PUT Object

Last updated:2021-04-07 21:40:23

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.ksyun.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.

Did you find the above information helpful?

Unhelpful
Mostly Unhelpful
A little helpful
Helpful
Very helpful

What might be the problems?

  • Insufficient
  • Outdated
  • Unclear or awkward
  • Redundant or clumsy
  • Lack of context for the complex system or functionality

More suggestions

0/200

Please give us your feedback.

Submitted

Thank you for your feedback.

问题反馈