tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
对象存储
    文档
    Download PDF

    PUT Object

    最后更新时间：2024-09-26 16:50:11
    下载PDF

      功能描述

      PUT Object 接口请求可以将本地的对象（Object）上传至指定存储桶中。该 API 的请求者需要对存储桶有写入权限。
      说明
      PUT Object 接口最大支持上传5GB文件。如需上传大于5GB的文件，请使用 分块上传 的 API 接口。
      如果请求头的 Content-Length 值小于实际请求体（body）中传输的数据长度，COS 仍将成功创建文件，但对象大小只等于 Content-Length 中定义的大小，其他数据将被丢弃。
      如果试图添加已存在的同名对象且没有启用版本控制，则新上传的对象将覆盖原来的对象，成功时返回200 OK。
      对象存储中本身没有文件夹和目录的概念，如需将对象上传到指定的文件夹或路径，可通过/实现，例如将 picture.png 上传到 doc 文件夹，则对象键设置为 doc/picture.png；如需创建文件夹 doc，则对象键设置为 doc/。更多说明请参见 文件夹和目录。
      

      版本控制

      如果对存储桶启用版本控制，对象存储将自动为要添加的对象生成唯一的版本 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]
      说明
      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 中定义的文件名称，将作为对象元数据保存
      string
      否
      Content-Encoding
      RFC 2616 中定义的编码格式，将作为对象元数据保存
      string
      否
      Content-Type
      RFC 2616 中定义的 HTTP 请求内容类型（MIME），此头部用于描述待上传对象的内容类型，将作为对象元数据保存。
      例如text/html或image/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，即800Kb/s - 800Mb/s，如果超出该范围将返回400错误
      integer
      否
      x-cos-tagging
      对象的标签集合，最多可设置10个标签（例如，Key1=Value1&Key2=Value2）。 标签集合中的 Key 和 Value 必须先进行 URL 编码。
      string
      否
      x-cos-forbid-overwrite
      针对未开启版本控制的存储桶，上传文件时，用于指定上传操作时是否禁止覆盖同名对象：
      不携带 x-cos-forbid-overwrite 头部或指定为 false 时，默认覆盖同名 Object；
      指定 x-cos-forbid-overwrite 为 true 时，表示禁止覆盖同名 Object。
      注意：
      当存储桶处于已开启或已暂停的版本控制状态时，x-cos-forbid-overwrite 请求头部设置无效，即允许覆盖同名对象。
      string
      否
      访问控制列表（ACL）相关头部
      在上传对象时可以通过指定下列请求头部来设置对象的访问权限：
      名称
      描述
      类型
      是否必选
      x-cos-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-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****

      案例九：设置对象锁定

      请求

      PUT /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      x-cos-object-lock-retain-until-date: 2022-12-30T10:30:09.000Z
      x-cos-object-lock-mode: COMPLIANCE
      
      [Object Content]

      响应

      HTTP/1.1 200 OK
      Content-Length: 0
      Connection: close
      Date: Fri, 10 Apr 2020 09:35:05 GMT
      ETag: "ee8de918d05640145b18*****"
      Server: tencent-cos
      x-cos-hash-crc64ecma: 167495656791****
      x-cos-request-id: NWU5MDNkYzlfNjRiODJhMDlfMzFmYz********
      
      联系我们

      联系我们，为您的业务提供专属服务。

      联系我们
      技术支持

      如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

      提交工单
      7x24 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款