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

功能描述

POST Object 接口请求可以将本地不超过5GB的对象(Object)以网页表单(HTML Form)的形式上传至指定存储桶中。该 API 的请求者需要对存储桶有写入权限。
注意
POST Object 接口不使用 COS 对象存储统一的请求签名,而是拥有自己的签名要求,请参见本文档的 签名保护 及相关字段的描述。
如果试图添加已存在的同名对象且没有启用版本控制,则新上传的对象将覆盖原来的对象,成功时按照指定的返回方式正常返回。
上传图片时,请参见 PUT Object 接口,可参考代码示例进行数据填充。


授权说明

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

版本控制

如果对存储桶启用版本控制,对象存储将自动为要添加的对象生成唯一的版本 ID。对象存储使用 x-cos-version-id 响应头部在响应中返回此标识。
如果暂停存储桶的版本控制,则对象存储始终将 null 用作存储在存储桶中的对象的版本 ID,且不返回 x-cos-version-id 响应头部。

请求

请求示例

POST / HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: multipart/form-data; boundary=Multipart Boundary
Content-Length: Content Length



[Multipart Form Data]
说明
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com,其中 <BucketName-APPID> 为带 APPID 后缀的存储桶名字,例如 examplebucket-1250000000,可参阅 存储桶概览 > 基本信息存储桶概述 > 存储桶命名规范 文档;<Region> 为 COS 的可用地域,可参阅 地域和访问域名 文档。

请求表单

此接口请求体通过 multipart/form-data 编码,在 HTML 网页中通过 <form> 元素发送请求时,需将 <form> 元素的 enctype 属性设置为 multipart/form-data,随后使用 HTML 表单元素(例如 <input>、<select> 等)添加所需表单字段。

表单字段

名称
描述
类型
是否必选
key
对象键,可在对象键中指定${filename}通配符,此时将使用实际上传的文件的文件名替换对象键中的通配符,相关示例请参见本文档的 案例七
string
Cache-Control
RFC 2616 中定义的缓存指令,将作为对象元数据保存
string
Content-Disposition
RFC 2616 中定义的文件名称,将作为对象元数据保存
string
Content-Encoding
RFC 2616 中定义的编码格式,将作为对象元数据保存
string
Content-Type
RFC 2616 中定义的 HTTP 内容类型(MIME),将作为对象元数据保存
注意:通过网页表单上传文件时,浏览器会自动把指定文件的 MIME 类型携带在请求中,但对象存储 COS 并不会使用浏览器携带的 MIME 类型,您需要显式指定 Content-Type 表单字段作为对象的内容类型
string
Expires
RFC 2616 中定义的缓存失效时间,将作为对象元数据保存
string
success_action_redirect
上传成功时重定向的目标 URL 地址,如果设置,那么在上传成功时将返回 HTTP 状态码为303(Redirect)及 Location 响应头部,Location 响应头部的值为该字段指定的 URL 地址,并附加 bucket、key 和 etag 参数,相关示例请参见本文档的 案例八
string
success_action_status
上传成功时返回的 HTTP 状态码,可选200、201或204,默认为204。如果指定了 success_action_redirect 字段,则此字段会被忽略。相关示例请参见本文档的 案例九
number
x-cos-meta-*
包括用户自定义元数据头部后缀和用户自定义元数据信息,将作为对象元数据保存,大小限制为2KB
注意:用户自定义元数据信息支持下划线(_),但用户自定义元数据头部后缀不支持下划线,仅支持减号(-)
string
x-cos-storage-class
对象存储类型。枚举值请参见 存储类型 文档,例如 MAZ_STANDARD、MAZ_STANDARD_IA、INTELLIGENT_TIERING、MAZ_INTELLIGENT_TIERING、STANDARD_IA、ARCHIVE、DEEP_ARCHIVE。默认值:如果是单 AZ 存储桶,则默认为 STANDARD;如果是多 AZ 存储桶,则默认为 MAZ_STANDARD
Enum
x-cos-traffic-limit
针对本次上传进行流量控制的限速值,必须为数字,单位默认为 bit/s。限速值设置范围为819200 - 838860800,即800Kb/s-800Mb/s,如果超出该范围将返回400错误
integer
Content-MD5
经过 Base64 编码的文件内容 MD5 哈希值,用于完整性检查,验证文件内容在传输过程中是否发生变化
string
file
文件的信息和内容,通过网页表单上传时,浏览器将自动设置该字段的值为正确的格式
注意:file 字段必须放在整个表单的最后面。
file

访问控制列表(ACL)相关表单字段

在上传对象时可以通过指定下列表单字段来设置对象的访问权限:
名称
描述
类型
是否必选
acl
定义对象的访问控制列表(ACL)属性。枚举值请参见 ACL 概述 文档中对象的预设 ACL 部分,例如 default,private,public-read 等,默认为 default
注意:如果您不需要进行对象 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-server-side-encryption
服务端加密算法,支持 AES256、cos/kms
string
使用 SSE-COS 或 SSE-KMS 时,此字段为必选项
x-cos-server-side-encryption-customer-algorithm
服务端加密算法,支持 AES256
string
使用 SSE-C 时,此字段为必选项
x-cos-server-side-encryption-cos-kms-key-id
当 x-cos-server-side-encryption 值为 cos/kms 时,用于指定 kms 的用户主密钥 CMK,如不指定则使用 COS 默认创建的 CMK,更多详细信息可参见 SSE-KMS 加密
string
x-cos-server-side-encryption-context
当 x-cos-server-side-encryption 值为 cos/kms 时,用于指定加密上下文,值为 JSON 格式加密上下文键值对的 Base64 编码
例如eyJhIjoiYXNkZmEiLCJiIjoiMTIzMzIxIn0=
string
x-cos-server-side-encryption-customer-key
服务端加密密钥的 Base64 编码
例如MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
string
使用 SSE-C 时,此字段为必选项
x-cos-server-side-encryption-customer-key-MD5
服务端加密密钥的 MD5 哈希值,使用 Base64 编码
例如U5L61r7jcwdNvT7frmUG8g==
string
使用 SSE-C 时,此字段为必选项

签名保护

POST Object 接口要求在请求中携带签名相关字段,COS 服务器端收到消息后,进行身份验证,验证成功则可接受并执行请求,否则将会返回错误信息并丢弃此请求。
签名流程如下:

响应

响应头

此接口除返回公共响应头部外,还返回以下响应头部,了解公共响应头部详情请参见 公共响应头部 文档。
名称
描述
类型
Location
当使用 success_action_redirect 表单字段时,此响应头部的值为 success_action_redirect 指定的 URL 地址,并附加 bucket、key 和 etag 参数,相关示例请参见本文档的 案例八
当未使用 success_action_redirect 表单字段时,此响应头部的值为完整的对象访问 URL 地址,相关示例请参见本文档的 案例一
string

版本控制相关头部

在启用版本控制的存储桶中上传对象,将返回下列响应头部:
名称
描述
类型
x-cos-version-id
对象的版本 ID
string

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

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

响应体

此接口响应体为空。

错误码

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

使用案例

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