PUT Fetch

Description

You can call this operation to pull a file from a third-party URL and upload the file as an object to a bucket in Kingsoft Cloud Standard Storage Service (KS3). You can use the x-kss-sourceurl request header to specify a third-party URL in the request. You can also use the x-kss-callbackurl request header to specify a callback URL to which the notifications about the upload success or failure are sent. You can use the x-kss-acl request header to manage the permissions on the object that is uploaded to KS3.

Notes:

This operation consists of the following two steps: 1. Initiate a PUT Object Fetch request. 2. Pull a file from the URL and upload it as an object to KS3. The two steps are performed in an asynchronous way. You initiate a PUT Object Fetch request first. When a success response is returned, KS3 pulls a file and uploads the file as an object to KS3. A different response is returned for each step. If the PUT Object Fetch request is initiated, HTTP status code 200 is returned. If you have specified a callback URL in the request, a status code is returned based on the execution results of the pull and upload operations.

If the name of the object to be uploaded already exists in KS3, the server checks whether the value of the Content-MD5 header is the same as the MD5 value of the existing KS3 object with the same name. If not, the existing object is overwritten by the uploaded object.

If KS3 fails to pull a file from the URL that is specified by the x-kss-sourceurl header, KS3 retries up to three times. If the pull operation is successful, KS3 uploads the file as an object to a bucket. If the upload fails, KS3 retries up to three times.

If you have specified a callback URL, KS3 sends a piece of JSON-formatted text about an upload success or failure to the callback URL by using the POST method. The server returns HTTP status code 200 if the callback event is properly handled. If a status code other than 200 is returned, the callback is not properly handled and KS3 retries up to three times. The timeout period is 3 seconds. If a timeout error occurs, KS3 retries up to three times.

If you want to use this operation, you must have the write permissions on the bucket to which you want to upload an object. Each PUT Object Fetch request requires authentication and does not contain a request body.

Request

Request syntax

PUT /{ObjectKey}?fetch HTTP/1.1
Host: {BucketName}.{endpoint}
x-kss-sourceurl: {sourceurl}
x-kss-callbackurl: {callbackurl}
x-kss-acl: {acl}
x-kss-tagging:TagA=A&TagB=B
Authorization: {SignatureValue}
Date: {date}

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.

Header	Description	Required
x-kss-sourceurl	The third-party URL. URL-encoding is required.	Yes
x-kss-callbackurl	The callback URL to which the notifications about the upload success or failure are sent. URL-encoding is required.	No
x-kss-acl	The pre-defined permissions on the object to be uploaded. Type: String Default value: private Valid values: private and public-read	No
x-kss-tagging	The tag to be added to the uploaded 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.	No
Content-MD5	The value that is generated by using the MD5 algorithm for encryption and encoded in Base64. The MD5 value is a 128-bit number that can be used to verify the integrity of the object. Type: String Default value: None If the value is different from the MD5 value of the uploaded object, the status code 3 that indicates an upload failure is returned to the callback URL.	No

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.

Callback

Callback content

If you have specified a callback URL by using the x-kss-callbackurl header in the request, the server returns the result of the pull and upload operations to the callback URL. The callback content is a piece of JSON-formatted text. The top-level field is the status parameter that indicates the status of the pull and upload operations.

If the value of the status parameter is 0, the pull and upload operations are successful. The information about the uploaded object is also included in the callback content.

If the value of the status parameter is 1, the pull operation failed. Check whether the specified third-party URL is correct.

If the value of the status parameter is 2, the upload operation failed. Try again later.

If the value of the status parameter is 3, the MD5 value of the uploaded object is different from that of the file that is pulled from the third-party URL.

If the value of the status parameter is 4, an object with the same name as the uploaded object already exists in KS3.

If the value of the status parameter is 5, an object with the same name as the uploaded object is being uploaded.

The callback content also contains the requestId parameter in the response. You can query the request based on the request ID.

Parameters related to the object information

Parameter	Description	Remarks
bucket	The bucket to which the object is uploaded.	The value is encoded in UTF-8.
key	The name of the object.	The value is encoded in UTF-8.
objectSize	The size of the object.	Unit: byte.
sourceUrl	The URL from which the object is pulled.	The value is encoded in UTF-8.

Examples

Sample request

PUT /my-image.jpg?fetch HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-kss-sourceurl: http://example.com/some-resource-url
x-kss-callbackurl: http://example.com/some-callbackurl
x-kss-acl: public-read
x-kss-tagging:TagA=A&TagB=B
Authorization: authorization string

Sample response

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: Tengine

Sample callback

If the pull and upload operations are successful, the following callback content is returned:

{"status":0,"key":"test-object-key","bucket":"test-bucket-name","objectSize":20597555,"sourceUrl":"http://example.com/some-resource-url","requestId":"d089cd7e583a4f9d95626de6695279db"}

If the pull operation fails, the following callback content is returned:

{"status":1,"key":"test-object-key","bucket":"test-bucket-name","sourceUrl":"http://example.com/some-resource-url","requestId":"47661b13ce8c4c4aabbcda3a1a2dfe14"}

If the pull operation is successful but the upload operation fails, the following callback content is returned:

{"status":2,"key":"test-object-key","bucket":"test-bucket-name","sourceUrl":"http://example.com/some-resource-url","requestId":"f28d01ef77274c0c8f40489a41f367f4"}

Usage notes

• HTTP status code 200 only indicates that the PUT Object Fetch request is initiated. This status code does not indicate that the object is uploaded to KS3. The object may fail to be uploaded even if this status code is returned. If you want to check whether the pull and upload operations are successful, you must register a callback function.
• You must have the write permissions on the bucket to which you want to upload an object.
• You can set tags for the object that is uploaded to KS3. If you want to set tags, you must have the ks3:PutObjectTagging permission.
• If the object to be uploaded has the same name as an existing object, an error is returned.
• You cannot call this operation for multiple times to upload an object. If a PUT Object Fetch request is initiated for the object, subsequent requests cannot trigger callbacks.
• If you have the ks3:PutObject permission but not the PutObjectTagging permission, you can call this operation to upload an object without tags.