PUT Object

最近更新时间:2020-02-17 15:08:31

PUT Object


Description

This PUT interface can add an object to a bucket. If you want to use this interface, you need to have WRITE permission on the space of the object to be added.

KS3 will not add incomplete objects. If you receive a successful response, KS3 has successfully added objects to the response space.

KS3 is a distributed system. If multiple write requests from the same object are received at the same time, it will overwrite all the same objects and keep only the last one. KS3 does not provide object locking service when writing objects. If you really need it, please implement it in your application layer.

To ensure that the data is not damaged during transmission, use the Content-MD5 header. When using this header, KS3 will automatically calculate MD5 and verify it according to MD5 provided by the user. If it does not match, an error message will be returned. In addition, when the user uploads an object to KS3, the MD5 value of the object can be calculated according to the returned ETag.

Attention:Only files within 5G can be uploaded using this interface, and files over 5G can be uploaded [in blocks].(https://docs.ksyun.com/directories/1100)。

Permissions

When you upload an object, you can freely specify any number of groups or individuals to grant permissions. Using the request header, there are two ways to grant valid permissions.

  • Using the x-kss-acl request header, specify a predefined ACL.
  • Using x-kss-grant-read,x-kss-grant-write,x-kss-grant-full-control request headers to explicitly specify specific access rights.

Request

Syntax

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

Attention:

Request Parameters

The request does not use the request parameters.

Request Headers

This interface can use all the common request headers. In addition, it can also use the request headers listed in the following table. For more information, click on Common Request Headers.

Name Description Required
Cache-Control Tell all caching mechanisms whether they can cache and what type they are. For more information, please click http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html## sec14.9
Type:String
Default:None
Constraints:None
No
Content-Disposition Specifies the representation of the object. For more information, please click http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html## sec19.5.1
Type:String
Default:None
Constraints:None
No
Content-Encoding Specifies the file content encoding format. For more information, please click http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html## sec14.11
Type:String
Default:None
Constraints:None
No
Content-Length Indicates the size of the object, in bytes. For more information, please click http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html## sec14.13
Type:String
Default:None
Constraints:None
Yes
Content-MD5 The MD5 value of the message content (excluding the header) is calculated to obtain a 128 bit number, which is then Base64 encoded for object integrity verification.
Type:String
Default:None
Constraints:None
No
Content-Type Describes the MIME format of the file content. For more information, please click http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html## sec14.17
Type:String
Default:binary/octet-stream
Valid Values: MIME types
Constraints:None
No
Expect When you use 100-continue, the body of the request is not sent until you receive confirmation. If the header is rejected, the request body will not be sent.
Type:String
Default:None
Valid Values:100-continue
Constraints:None
No
Expires Object exists on the cached effective time date. For more information, please click http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html## sec14.21
Type:String
Default:None
Constraints:None
No
x-kss-meta- User metadata prefix ID. If a header prefix is x-kss-meta-, the metadata is user-defined.
Type:String
Default:None
Constraints:None
No
x-kss-storage-class Set the storage mode.
Type:String
Default:None
Valid Value:STANDARD/STANDARD_IA/ARCHIVE
Notes:When the x-kss-storage-class is not uploaded, if the Bucket is an archive type, the object will automatically be an archive type. If the Bucket is a non archive type, the object will automatically be a standard type. If thex-kss-storageClass is ARCHIVE, the Bucket must be an archive type, otherwise it will return 400. If the x-kss-storageClass is not ARCHIVE, the Bucket cannot be an archive type, otherwise it will return 400.
Constraints:None
No
x-kss-content-maxlength Set the maximum allowed size of the uploaded file. When Content-Length is greater than this value, KS3 will return 403.
Type:String
Default:None
Constraints:None
No
x-kss-newfilename-in-body After the console sets the filename , specify whether the returned filename appears in the body. True means return in header and body. False means return only in header
Type:boolean
Default:None
Valid Value:false|true
Constraints:None
No
ACL Special Headers

The user can set the default ACL for the Object through the following header.

Name Description Required
x-kss-acl Predefined permissions for the object.
Type:String
Default:private
Valid Value:private &##124; public-read
Constraints:None
No

If you want to set the detailed ACL for the Bucket, you can use the following header settings

Name Description Required
x-kss-grant-read Grant READ permission to several users.
Type:String
Default:None
Constraints:None
No
x-kss-grant-write Grant WRITE permission to several users.
Type:String
Default:None
Constraints:None
No
x-kss-grant-full-control Grant FULL_CONTROL permission to several users.
Type:String
Default:None
Constraints:None
No

The value of the above header value is a comma "," separated authorization list. The format of each authorization information is type = value. The current type supports ID:

  • ID: user ID of the authorized person

For example, to grant READ permission to two users with ID 1234578 and 3344211:
x-kss-grant-read : id="1234578", id="3344211"

Request Elements

The interface does not use the requested elements.

Response

Response Headers

This interface can use all common response headers. For more information, click on Common Response Headers

Name Description
x-kss-server-side-encryption If the server-side encryption is used to store the object, the response will contain the header, and the value is the encryption algorithm used.
Type:String
x-kss-server-side-encryption-customer-algorithm If the server uses the encryption key provided by the user for encryption, the response will include the header to confirm the decryption algorithm used when the request is decrypted.
Type:String
Valid Value:AES256
x-kss-server-side-encryption-customer-key-MD5 If the server uses the encryption key provided by the user for encryption, the response will include the header to provide the data consistency verification information of the encryption key provided by the user when the request is decrypted.
Type:String
newfilename The new filename after Set the filename in the console.
Type:String

Response Elements

The interface does not return response elements.

Special Errors

The request returned no special 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
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

Interface Detail Analysis

  • The user can add Content-md5 to the request header and ask KS3 to verify the integrity of the file
  • When the file on the server already exists, if the upload is successful, it will cause overwrite
  • Users can add the x-kss-meta - * header when uploading, and add user metadata for the Object
  • Content-Length is required and cannot be greater than the actual data size in the body
  • For details about how to download and upload the object, see GET Object

金山云,开启您的云计算之旅

注册有礼