PUT Object

Description

You can call this operation to add an object to a specific bucket. To call this operation, you must have the write permission on the bucket where an object is to be added.

An incomplete object cannot be added by using Kingsoft Cloud Standard Storage Service (KS3). If KS3 has added the object to the desired bucket, a success response is returned.

KS3 is a distributed system. When KS3 receives multiple write requests for the same object, it writes the object in an overwrite way and keeps only the latest object. KS3 does not provide object locking when you write an object to the bucket. You can build this function into your application layer as required.

We recommend that you use a Content-MD5 header to avoid data corruption during data transmission. If a Content-MD5 header is used, KS3 automatically calculates an MD5 value for verification. If the calculated MD5 value does not match the MD5 value that you provide, an error message is returned. After you upload an object to KS3, KS3 calculates the MD5 value for the object based on the ETag of the response.

Note: You can call this operation to upload an object up to 5 GB in size. For an object greater than 5 GB, you must upload the object in multiple parts.

Permission

You can grant permissions to one or more users or user groups to upload an object. You can grant permissions by using the following request headers:

• Use the x-kss-acl request header to specify a predefined access control list (ACL).
• Use the x-kss-grant-read, x-kss-grant-write, or x-kss-grant-full-control request header to grant specific permissions.

Permissions on object tags

• To specify tags for an object when you upload the object, you must have the ks3:PutObjectTagging permission. The ks3:PutObjectTagging permission enables you to add or modify the tags of an object. You must separately apply for the write permissions on an object and object tags.

Request

Request syntax

PUT /{ObjectKey} HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}

References:

• Endpoints and regions
• Request signature

Request parameters

No request parameter is used.

Request headers

This operation supports all common request headers and the request headers that are described in the following table. For more information, see Common request headers.

ACL-specific request headers

You can predefine the ACL for the object by using the following request header.

To configure a specific ACL for the bucket, the following request headers can be used.

For each of the preceding headers, the value is a list of permission items that are separated by commas (,). The authorization information is in the type=value format. The type can be an ID:

• ID: The ID of an user to whom permissions are granted.

For example, you can grant the read permissions to users whose IDs are 1234578 and 3344211 as follows: x-kss-grant-read:id="1234578",id="3344211"

Request body

No request body is used.

Response

Response headers

This operation supports all common response headers. For more information, see common response headers.

Response body

No response body is returned.

Operation-specific errors

This operation does not return operation-specific errors.

Examples

Sample request

PUT /my-image.jpg HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
x-kss-tagging:TagA=A&TagB=B
Content-Length: 11434
Expect: 100-continue
[11434 bytes of object data]

Sample response

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server: Tengine

Usage notes

• You can add a Content-MD5 header to the request to verify the integrity of the object in KS3.
• Assume that a newly uploaded object has the same name as an existing object on the server. The newly uploaded object overwrites the existing object.
• When you upload an object, you can add an x-kss-meta-* header to add metadata.
• You can specify tags for the object to be uploaded. You must have the ks3:GetObjectTagging permission to specify tags regardless of the role that you assume.
• You must use the Content-Length request header. The size that is specified by the Content-Length request header cannot be greater than the data size that is actually uploaded in the request body.
• If you have the ks3:PutObject permission but not the ks3:PutObjectTagging permission, you can call this operation to upload only an object without tags.
• For more information about how to download the uploaded objects, see GET Object.