租户端 存储 对象存储（COS） COS API参考 表单上传对象

表单上传对象

最近更新时间: 2025-02-18 16:02:00

功能描述

POST Object 接口请求允许使用者用表单的形式将文件（Object）上传至指定 Bucket 中。该操作需要请求者对 Bucket 有 WRITE 权限。所有由 HTTP 头部携带的 API 参数，都使用表单字段请求。

细节分析

  1. 需要有 Bucket 的写权限。
  2. 如果试图添加的 Object 的同名文件已经存在，那么新上传的文件，将覆盖原来的文件，成功时返回200 OK。

请求

请求示例

  • 复制
    复制成功
POST / HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Content-Length: length
Headers
Form

请求头

公共头部

该请求操作的实现使用公共请求头，了解公共请求头详情，请参阅 公共请求头部 文档。

非公共头部

该请求操作需要用到如下必选请求头：

名称描述类型必选
Content-LengthRFC 2616中定义的 HTTP 请求内容长度（字节）String是

表单字段

名称描述类型必选
acl定义 Object 的 ACL 属性，
有效值：private，public-read，default；
默认值：default(继承 Bucket 权限)；
注意：当前访问策略条目限制为1000条，如果您不需要进行 Object ACL 控制，请填 default 或者此项不进行设置，默认继承 Bucket 权限		String否
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, ExpiresRFC 2616 中定义的头部，详见 文档String否
file文件内容，作为表单的最后一个字段String是
key上传后的文件名，使用 ${filename} 则会进行替换，例如a/b/${filename}，上传文件 photo.jpg，那么最终的上传路径就是 a/b/photo.jpgString是
x-cos-meta-*包括用户自定义头部后缀和用户自定义头部信息，将作为 Object 元数据返回，大小限制为2KB。
注意：用户自定义头部信息支持下划线，但用户自定义头部后缀不支持下划线		String否
policyBase64 编码。用于做请求检查，如果请求的内容和 Policy 指定的条件不符，返回 403 AccessDeniedString否

签名保护

当发起一个表单上传 HTTP POST 请求需要签名保护时，表单需要包含以下的内容结构 form-data 的内容：

表单字段描述
policy经过 Base64 加密的策略内容，策略内容将用于对请求内容的检查。如果请求内容与策略指定条件不符，则请求将被拒绝。
q-sign-algorithm用于计算签名的算法，COS目前支持SHA1，此处填写小写 `sha1`。
q-ak账户密钥 ID，即 SecretId
q-key-time用于请求签名的密钥有效起止时间，通过 Unix 时间戳描述起始和结束时间，以秒为单位，格式为 [start-seconds];[end-seconds]。例如`1480932292;1481012298`
q-signature使用上述元素计算的请求签名，COS 将会使用表单元素与签名内容做校验，若签名与所签内容不一致，则请求将被拒绝

签名计算

签名 q-signature 的计算分为三个步骤：

  1. 使用密钥内容对 q-key-time 的时间加密计算值 SignKey。
  2. 创建一个 POST 请求 policy 并将内容进行 sha1 加密，得到 StringToSign。
  3. 使用 SignKey 对 StringToSign 进行加密，生成签名 Signature。

Policy

