tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Cloud Object Storage
    Documentation
    Download PDF

    PUT Object

    Last updated: 2024-09-26 16:50:11
    Download PDF

      Function Description

      The PUT Object interface request facilitates the upload of local objects into a designated storage bucket. The requester of this API must possess write permissions for the storage bucket.
      Note:
      The PUT Object interface supports the uploading of a maximum of 5 GB files. For files larger than 5 GB, use the Multipart Upload API.
      If the Content-Length value in the request header is smaller than the actual data length transmitted in the request body, COS will still successfully create the file. However, the object size will only be equivalent to the size defined in Content-Length, and any additional data will be discarded.
      If an attempt is made to add an existing object with the same name without enabling version control, the newly uploaded object will overwrite the original object, returning a 200 OK message upon success.
      There is no concept of folders and directories in COS. To upload an object to a specific folder or path, you can use /. For instance, to upload picture.png to the doc folder, the object key should be set as doc/picture.png. To create a doc folder, the object key should be set as doc/. For more instructions, refer to Folder and directory.
      

      Version Control

      Upon the enabling of version control for a bucket, COS will automatically generate a unique version ID for the object to be added. This identifier is returned in the response via the x-cos-version-id response header by COS.
      If version control of the bucket is paused, COS will consistently use null as the version ID for the objects stored in the bucket, and it will not return the x-cos-version-id response header.

      Request

      Request Example

      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]
      Note:
      Host: <BucketName-APPID>.cos.<Region>.myqcloud.com. <BucketName-APPID> indicates the bucket name suffixed with APPID, for instance, examplebucket-1250000000. Refer to Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Conventions. <Region> indicates the available regions of COS, for which you can refer to Regions and Access Endpoints.
      Authorization: Auth String (for more details, refer to Request Signature).

      Request Parameters

      This interface does not require any request parameters.

      Request Headers

      In addition to common request headers, this interface also supports the following request headers. For detailed information on common request headers, refer to Common Request Headers.
      Name
      Description
      Type
      Mandatory
      Cache-Control
      Cache directive defined in RFC 2616, which will be preserved as object metadata.
      string
      No
      Content-Disposition
      File name defined in RFC 2616, which will be preserved as object metadata.
      string
      No
      Content-Encoding
      Encoding format defined in RFC 2616, which will be preserved as object metadata.
      string
      No
      Content-Type
      HTTP request content type (MIME) defined in RFC 2616. This header is used to describe the content type of the object to be uploaded, which will be preserved as object metadata. For instance, text/html or image/jpeg.
      string
      Yes
      Expires
      Cache expiration time defined in RFC 2616, which will be preserved as object metadata.
      string
      No
      Transfer-Encoding
      If you want to employ chunked transfer encoding during the upload process, specify the Transfer-Encoding: chunked request header. In this instance, the request body adheres to the transmission encoding format defined in RFC 2616, and the Content-Length request header cannot be specified.
      string
      No
      x-cos-meta-*
      User-defined metadata header suffixes and user-defined metadata information are stored as object metadata, with a size limit of 2 KB.
      Note: User-defined metadata information supports underscores (_). However, user-defined metadata header suffixes do not support underscores (_) and only support hyphens (-).
      string
      No
      x-cos-storage-class
      COS type. For details about the enumerated values, see Storage Class Overview, such as MAZ_STANDARD, MAZ_STANDARD_IA, INTELLIGENT_TIERING, MAZ_INTELLIGENT_TIERING, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE. Default value: STANDARD.
      enum
      No
      x-cos-traffic-limit
      Traffic control limit for this upload. The value must be a digit and the default unit is bit/s. The range is 819200-838860800, equating to 800 Kb/s - 800 Mb/s. Any value outside this range will result in a 400 error.
      integer
      No
      x-cos-tagging
      Collection of object tags. A maximum of 10 tags can be set (for instance, Key1=Value1&Key2=Value2). Both Key and Value in the tag collection must be URL encoded in advance.
      string
      No
      x-cos-forbid-overwrite
      For a bucket which has never enabled versioning, you may use it to specify whether to prohibit overwriting the object with the same name when uploading the object:
      When the x-cos-forbid-overwrite header is not specified or specified as false, the object with the same name will be overwritten by default;
      When the x-cos-forbid-overwrite is specified as true, overwriting the object with the same name will be prohibited.
      Note：
      For a bucket which has enabled versioning or suspended versioning, the x-cos-forbid-overwrite request header is invalid, which means overwriting objects with the same name is allowed whether the x-cos-forbid-overwrite request header is specified as true or false.
      string
      Not required
      ACL-related Headers
      During the uploading of an object, you can set the access permission on the object by specifying the following request headers:
      Name
      Description
      Type
      Mandatory
      x-cos-acl
      Defines the access control list (ACL) attributes of the object. For enumerated values, refer to the preset ACL section in ACL, such as default, private, public-read. The default value is default.
      Note: If you do not require object ACL control, set this parameter to default or leave this parameter unset, which means that by default the permissions of the bucket will be inherited.
      enum
      No
      x-cos-grant-read
      Grants the authorized party the permission to read the object. The format is id="[OwnerUin]", for instance, id="100000000001". Multiple authorized parties can be separated by commas (,), for example, id="100000000001",id="100000000002".
      string
      No
      x-cos-grant-read-acp
      Grants the authorized party the permission to read the ACL of the object. The format is id="[OwnerUin]", for instance, id="100000000001". Multiple authorized parties can be separated by commas (,), such as id="100000000001",id="100000000002".
      string
      No
      x-cos-grant-write-acp
      Grants the authorized party the permission to write data into the ACL of the object. The format is id="[OwnerUin]", for instance, id="100000000001". Multiple authorized parties can be separated by commas (,), such as id="100000000001",id="100000000002".
      string
      No
      x-cos-grant-full-control
      Grants all permissions on the object to the authorized party. The format is id="[OwnerUin]", for instance, id="100000000001". Multiple authorized parties can be separated by commas (,), such as id="100000000001";id="100000000002".
      string
      No
      SSE-related Headers
      When uploading an object, server-side encryption (SSE) can be used. Refer to Server-Side Encryption Headers.
      Object Lock-related Headers
      Object lock can be employed during the uploading of an object. Refer to the dedicated headers for object lock.

      Request Body

      The request body for this interface consists of the object (file) content.

      Response

      Response Headers

      In addition to common response headers, this interface also returns the following response headers. For details on common response headers, refer to Common Response Headers.
      Version Control-related Headers
      When uploading an object in a bucket with version control enabled, the following response headers will be returned:
      Name
      Description
      Type
      x-cos-version-id
      Object's version ID.
      string
      SSE-related Headers
      If SSE is used during object uploading, this interface will return dedicated headers for SSE. Refer to Server-Side Encryption Headers.

      Response Body

      The response body is empty.

      Error Codes

      This interface adheres to unified error responses and error codes. For details, refer to Error Codes.

      Examples

      Example 1: Simple Example (Version Control Not Enabled)

      Request

      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]
      

      Response

      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****

      Example 2: Specifying Metadata and ACL Using Request Headers

      Request

      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]

      Response

      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****

      Example 3: Using SSE-COS

      Request

      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]

      Response

      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

      Example 4: Using SSE-KMS

      Request

      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]

      Response

      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****

      Example 5: Using SSE-C

      Request

      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]
      

      Response

      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==

      Example 6: Enabling Version Control

      Request

      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]

      Response

      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

      Example 7: Suspending Version Control

      Request

      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]

      Response

      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****

      Example 8: Using Chunked Transfer Encoding for Segmented Transmission

      This example uses the Transfer-Encoding: chunked encoding. This example illustrates the raw data in an HTTP request. During the application, different invocation methods will be employed depending on the language and library in use. Developers are advised to consult the relevant documentation of the language and library.

      Request

      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

      Response

      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****

      Example 9: Configuring Object Lock

      Request

      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]

      Response

      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********
      
      Contact Us

      Contact our sales team or business advisors to help your business.

      Contact Us
      Technical Support

      Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy