全部文档
当前文档
最近更新时间：2023-01-16 14:42:14
此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}
注意：
该请求不使用请求参数。
该接口可以使用所有常用请求头部，此外，也可以使用下表所列请求头部。获取更多信息，请点击常用请求头部。
| 名称 | 描述 | 是否必选 |
|---|---|---|
| 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。如果需要了解拉取是否成功，需要注册回调。纯净模式