This API is used to upload a local object to a specified bucket. To call this API, you need to have write permission for the bucket.
Note：
- The
PUT ObjectAPI supports uploading a file of up to 5 GB. If you need to upload a file larger than 5 GB, please use the Multipart Upload API.- If the
Content-Lengthvalue in the request header is smaller than the length of the data in the actual request body, COS will still successfully create a file, but the object size will be equal to the size defined inContent-Length, and the remaining data will be discarded.- If you upload an object with the same name as an object that already exists in the bucket and versioning is not enabled, the old object will be overwritten by the new one and "200 OK" will be returned upon successful upload.
x-cos-version-id response header.null as the version ID of the object in the bucket and will not return the x-cos-version-id response header.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：
Authorization: Auth String (See Request Signature for details.)
This API has no request parameter.
In addition to common request headers, this API also supports the following request headers. For more information about common request headers, please see Common Request Headers.
| Header | Description | Type | Required |
|---|---|---|---|
| Cache-Control | Cache directives as defined in RFC 2616. It will be stored as object metadata. | string | No |
| Content-Disposition | Filename as defined in RFC 2616. It will be stored as object metadata. | string | No |
| Content-Encoding | Encoding format as defined in RFC 2616. It will be stored as object metadata. | string | No |
| Content-Type | HTTP request content type (MIME) as defined in RFC 2616. This header describes the content type of the object to be uploaded and will be stored as object metadata. Example: text/html, image/jpeg |
string | Yes |
| Expires | The cache expiration time as defined in RFC 2616. It will be stored as object metadata. | string | No |
| Transfer-Encoding | If you want to upload the object in parts, you need to specify the Transfer-Encoding: chunked request header. In this case, the request body will follow the transfer encoding format defined in RFC 2616, and you cannot specify the Content-Length request header. |
string | No |
| x-cos-meta-* | Contains user-defined metadata and header suffixes. It will be stored as object metadata. Maximum size: 2 KB. Note: User-defined metadata can contain underscores (_), whereas the header suffixes of user-defined metadata can only contain minus signs (−) but not underscores. |
string | No |
| x-cos-storage-class | Object storage class. For the enumerated values, such as STANDARD (default), INTELLIGENT_TIERING, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE, please see Storage Class Overview. |
enum | No |
| x-cos-traffic-limit | Limits the speed (in bit/s) for the current upload for traffic control. Valid range: 819200-838860800 (i.e., 100 KB/s-100 MB/s). If the speed exceeds the limit, a 400 error will be returned. | integer | No |
| x-cos-tagging | A set of up to 10 object tags (for example, Key1=Value1&Key2=Value2). Tag key and tag value in the set must be URL-encoded. |
string | No |
ACL-related headers
You can configure an access control list (ACL) for the object by specifying the following request headers during the upload:
| Header | Description | Type | Required |
|---|---|---|---|
| x-cos-acl | Defines the ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Default value: default. Note: If you do not need to set an ACL for the object, set this parameter to default or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in. |
enum | No |
| x-cos-grant-read | Grants a user read permission for an object in the format: id="[OwnerUin]", such as id="100000000001". You can use a comma (,) to separate multiple users, such as id="100000000001",id="100000000002" |
string | No |
| x-cos-grant-read-acp | Grants a user read permission for the ACL of an object in the format: id="[OwnerUin]", such as id="100000000001". You can use a comma (,) to separate multiple users, such as id="100000000001",id="100000000002" |
string | No |
| x-cos-grant-write-acp | Grants a user write permission for the ACL of an object in the format: id="[OwnerUin]", such as id="100000000001". You can use a comma (,) to separate multiple users, such as id="100000000001",id="100000000002" |
string | No |
| x-cos-grant-full-control | Grants a user full permission to operate on an object in the format: id="[OwnerUin]", such as id="100000000001". You can use a comma (,) to separate multiple users, such as id="100000000001",id="100000000002" |
string | No |
Headers Related to Server-Side Encryption (SSE)
Server-side encryption can be used during object upload. For more information, see Server-side encryption headers.
The request body of this API is the object (file) content.