tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

PUT Object

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

    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********
    
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy