PUT Fetch

最近更新时间:2020-07-13 23:25:44

PUT Object - Fetch


This put interface pulls files from the third-party URL and uploads them to a file named object stored in a bucket in KS3. The user specifies the third-party URL by configuring the request header x-kss-sourceurl in the request. You can also specify the callback URL when the upload succeeds or fails by configuring the request header x-kss-callbackurl. You can also set the file permissions after uploading KS3 through x-kss-acl.

If the file of fetch has the same name as the existing file of KS3, the KS3 server will verify the Content-Md5 value in the request header and the MD5 value of the file with the same name of KS3. If they are not the same, the file will be pulled and overwritten.

KS3 will try to access the URL specified by x-kss-sourceurl, and try again three times. If the file is pulled successfully, an attempt will be made to upload a file named object to the bucket, and three retries will be made.

If the callback interface is used, KS3 will POST a section of JSON data to the user's callback address through the POST method when the pull succeeds or fails. After the user server correctly handles the callback, it responds to the HTTP status code 200 to indicate correct processing. For other status codes, KS3 thinks that the client server handles exceptions and will try again. The timeout is set to 3 seconds and three retries.

With this interface, users need to have write permission on the target space. And all pull requests need user authentication and do not contain information body.



PUT /{ObjectKey}?fetch HTTP/1.1
Host: {BucketName}.{endpoint}
x-kss-sourceurl: {sourceurl}
x-kss-callbackurl: {callbackurl}
x-kss-acl: {acl}
Authorization: {SignatureValue}
Date: {date}


Request Parameters

The request does not use the request parameter.

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, please click Public Request Headers

Name Description Required
x-kss-sourceurl Third party URL address, URLEncode is required Yes
x-kss-callbackurl Pull the successful or failed callback URL, and URLEncode is required No
x-kss-acl Predefined permissions for the object.
Valid Value:private | public-read
Content-MD5 base64 encrypt MD5 information, 128 bits, for object integrity verification.
If this value is inconsistent with the MD5 uploaded to the KS3 file, the callback will return the upload KS3 failure(status = 3)

Request Elements

The interface does not use the requested content.


Response Headers

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

Response Elements

The interface does not return response content.

Special Errors

The request does not return any special errors.


Callback Elements

The callback content is a JSON. The top level includes the status field to indicate the pull status.

If status is 0, it means that the pull is successful and the upload of KS3 is successful. Some file information will also be included.

If status is 1,it indicates that the pull failed. You need to check the specified third-party URL.

If status is 2,it means the upload of KS3 failed. Please try again later.

If status is 3,it indicates that the uploaded MD5 value is inconsistent with the MD5 value of the file pulled from the origin.

If status is 4,it indicates that the file already exists.

If status is 5,it indicates that the same objectkey is still executing.

The callback content also contains the requestId returned when requesting the interface, which is used to establish the corresponding relationship of the request.

File Information

Parameters Explanation Remarks
bucket Bucket for file upload Utf-8 Encoding
key Name of the File Utf-8 Encoding
objectSize File Size Identified in Bytes
sourceUrl Pull Resource URL Utf-8 Encoding


Sample Request

PUT /my-image.jpg?fetch HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyun.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
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

The callback content after pulling and uploading successfully:


Callback content in case of pull failure:


Callback content when pull succeeds but upload fails:


Interface Detail Analysis

  • The 200 returned by this interface does not mean that the file has been uploaded to KS3, or even that the file will be uploaded to KS3. If you need to know whether the pull is successful, you need to register the callback.。
  • The user must have WRITE permission on the target Bucket.
  • If the target key already exists, this interface will report an error.
  • Please do not make a fetch request to the same target file multiple times. If the file is in a fetch, there will be no callback to initiate the request again.