以下是一个完整的 policy 示例：

  • 复制
    复制成功
{ "expiration": "2007-12-01T12:00:00.000Z",
  "conditions": [
    {"acl": "public-read" },
    {"bucket": "examplebucket-1250000000" },
    ["starts-with", "$key", "user/eric/"],
    {"q-sign-algorithm": "sha1" },
    {"q-ak": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
    {"q-sign-time": "1480932292;1481012298" }
  ]
}

Expiration 设置该 POST Policy 的超时时间，使用 ISO8601 GMT 时间，例如 2017-12-01T12:00:00.000Z。

Conditions 规则

类型描述
完全匹配使用`{"key": "value"}`或`["eq", "$key", "value"]`方式表达
前缀匹配使用`["starts-with", "$key", "value"]`方式表达，value 可留空
范围匹配仅用于`["content-length-range", int1, int2]`则文件字节数必须在 int1 和 int2 范围内

Conditions 参数 所有参数均为非必选，不填可以不校验。

名称描述匹配方式
acl文件 ACL 属性的许可范围，可不填完全、前缀
bucket指定上传的 Bucket完全
content-length-range指定文件的上传大小范围范围
key对象的存储路径完全、前缀
x-cos-meta-\*包括用户自定义头部后缀和用户自定义头部信息，将作为 Object 元数据返回，大小限制为 2KB
注意：用户自定义头部信息支持下划线，但用户自定义头部后缀不支持下划线		完全、前缀
x-cos-\*其他需要签署的 COS 头部完全

响应

响应头

公共响应头

该响应使用公共响应头，了解公共响应头详情，请参阅 公共响应头部 文档。

响应参数

名称描述类型
ETag返回文件的 MD5 算法校验值。ETag 的值可以用于检查 Object 在上传过程中是否有损坏String

响应体

该响应体返回为 application/xml 数据，包含完整节点数据的内容展示如下：

  • 复制
    复制成功
<PostResponse>
        <Location>http://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/photo.jpg</Location>
        <Bucket>examplebucket-1250000000</Bucket>
        <Key>photo.jpg</Key>
        <ETag>d41d8cd98f00b204e9800998ecf8427e</ETag>
</PostResponse>

具体的数据描述如下：

节点名称（关键字）父节点描述类型必选
PostResponse无保存 POST Object 结果的容器Container是

Container 节点 PostResponse 的内容：

节点名称（关键字）父节点描述类型必选
LocationPostResponse对象的完整路径String是
BucketPostResponse对象所在的存储桶String是
KeyPostResponse对象 key 名String是
ETagPostResponseEtag 内容String是

错误码

以下描述此请求可能会发生的一些特殊的且常见的错误情况。关于 COS 更多的错误码信息，请查阅 错误码 文档。

错误码HTTP 状态码描述
InvalidDigest400 Bad Request如果用户上传文件时携带 Content-MD5 头部，COS 会校验 body 的 Md5 和用户携带的 MD5 是否一致，如果不一致将返回 InvalidDigest
KeyTooLong400 Bad Request上传文件时携带的以 x-cos-meta 开头的自定义头部，每个自定义头部的 key 和 value 加起来不能超过4k，否则返回 KeyTooLong 错误
MissingContentLength411 Length Required如果上传文件时，没有添加 Content-Length 头部，会返回该错误码
NoSuchBucket404 Not Found如果试图添加的 Object 所在的 Bucket 不存在，返回 404 Not Found 错误，错误码：NoSuchBucket
EntityTooLarge400 Bad Request如果添加的文件长度超过5G，会返回 EntityTooLarge，并返回错误信息`“Your proposed upload exceeds the maximum allowed object size”`
InvalidURI400 Bad Request对象 key 长度限制为850，如果超过850会返回 InvalidURI

实际案例

请求

  • 复制
    复制成功
POST / HTTP/1.1
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: python-requests/2.12.4
Host: <BucketName-APPID>.<Endpoint>
Content-Length: 1352
Content-Type: multipart/form-data; boundary=e07f2a7876ae4755ae18d300807ad879

--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="key"

a/${filename}
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="Acl"

public-read
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="Signature"

q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1512983814;1512984814&q-key-time=1512983814;1512984814&q-url-param-list=&q-header-list=host&q-signature=2ffd2ae714e7445a8da000ec5d51771ff5056500
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="policy"

eyJjb25kaXRpb25zIjogW3siYnVja2V0IjogImtpdG1hbnMzdGVzdDEifSwgWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwMDAwMDAwXSwgWyJzdGFydHMtd2l0aCIsICJ4LWNvcy1tZXRhLWJiIiwgIjEyIl1dLCAiZXhwaXJhdGlvbiI6ICIyMDQ3LTEyLTAxVDEyOjAwOjAwLjAwMFoifQ==
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="x-Cos-meta-bb"

124
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="key1"

1
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="file"; filename="empty:a"


--e07f2a7876ae4755ae18d300807ad879--

响应

  • 复制
    复制成功
HTTP/1.1 204
Content-Type: application/xml
Content-Length: 232
Connection: keep-alive
Date: Mon, 11 Dec 2017 09:16:56 GMT
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Location: http://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/photo.jpg
Server: tencent-cos
x-cos-request-id: NWEyZTRkMDZfMjQ4OGY3MGFfNTE4Yl81