金山云-文档中心-PUT Object

Standard Storage Service (KS3)

View more results

Document title with current keyword not found

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:

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.

Header	Description	Required
Cache-Control	Tells all caching mechanisms whether the object is cacheable and the specific cache type. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.9. Type: String Default value: None Constraint: None	No
Content-Disposition	The presentation information of an object. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html##sec19.5.1. Type: String Default value: None Constraint: None	No
Content-Encoding	The encoding format of the object. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.11. Type: String Default value: None Constraint: None	No
Content-Length	The size of the object, in bytes. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.13. Type: String Default value: None Constraint: None	Yes
Content-MD5	The 128-bit MD5 value calculated based on the message content that excludes the message header. Then, the Base64 encoding technique is used to encode the 128-bit value to verify the object integrity. Type: String Default value: None Constraint: None	No
Content-Type	The Multipurpose Internet Mail Extensions (MIME) type describing the format of the object data. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.17. Type: String Default value: binary/octet-stream Valid value: MIME types Constraint: None	No
Expect	Specifies that the request body is not sent before a 100 (Continue) response is received when a `100-continue` expectation is sent with this request header. If this request header is rejected, the request body will not be sent. Type: String Default value: None Valid value: 100-continue Constraint: None	No
Expires	The date and time after which the cache of an object is considered stale. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.21. Type: String Default value: None Constraint: None	No
x-kss-meta-	The prefix of user-defined metadata. A header starting with `x-kss-meta-` is user-defined metadata. Type: String Default value: None Constraint: None	No
x-kss-storage-class	The storage class. Type: String Default value: None Valid values: STANDARD, STANDARD_IA, and ARCHIVE Note: Assume that the `x-kss-storage-class` request header is not specified. In this case, if the bucket is of the archive type, the object is archived. If the bucket is of the non-archive type, the object is stored in standard mode. Assume that the `x-kss-storageClass` request header is specified. In this case, the object is stored by using the specified method. Constraint: None	No
x-kss-content-maxlength	The maximum size of the object to be uploaded. If the object size exceeds the upper limit, KS3 returns a 403 error. Type: String Default value: None Constraint: None	No
x-kss-newfilename-in-body	Specifies whether to display the returned file name in the response body after you specify the file name in the console. A value of true indicates that the file name is displayed in the response header and response body. A value of false indicates that the file name is displayed only in the response header. Type: Boolean Default value: None Valid values: false and true Constraint: None	No
x-kss-tagging	The tag to be added to the desired object. You can set multiple tags. Example: TagA=A\&TagB=B. Note: URL-encoding is required for the key-value pair of each tag. If a key-value pair does not contain an equal sign (=), the value is considered an empty string. For more information, see Object Tagging.	No

ACL-specific request headers

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

Header	Description	Required
x-kss-acl	The pre-defined permissions on the object to be uploaded. Type: String Default value: private Valid values: `private` and `public-read` Constraint: None	No

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

Header	Description	Required
x-kss-grant-read	Grants the read permissions to users. Type: String Default value: None Constraint: None	No
x-kss-grant-write	Grants the write permissions to users. Type: String Default value: None Constraint: None	No
x-kss-grant-full-control	Grants the users full permissions on the object. Type: String Default value: None Constraint: None	No

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.

Header	Description
x-kss-server-side-encryption	The encryption algorithm that is used. If the server-side encryption is used to store an `object`, this header will be included in the response. Type: String
x-kss-server-side-encryption-customer-algorithm	The user-defined encryption algorithms. If the server-side encryption uses a user-defined encryption key, the response will include this header to check the decryption algorithms to use when decrypting the object. Type: String Valid value: AES256
x-kss-server-side-encryption-customer-key-MD5	The user-defined encryption key. If the server-side encryption uses a user-defined encryption key, the response will include this header to provide the information, with which you can verify the data integrity of the user-provided encryption key. Type: String
newfilename	The file name that is obtained after you specify the file name in the console. Type: String

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.

On this page

Previous:HEAD Object

Next:POST Object

Pure ModeNormal Mode

Pure Mode

Click to preview the document content in full screen