All Documents
Current Document
Content is empty
If you don't find the content you expect, please try another search term
Found 0 result in total
Content is empty
If you don't find the content you expect, please try another search term
Last updated：2021-09-14 16:18:18
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.
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:
No request parameter is used.
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 |
No request body is used.
This operation supports all common response headers. For more information, see Common response headers.
No response body is returned.
This operation does not return operation-specific errors.
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. |
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 stringSample response
HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: TengineSample 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"}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.Pure Mode