Description
The PUT Object API request allows uploading a local object (Object) to a specified bucket. This operation requires the requester to have write permissions for the bucket.
Notes
- Write permissions for the bucket are required.
- If the value of Content-Length in the request header is smaller than the actual length of data transmitted in the request body, COS still successfully creates the file. However, the object size is only equal to the size defined in Content-Length, and other data is discarded.
- If the Object being added already exists with the same name, the newly uploaded file will overwrite the original file, and a successful response will return 200 OK.
Request
Request Example
PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String
Note:
Authorization: Auth String (For details, please refer to Request Signature document).
Request Header
Common Headers
This request uses common request headers. For details, see Common Request Headers.
Non-common Headers
This operation's implementation can also use the following request headers.
| Name | Description | Type | Required |
|---|---|---|---|
| Content-Disposition | File name defined in RFC 2616. It is saved as object metadata. | string | No |
| Content-Encoding | Encoding format defined in RFC 2616. It is saved as object metadata. | string | No |
| Expect | When using Expect: 100-continue, the request content is sent only after receiving confirmation from the server. | string | No |
| Expires | Cache policy defined in RFC 2616. It is saved as object metadata. | string | No |
| x-cos-meta-* | Including user-defined header suffixes and user-defined header information will be returned as Object metadata, with a size limit of 2 KB. Note: User-defined header information supports underscores, but user-defined header suffixes do not support underscores. |
string | No |
| x-cos-storage-class | Sets the storage class of the Object, with enumeration values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD | string | No |
| x-cos-acl | Defines the ACL property of the Object, with valid values: private, public-read, default; Default value: default (inherits Bucket permissions). Note: The current access policy entry limit is 1000 entries. If you do not need to control Object ACLs, please fill in default or leave this item unset, which will default to inheriting Bucket permissions. |
string | No |
| x-cos-grant-read | Grants the grantee read permission, format: x-cos-grant-read: id="[OwnerUin]" | String | No |
| x-cos-grant-full-control | Grants the grantee full control permission, format: x-cos-grant-full-control: id="[OwnerUin]" | String | No |
SSE-related headers
SSE can be used during object upload. For details, see Server-side encryption headers.
Request Body
The request body of this request is the content of the Object file.
Response
Response Headers
Common Response Headers
This response contains common response headers. For details on common response headers, please refer to the Common Response Header document.
Special Response Headers
Response headers for this request operation are as follows:
| Name | Type | Description |
|---|---|---|
| ETag | string | MD5 value of the uploaded file content |
Versioning-related headers
The following table describes the response headers returned when objects are uploaded to a versioning-enabled bucket.
| Name | Description | Type |
|---|---|---|
| x-cos-version-id | Version ID of an object. | string |
SSE-related headers
If SSE is used during object upload, this API returns headers used specifically for SSE. For details, see Server-Side Encryption Custom Header.
Response Body
The response body is empty.
Error Code
This request returns common error responses and error codes. For more information, see Error Codes.
Practical Case
Request
PUT /picture.jpg HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Wed, 28 Oct 2015 20:32:00 GMT
Authorization:q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1484639384;32557535384&q-key-time=1484639384;32557535384&q-header-list=host&q-url-param-list=&q-signature=5c07b7c67d56497d9aacb1adc19963135b7d00dc
Content-Length: 64
[Object]
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Wed,16 Aug 2017 11: 59: 33 GMT
x-cos-request-id: NTk5NDMzYTRfMjQ4OGY3Xzc3NGRfMWY=
Example: Using Server Encryption SSE-C
Request
PUT /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.city.yfm4.fsphere.cn
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"
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==