PUT Object

最后更新时间:2020-11-19 10:42:16

    功能描述

    PUT Object 接口请求可以将本地的对象(Object)上传至指定存储桶中。该 API 的请求者需要对存储桶有写入权限。

    说明:

    • PUT Object 接口最大支持上传5GB文件。如需上传大于5GB的文件,请使用 分块上传 的 API 接口。
    • 如果请求头的 Content-Length 值小于实际请求体(body)中传输的数据长度,COS 仍将成功创建文件,但对象大小只等于 Content-Length 中定义的大小,其他数据将被丢弃。
    • 如果试图添加已存在的同名对象且没有启用版本控制,则新上传的对象将覆盖原来的对象,成功时返回200 OK。

    版本控制

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

    请求

    请求示例

    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]

    说明:

    Authorization: Auth String (详情请参见 请求签名 文档)。

    请求参数

    此接口无请求参数。

    请求头

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

    名称 描述 类型 是否必选
    Cache-Control RFC 2616 中定义的缓存指令,将作为对象元数据保存 string
    Content-Disposition RFC 2616 中定义的文件名称,将作为对象元数据保存 string
    Content-Encoding RFC 2616 中定义的编码格式,将作为对象元数据保存 string
    Content-Type RFC 2616 中定义的 HTTP 请求内容类型(MIME),此头部用于描述待上传对象的内容类型,将作为对象元数据保存。
    例如text/htmlimage/jpeg
    string
    Expires RFC 2616 中定义的缓存失效时间,将作为对象元数据保存 string
    Transfer-Encoding 如果希望在上传时分块传输,则指定 Transfer-Encoding: chunked 请求头部,此时请求体遵循 RFC 2616 中定义的传输编码格式,且不能指定 Content-Length 请求头部 string
    x-cos-meta-* 包括用户自定义元数据头部后缀和用户自定义元数据信息,将作为对象元数据保存,大小限制为2KB
    注意:用户自定义元数据信息支持下划线(_),但用户自定义元数据头部后缀不支持下划线,仅支持减号(-)
    string
    x-cos-storage-class 对象存储类型。枚举值请参见 存储类型 文档,例如 MAZ_STANDARD,MAZ_STANDARD_IA,INTELLIGENT_TIERING,MAZ_INTELLIGENT_TIERING,STANDARD_IA,ARCHIVE,DEEP_ARCHIVE。默认值:STANDARD Enum
    x-cos-traffic-limit 针对本次上传进行流量控制的限速值,必须为数字,单位默认为 bit/s。限速值设置范围为819200 - 838860800,即100KB/s - 100MB/s,如果超出该范围将返回400错误 integer
    x-cos-tagging 对象的标签集合,最多可设置10个标签(例如,Key1=Value1&Key2=Value2)。 标签集合中的 Key 和 Value 必须先进行 URL 编码。 string

    访问控制列表(ACL)相关头部

    在上传对象时可以通过指定下列请求头部来设置对象的访问权限:

    名称 描述 类型 是否必选
    x-cos-acl 定义对象的访问控制列表(ACL)属性。枚举值请参见 ACL 概述 文档中对象的预设 ACL 部分,例如 default,private,public-read 等,默认为 default
    注意:当前访问策略条目限制为1000条,如果您不需要进行对象 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)相关头部

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

    响应体

    此接口响应体为空。

    错误码

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

    实际案例

    案例一:简单案例(未启用版本控制)

    请求

    PUT /exampleobject HTTP/1.1
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    Date: Fri, 10 Apr 2020 09:35:05 GMT
    Content-Type: image/jpeg
    Content-Length: 16
    Content-MD5: 7o3pGNBWQBRbGPcPTDqmAg==
    Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511305;1586518505&q-key-time=1586511305;1586518505&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=&q-signature=c4147d4d457869a49b13e8e936c06a12c809****
    Connection: close
    
    [Object Content]

    响应

    HTTP/1.1 200 OK
    Content-Length: 0
    Connection: close
    Date: Fri, 10 Apr 2020 09:35:05 GMT
    ETag: "ee8de918d05640145b18f70f4c3aa602"
    Server: tencent-cos
    x-cos-hash-crc64ecma: 16749565679157681890
    x-cos-request-id: NWU5MDNkYzlfNjRiODJhMDlfMzFmYzhfMTFm****

    案例二:使用请求头部指定元数据和 ACL

    请求

    PUT /exampleobject HTTP/1.1
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    Date: Fri, 10 Apr 2020 09:35:28 GMT
    Content-Type: image/jpeg
    Cache-Control: max-age=86400
    Content-Disposition: attachment; filename=example.jpg
    x-cos-meta-example-field: example-value
    x-cos-acl: public-read
    Content-Length: 16
    Content-MD5: 7o3pGNBWQBRbGPcPTDqmAg==
    Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511328;1586518528&q-key-time=1586511328;1586518528&q-header-list=cache-control;content-disposition;content-length;content-md5;content-type;date;host;x-cos-acl;x-cos-meta-example-field&q-url-param-list=&q-signature=20d0cd79060cec8c560ebd239738626726f4****
    Connection: close
    
    [Object Content]

    响应

    HTTP/1.1 200 OK
    Content-Length: 0
    Connection: close
    Date: Fri, 10 Apr 2020 09:35:28 GMT
    ETag: "ee8de918d05640145b18f70f4c3aa602"
    Server: tencent-cos
    x-cos-hash-crc64ecma: 16749565679157681890
    x-cos-request-id: NWU5MDNkZTBfZjhjMDBiMDlfNzdmN18xMGFi****

    案例三:使用服务端加密 SSE-COS

    请求

    PUT /exampleobject HTTP/1.1
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    Date: Fri, 10 Apr 2020 09:35:49 GMT
    Content-Type: image/jpeg
    x-cos-server-side-encryption: AES256
    Content-Length: 16
    Content-MD5: 7o3pGNBWQBRbGPcPTDqmAg==
    Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511349;1586518549&q-key-time=1586511349;1586518549&q-header-list=content-length;content-md5;content-type;date;host;x-cos-server-side-encryption&q-url-param-list=&q-signature=35145bc61ae490c4959b58bc6d27b3258bf7****
    Connection: close
    
    [Object Content]

    响应

    HTTP/1.1 200 OK
    Content-Length: 0
    Connection: close
    Date: Fri, 10 Apr 2020 09:35:49 GMT
    ETag: "ee8de918d05640145b18f70f4c3aa602"
    Server: tencent-cos
    x-cos-hash-crc64ecma: 16749565679157681890
    x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****
    x-cos-server-side-encryption: AES256

    案例四:使用服务端加密 SSE-KMS

    请求

    PUT /exampleobject HTTP/1.1
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    Date: Fri, 10 Apr 2020 09:36:00 GMT
    Content-Type: image/jpeg
    x-cos-server-side-encryption: cos/kms
    x-cos-server-side-encryption-cos-kms-key-id: 48ba38aa-26c5-11ea-855c-52540085****
    x-cos-server-side-encryption-context: eyJhdXRob3IiOiJmeXNudGlhbiIsImNvbXBhbnkiOiJUZW5jZW50In0=
    Content-Length: 16
    Content-MD5: 7o3pGNBWQBRbGPcPTDqmAg==
    Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511360;1586518560&q-key-time=1586511360;1586518560&q-header-list=content-length;content-md5;content-type;date;host;x-cos-server-side-encryption;x-cos-server-side-encryption-context;x-cos-server-side-encryption-cos-kms-key-id&q-url-param-list=&q-signature=6cb5d6f0137bb1d87f5afe98c5289b0de375****
    Connection: close
    
    [Object Content]

    响应

    HTTP/1.1 200 OK
    Content-Length: 0
    Connection: close
    Date: Fri, 10 Apr 2020 09:36:01 GMT
    ETag: "840af7c921f4b3230049af8663145bd0"
    Server: tencent-cos
    x-cos-hash-crc64ecma: 16749565679157681890
    x-cos-request-id: NWU5MDNlMDFfOThjMjJhMDlfMjhhMl8xNTlm****
    x-cos-server-side-encryption: cos/kms
    x-cos-server-side-encryption-cos-kms-key-id: 48ba38aa-26c5-11ea-855c-52540085****
    

    案例五:使用服务端加密 SSE-C

    请求

    PUT /exampleobject HTTP/1.1
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    Date: Fri, 10 Apr 2020 09:36:12 GMT
    Content-Type: image/jpeg
    x-cos-server-side-encryption-customer-algorithm: AES256
    x-cos-server-side-encryption-customer-key: MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
    x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==
    Content-Length: 16
    Content-MD5: 7o3pGNBWQBRbGPcPTDqmAg==
    Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511372;1586518572&q-key-time=1586511372;1586518572&q-header-list=content-length;content-md5;content-type;date;host;x-cos-server-side-encryption-customer-algorithm;x-cos-server-side-encryption-customer-key;x-cos-server-side-encryption-customer-key-md5&q-url-param-list=&q-signature=4f6f9f0a6700930f70bff31e3a2b2e622711****
    Connection: close
    
    [Object Content]
    

    响应

    HTTP/1.1 200 OK
    Content-Length: 0
    Connection: close
    Date: Fri, 10 Apr 2020 09:36:13 GMT
    ETag: "582d9105f71525f3c161984bc005efb5"
    Server: tencent-cos
    x-cos-hash-crc64ecma: 16749565679157681890
    x-cos-request-id: NWU5MDNlMGNfZTFjODJhMDlfMzVlMDFfZTk1****
    x-cos-server-side-encryption-customer-algorithm: AES256
    x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==

    案例六:启用版本控制

    请求

    PUT /exampleobject HTTP/1.1
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    Date: Fri, 10 Apr 2020 09:36:34 GMT
    Content-Type: image/jpeg
    Content-Length: 16
    Content-MD5: 7o3pGNBWQBRbGPcPTDqmAg==
    Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511394;1586518594&q-key-time=1586511394;1586518594&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=&q-signature=371f555ec81751e1dbf38927e568af4cc67a****
    Connection: close
    
    [Object Content]

    响应

    HTTP/1.1 200 OK
    Content-Length: 0
    Connection: close
    Date: Fri, 10 Apr 2020 09:36:35 GMT
    ETag: "ee8de918d05640145b18f70f4c3aa602"
    Server: tencent-cos
    x-cos-hash-crc64ecma: 16749565679157681890
    x-cos-request-id: NWU5MDNlMjNfMThiODJhMDlfNGQ1OF8xMWY4****
    x-cos-version-id: MTg0NDUxNTc1NjIzMTQ1MDAwODg

    案例七:暂停版本控制

    请求

    PUT /exampleobject HTTP/1.1
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    Date: Fri, 10 Apr 2020 09:37:07 GMT
    Content-Type: image/jpeg
    Content-Length: 16
    Content-MD5: 7o3pGNBWQBRbGPcPTDqmAg==
    Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511427;1586518627&q-key-time=1586511427;1586518627&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=&q-signature=0747f6508fca37dfb5c91bbe3fa01f91b326****
    Connection: close
    
    [Object Content]

    响应

    HTTP/1.1 200 OK
    Content-Length: 0
    Connection: close
    Date: Fri, 10 Apr 2020 09:37:07 GMT
    ETag: "ee8de918d05640145b18f70f4c3aa602"
    Server: tencent-cos
    x-cos-hash-crc64ecma: 16749565679157681890
    x-cos-request-id: NWU5MDNlNDNfZTZjNzJhMDlfMmYwMDlfMTVi****

    案例八:使用 chunked 传输编码分块传输

    本案例请求中使用 Transfer-Encoding: chunked 编码,案例描述的是 HTTP 请求中的原始数据,在使用过程中根据不同语言和库将有不同的调用方法,请开发者查阅语言和库的相关文档。

    请求

    PUT /exampleobject HTTP/1.1
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    Date: Thu, 08 Aug 2019 09:15:29 GMT
    Content-Type: text/plain
    Transfer-Encoding: chunked
    Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1565255729;1565262929&q-key-time=1565255729;1565262929&q-header-list=content-type;date;host;transfer-encoding&q-url-param-list=&q-signature=0b05b6bda75afbc159caa0da4e4051ec6939****
    Connection: close
    
    11
    [Chunked Content]
    b
    [2nd chunk]
    b
    [3rd chunk]
    b
    [4th chunk]
    0

    响应

    HTTP/1.1 200 OK
    Content-Length: 0
    Connection: close
    Date: Thu, 08 Aug 2019 09:15:29 GMT
    ETag: "aa488bb80185a6be87f4a7b936a80752"
    Server: tencent-cos
    x-cos-hash-crc64ecma: 7188322482464764960
    x-cos-request-id: NWQ0YmU4MzFfNzFiNDBiMDlfMWJhYTlfMTY2Njll****

    Was this page helpful?

    本页内容是否解决了您的问题?

    • 完全没帮助
    • 文档较差
    • 文档一般
    • 文档不错
    • 文档很好
    反馈
    帮助