有奖:语音产品征文挑战赛等你来> HOT

功能描述

PUT Object 接口请求可以将本地的对象(Object)上传至指定存储桶中,该 API 的请求者需要对存储桶有写入权限。若无权限请参见 设置访问权限。如想以网页表单(HTML Form)的形式上传至指定存储桶中,请使用 POST Object


注意事项

PUT Object 接口最大支持上传 5GB 文件。如需上传大于 5GB 的文件,请使用 分块上传 的 API 接口。
请求头的 Content-Length 值小于实际请求体(body)中传输的数据长度,COS 仍将成功创建文件,但对象大小只等于 Content-Length 中定义的大小,其他数据将被丢弃。
对象存储中本身没有文件夹和目录的概念,将对象上传到指定的文件夹或路径,通过/实现。
对象键设置为 doc/picture.png,表示将 picture.png 对象上传到 doc 文件夹。
对象键设置为 doc/,表示创建一个名为 doc 的文件夹。更多说明请参见 文件夹和目录
如果试图添加已存在的同名对象,则新上传的对象将覆盖原来的对象,成功时返回200 OK。若要求不覆盖之前版本,需打开版本控制,详情请参见 版本控制
启用存储桶版本控制 :上传对象时,对象存储将自动为要添加的对象生成唯一的版本 ID,且响应头部在响应中返回 x-cos-version-id 标识。
暂停存储桶版本控制 :上传对象时,对象存储始终将 null 用作在存储桶中的对象版本 ID,且响应头部在响应中不返回 x-cos-version-id 标识。

授权说明

在您进行 授权策略 时,action 需要设置为 cos:PutObject ,示例如下。
{
"version": "2.0",
"statement": [
{
"action": [
"name/cos:PutObject"
],
"effect": "allow",
"resource": [
"qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
]
}
]
}
对象存储的更多 action,请参见支持CAM的业务接口

请求

请求语法

PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: Content Type
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String

[Object Content]
说明
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com,其中 <BucketName-APPID> 为带 APPID 后缀的存储桶名字,例如 examplebucket-1250000000,可参阅 存储桶概览 > 基本信息存储桶概述 > 存储桶命名规范 文档;<Region> 为 COS 的可用地域,可参阅 地域和访问域名 文档。
Authorization: Auth String(详情请参见 请求签名 文档)。

请求参数

此接口无请求参数。

请求头

此接口除使用公共请求头部外,还支持以下请求头部,了解公共请求头部详情请参见 公共请求头部 文档。

常规请求头

名称
描述
类型
是否必选
Cache-Control
RFC 2616 中定义的缓存指令,将作为对象元数据保存。
string
Content-Disposition
RFC 2616 中定义的文件名称,将作为对象元数据保存。
例如:
inline:直接预览文件内容。
attachment:以原文件名的形式下载到浏览器指定路径。
attachment; filename="FileName":以自定义文件名的形式下载到浏览器指定路径。FileName 用于自定义下载后的文件名称,例如 example.jpg。
string
Content-Encoding
RFC 2616 中定义的编码格式,将作为对象元数据保存。
string
Content-Type
RFC 2616 中定义的 HTTP 请求内容类型(MIME),此头部用于描述待上传对象的内容类型,将作为对象元数据保存。
例如:application/xml 或 image/jpeg
string
Expires
RFC 2616 中定义的缓存失效时间,是绝对日期和时间,将作为对象元数据保存。
string
Transfer-Encoding
RFC 2616 中定义的传输编码格式,如果希望在上传时分块传输,则指定 Transfer-Encoding: chunked 请求头部,不能指定 Content-Length 请求头部。
string

专用请求头

在上传对象时可以通过指定下列请求头部来设置对象的元数据、存储类型、流量控制、标签:
名称
描述
类型
是否必选
x-cos-meta-*
用户自定义元数据头部后缀和用户自定义元数据信息,将作为对象元数据保存,用于对象自定义管理。没有数量限制,单条大小限制为 2KB。例如x-cos-meta-test: test metadata
注意:用户自定义元数据信息支持下划线(_),但用户自定义元数据头部后缀仅支持减号(-)
string
x-cos-storage-class
对象存储类型,默认值为 STANDARD。枚举值请参见 存储类型概述 文档,
参考值有:
STANDARD:标准存储
STANDARD_IA:低频存储
ARCHIVE:归档存储
DEEP_ARCHIVE:深度归档存储
MAZ_STANDARD:标准存储(多 AZ)
MAZ_STANDARD_IA:低频存储(多 AZ)
INTELLIGENT_TIERING:智能分层存储
MAZ_INTELLIGENT_TIERING:智能分层存储(多 AZ)
enum
x-cos-traffic-limit
针对本次上传进行流量控制的限速值,必须为数字,单位默认为 bit/s。限速值设置范围为819200 - 838860800,即800Kb/s - 800Mb/s,如果超出该范围将返回400错误
integer
x-cos-tagging
对象的标签集合,最多可设置10个标签(例如,Key1=Value1&Key2=Value2)。 标签集合中的 Key 和 Value 必须先进行 URL 编码。
string

访问控制列表(ACL)请求头

在上传对象时可以通过指定下列请求头部来设置对象的访问权限:
名称
描述
类型
是否必选
x-cos-acl
定义对象的访问控制列表(ACL)属性。默认为 default。枚举值请参见 ACL 概述 文档中对象的预设 ACL 部分。
参考值有:
default:继承权限
private:私有读写
public-read :公有读私有写
注意:如果您不需要进行对象 ACL 控制,请设置为 default 或者此项不进行设置,默认继承存储桶权限。
enum
x-cos-grant-read
赋予被授权者读取对象的权限,格式为 id="[OwnerUin]",例如 id="100000000001",可使用半角逗号(,)分隔多组被授权者,例如id="100000000001",id="100000000002"
string
x-cos-grant-read-acp
赋予被授权者读取对象的访问控制列表(ACL)的权限,格式为 id="[OwnerUin]",例如 id="100000000001",可使用半角逗号(,)分隔多组被授权者,例如id="100000000001",id="100000000002"
string
x-cos-grant-write-acp
赋予被授权者写入对象的访问控制列表(ACL)的权限,格式为 id="[OwnerUin]",例如 id="100000000001",可使用半角逗号(,)分隔多组被授权者,例如id="100000000001",id="100000000002"
string
x-cos-grant-full-control
赋予被授权者操作对象的所有权限,格式为 id="[OwnerUin]",例如 id="100000000001",可使用半角逗号(,)分隔多组被授权者,例如id="100000000001",id="100000000002"
string

服务端加密(SSE)请求头

在上传对象时可以通过指定 服务端加密专用头部 来设置服务端加密。不设置默认为不加密。

请求体

此接口请求的请求体为对象(文件)内容。

响应

响应头

此接口除返回公共响应头部外,还返回以下响应头部,了解公共响应头部详情请参见 公共响应头部 文档。

版本控制相关头部

在启用版本控制的存储桶中上传对象,将返回下列响应头部。设置版本控制权限,详情请参见 版本控制
名称
描述
类型
x-cos-version-id
对象的版本 ID
string

服务端加密(SSE)相关头部

如果在上传对象时使用了服务端加密,则此接口将返回服务端加密专用头部,请参见 服务端加密专用头部

响应体

此接口响应体为空。

使用案例

注意:
API explorer 中会将常用且有功能的请求头部作为输入参数使用,使用时请留意。

错误码

此接口遵循统一的错误响应和错误码,详情请参见 错误码 文档。

附录:PUT Object 接口对应各语言的 SDK

SDK
文档链接
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
小程序 SDK