tencent cloud

Feedback

Cloud Object Storage

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


Catalog

Contact Us

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

Technical Support

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

7x24 Phone Support
Hong Kong, China
+852 800 906 020 (Toll Free)
United States
+1 844 606 0804 (Toll Free)
United Kingdom
+44 808 196 4551 (Toll Free)
Canada
+1 888 605 7930 (Toll Free)
Australia
+61 1300 986 386 (Toll Free)
EdgeOne hotline
+852 300 80699
More local hotlines coming soon