PUT Object

Last updated: 2020-07-06 15:26:52

    Feature

    This API is used to upload a local object to the specified bucket. To make this request, you need to have the permission to write to the bucket.

    • This API supports uploading up to 5 GB files. To upload larger files, please use the Multipart Upload API.
    • If the Content-Length is less than the actual length of request body, COS will create an object with the size as specified in Content-Length, but with the excessive data discarded.
    • If you upload an object whose name already exists in an bucket without versioning enabled, the old object will be overwritten by the new one and 200 OK will be returned upon success.

    Versioning

    • If versioning is enabled for the bucket, COS will automatically generate a unique version ID for new object, and return this ID in the response using the x-cos-version-id response header.
    • If versioning is suspended for the bucket, COS will always use null as the version ID of the object in the bucket and will not return the x-cos-version-id response header.

    Request

    Request samples

    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 (see Request Signature for details).

    Request parameters

    This API does not use any request parameter.

    Request headers

    In addition to common request headers, this API also supports the following request headers. For more information, see Common Request Headers.

    Name Description Type Required
    Cache-Control Cache directives as defined in RFC 2616, which are stored as part of object metadata String No
    Content-Disposition File name as defined in RFC 2616, which is stored as part of object metadata String No
    Content-Encoding Encoding format as defined in RFC 2616, which is stored as part of object metadata String No
    Content-Type HTTP request content type (MIME) as defined in RFC 2616 of the object to upload, and stored as part of object metadata
    Example: text/html or image/jpeg
    String Yes
    Expires The cache expiration time as defined in RFC 2616, which is stored as part of object metadata String No
    Transfer-Encoding To upload data in chunks, you need to specify the Transfer-Encoding: chunked request header. In this case, the request body will follow the transfer encoding format as defined in RFC 2616, while you cannot use the Content-Length request header. String No
    x-cos-meta-* Includes custom metadata and its header suffix, which are stored as part of object metadata. Maximum size: 2 KB.
    Note: custom metadata can contain underscores (_), whereas its header suffix can only contain minus signs (-).
    String No
    x-cos-storage-class Object storage class. Enumerated values: STANDARD (default), STANDARD_IA and ARCHIVE. For more information, see Storage Class Enum No

    ACL-related headers

    You can configure object access permissions when uploading an object using the following request headers:

    Name Description Type Required
    x-cos-acl Defines the access control list (ACL) attributes of the object. For enumerated values such as default, private, and public-read, see the Preset ACL section in ACL Overview.
    Note: currently, COS supports up to 1,000 bucket ACL rules. If you do not need an object ACL, set this parameter to default (inherit bucket permissions), or leave it empty.
    Enum No
    x-cos-grant-read Grants permission to read the object; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" String No
    x-cos-grant-read-acp Grants permission to read the object ACLs; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" String No
    x-cos-grant-write-acp Grants permission to write to the object ACLs; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" String No
    x-cos-grant-full-control Grants full permission to operate on the object; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" String No

    Headers related to server-side encryption (SSE)

    For information about uploading objects using SSE encryption, see Server-side encryption headers.

    Request body

    The request body of this API request is the object (file) content.

    Response

    Response headers

    In addition to common response headers, this API also returns the following response headers. For more information on common response headers, see Common Response Headers.

    Versioning-related headers

    If the object is uploaded to a versioning-enabled bucket, the following response headers will be returned:

    Name Description Type
    x-cos-version-id Object version ID string

    Headers related to server-side encryption (SSE)

    If you upload an object using SSE encryption, this API will return SSE headers. For more information, see Server-side encryption headers.

    Response body

    The response body of this API is empty.

    Error codes

    This API returns uniform error responses and error codes. For more information, see Error Codes.

    Examples

    Example 1. Simple example (versioning 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****

    Sample 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 server-side encryption 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 server-side encryption 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 server-side encryption 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 versioning

    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 versioning

    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 7. Using chunked transfer encoding to transfer data in chunks

    This example request uses chunked transfer encoding, and describes raw data in the HTTP request. The API calling method varies depending on languages and libraries. For more information, see the language- and library-specific documentation.

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

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help