PUT Fetch

最近更新时间:2019-08-22 00:56:32

PUT Object - Fetch


描述

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


如果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}
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值不一致。

如果 status4,表示文件已经存在。

如果 status5,表示相同的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.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中,再次发起请求不会有任何回调。

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

注册有礼