PUT Fetch

描述

此PUT接口从第三方URL拉取文件，并上传至KS3某个 bucket 中存储成名为 object 的文件。用户通过在请求中配置请求头部 x-kss-sourceurl 来指定第三方URL。也可以通过配置请求头 x-kss-callbackurl 来指定上传成功或失败时的回调URL。还可以通过 x-kss-acl 来设置上传KS3后的文件权限。

注意：

该接口执行过程分为两个部分：

1.发起PUT Object Fetch请求；

2.执行拉取文件并上传到KS3。这两个过程异步执行，先发起PUT Object Fetch请求，成功后再执行Fetch拉取文件和上传到KS3的过程。两个过程有不同的返回信息，其中，发起PUT Object Fetch请求完成会返回http状态码200；如果用户配置了回调url，则根据不同的回调状态返回不同的状态码。

如果fetch的文件和KS3已存在的文件同名，KS3服务端会校验请求头中的Content-Md5值和KS3同名文件的md5值。如果不相同，才会拉取文件进行覆盖。

KS3会尝试访问 x-kss-sourceurl 指定的URL，会重试三次。如果拉取文件成功，会尝试往 bucket 上传名为 object 的文件，会重试三次。

如果使用回调接口，KS3在拉取成功或失败时，会通过POST方法向用户的回调地址POST一段json数据。用户服务端正确处理回调后通过响应HTTP状态码200表示正确处理，对于其它状态码，KS3认为客户服务端处理异常，会进行重试。超时时间设置为3秒，重试三次。

使用此接口，用户需要具有目标空间的写权限。并且所有的拉取请求均需要用户进行身份验证且不包含信息体。

请求

语法

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}

注意：

• endpoint与Region对应关系
• SignatureValue签名算法

请求参数

该请求不使用请求参数。

请求头部

该接口可以使用所有常用请求头部，此外，也可以使用下表所列请求头部。获取更多信息，请点击常用请求头部。

名称	描述	是否必选
x-kss-sourceurl	第三方URL地址，需要进行URLEncode。	是
x-kss-callbackurl	拉取成功或失败的回调URL，需要进行URLEncode。	否
x-kss-acl	用于对象的预定义权限。 类型：String 默认值：private 有效值：private | public-read	否
x-kss-tagging	指定目标Object对象标签，可同时设置多个标签，例如：TagA=A&TagB=B。 说明 Key和Value需要先进行URL编码， 如果某项没有“=”，则看作Value为空字符串。详见对象标签。	否
Content-MD5	base64加密MD5信息，128位，用于对象完整性校验。 类型：String 默认值：None 如果这个值与上传到KS3文件的MD5不一致，回调会返回上传KS3失败（status = 3）。	否

请求内容

该接口不使用请求内容。

响应

响应头部

该接口可以使用所有常用响应头部。获取更多信息，请点击常用响应头部。

响应内容

该接口不返回响应内容。

特殊错误

该请求不返回任何特殊错误。

回调

回调内容

如果在请求中配置了回调url（x-kss-callbackurl），则在拉取、上传过程后会执行回调返回拉取、上传的执行结果。回调内容是一段JSON。顶层包括 status 字段，用来表示拉取与上传的状态。

如果 status 为 0，表示拉取成功、上传KS3成功。同时会包括一些文件信息。

如果 status 为 1，表示拉取失败，需要检查指定的第三方URL。

如果 status 为 2，表示上传KS3失败，请稍后重试。

如果 status 为 3，表示上传的md5值与从源站拉取下来的文件md5值不一致。

如果 status 为 4，表示文件已经存在。

如果 status 为 5，表示相同的objectKey的仍在执行中。

回调内容还会包含请求接口时返回的requestId，用于建立请求的对应关系。

文件信息

参数	说明	备注
bucket	文件上传的Bucket	Utf-8编码
key	文件的名称	Utf-8编码
objectSize	文件大小	以字节标识
sourceUrl	拉取资源URL	Utf-8编码

示例

请求示例

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

响应示例

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

回调示例

拉取上传成功后的回调内容：

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

拉取失败时的回调内容：

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

拉取成功，但上传失败时的回调内容：

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

接口细节分析

• 此接口返回 200 仅代表发起PUT Object Fetch请求成功。不代表文件已经上传到KS3，甚至不保证文件会上传至KS3。如果需要了解拉取是否成功，需要注册回调。
• 用户必须对目标Bucket具有写权限。
• 仅支持对存储到KS3的目标文件设置tag，且需要具有ks3:PutObjectTagging操作授权。
• 如果目标key已经存在，则此接口会报错。
• 请不要多次对同一个目标文件发起fetch请求。如果文件正在fetch中，再次发起请求不会有任何回调。
• 当访问者具有ks3:PutObject权限，但没有PutObjectTagging权限时，该接口仅允许上传不带tagging的对象。