PUT Fetch

最近更新时间:2019-01-14 10:10:58

PUT Object - Fetch


描述

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


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}
Authorization: {SignatureValue}
Date: {date}

注意:

请求参数

该请求不使用请求参数。

请求头部

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

名称 描述 必需
x-kss-sourceurl 第三方URL地址,需要进行URLEncode
x-kss-callbackurl 拉取成功或失败的回调URL,需要进行URLEncode
x-kss-acl 用于对象的预定义权限。
类型:String
默认值:private
有效值:private | public-read
Content-MD5 base64加密MD5信息,128位,用于对象完整性校验。
类型:String
默认值:None
如果这个值与上传到KS3文件的MD5不一致,回调会返回上传KS3失败(status = 3)

请求内容

该接口不使用请求内容。

响应

响应头部

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

响应内容

该接口不返回响应内容。

特殊错误

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

回调

回调内容

回调内容是一段JSON。顶层包括 status 字段,用来表示拉取状态。

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

如果 status1,表示拉取失败,需要检查指定的第三方URL。

如果 status2,表示上传KS3失败,请稍后重试。

如果 status3,表示上传的md5值与从源站拉取下来的文件md5值不一致。

回调内容还会包含请求接口时返回的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.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

响应示例

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

回调示例

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

{"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 不代表文件已经上传到KS3,甚至不保证文件会上传至KS3。如果需要了解拉取是否成功,需要注册回调。
  • 用户必须对目标Bucket具有写权限。
  • 如果目标key已经存在,则此接口会报错。
  • 请不要多次对同一个目标文件发起fetch请求。如果文件正在fetch中,再次发起请求不会有任何回调。

金山云,开启您的云计算之旅

立即注册