描述
从指定 URL 抓取资源,并将该资源存储到指定空间中。每次只抓取一个文件,抓取时可以指定保存空间名和最终资源名。
发起任务
说明
- 抓取动作是异步操作,接受到抓取请求后服务端直接返回成功,资源会在后台进行抓取后存入存储,并产生一个回调请求通知业务服务器(如果存在回调参数)。
- 因为各种原因抓取失败时会产生一个json格式的特殊回调通知业务服务器。
- 如果被抓取的源站屏蔽(屏蔽可能是抓取源站有 IP、UA 等限制策略)来自七牛的抓取操作,那么不能确保一定可以抓取成功。
请求(示例参数不完整,详见请求参数部分)
POST /sisyphus/fetch HTTP/1.1
Host: api-<Zone>.qiniu.com
Content-Type: application/json
Authorization: Qiniu <AccessToken>
Body:
{
"url" : "<url>",
"host" : "<host>",
"bucket": "<bucket>",
"key": "<key>",
"md5": "<md5>",
"callbackurl": "<callbackurl>",
"callbackbody": "<callbackbody>",
"callbackbodytype": "<callbackbodytype>",
"file_type":<file_type>
}
请求参数
Host: api-<Zone>.qiniu.com
中的 <Zone>
为七牛各区域机房代号,对应关系如下
区域 |
代号 |
华东 |
z0 |
华北 |
z1 |
华南 |
z2 |
北美 |
na0 |
东南亚 |
as0 |
参数名称 |
类型 |
默认值 |
必填 |
说明 |
url |
string |
N/A |
是 |
需要抓取的url,支持设置多个用于高可用,以';'分隔,当指定多个url时可以在前一个url抓取失败时重试下一个 |
bucket |
string |
N/A |
是 |
所在区域的bucket |
host |
string |
空 |
否 |
从指定url下载数据时使用的Host |
key |
string |
空 |
否 |
文件存储的key,不传则使用文件hash作为key |
md5 |
string |
空 |
否 |
文件md5,传入以后会在存入存储时对文件做校验,校验失败则不存入指定空间 |
etag |
string |
空 |
否 |
文件etag,传入以后会在存入存储时对文件做校验,校验失败则不存入指定空间,相关算法参考 https://github.com/qiniu/qetag |
callbackurl |
string |
空 |
否 |
回调URL,详细解释请参考上传策略中的callbackUrl |
callbackbody |
string |
空 |
否 |
回调Body,如果callbackurl不为空则必须指定。上传成功后,七牛云向业务服务器发送 Content-Type: application/x-www-form-urlencoded 的 POST 请求。业务服务器可以通过直接读取请求的 query 来获得该字段,支持魔法变量、但不支持自定义变量。callbackBody 要求是合法的 url query string。例如key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)。如果callbackBodyType指定为application/json,则callbackBody应为json格式,例如:{"key":"$(key)","hash":"$(etag)","w":"$(imageInfo.width)","h":"$(imageInfo.height)"}。 |
callbackbodytype |
string |
空 |
否 |
回调Body内容类型,默认为"application/x-www-form-urlencoded",详细解释请参考上传策略中的callbackBodyType |
callbackhost |
string |
空 |
否 |
回调时使用的Host |
file_type |
int |
0 |
否 |
存储文件类型 0:标准存储(默认),1:低频存储,2:归档存储 |
ignore_same_key |
bool |
false |
否 |
如果空间中已经存在同名文件则放弃本次抓取(仅对比Key,不校验文件内容) |
返回
{"id":"<ID>","wait":<Wait>}
返回参数
参数名称 |
说明 |
id |
异步任务Id |
wait |
当前任务前面的排队任务数量,0表示当前任务正在进行,-1表示任务已经至少被处理过一次(可能会进入重试逻辑) |
抓取失败时特殊回调消息体格式
- 特殊回调消息体包含发起请求时的参数和错误信息,示例不包含所有参数
{
"url" : "<url>",
"bucket": "<bucket>",
"key": "<key>",
"md5": "<md5>",
"callbackurl": "<callbackurl>",
"callbackbody": "<callbackbody>",
"callbackbodytype": "<callbackbodytype>",
"file_type":<file_type>,
"err":"<err>",
"code":<code>
}
参数名称 |
说明 |
err |
错误信息 |
code |
错误码 |
查询任务
请求
GET /sisyphus/fetch?id=<ID> HTTP/1.1
Host: api-<Zone>.qiniu.com
Authorization: Qiniu <AccessToken>
返回
{"id":"<ID>","wait":<Wait>}
示例(发起异步任务)
请求
POST /sisyphus/fetch HTTP/1.1
Host: api-z0.qiniu.com
Content-Type: application/json
User-Agent: Go-http-client/1.1
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:FwliyUEz-rL1rb9qVkd0xYosBng=
Body:
{
"url" : "http://www.qiniu.com",
"bucket": "test",
"key": "qiniu",
"callbackurl": "http://www.qiniu.com/callback",
"callbackbody": "$(bucket)"
}
响应
HTTP/1.1 200 OK
Content-Length: 94
Connection: keep-alive
Content-Type: application/json
Date: Tue, 19 Sep 2017 06:28:18 GMT
Server: nginx
X-Reqid: jXwAAH8259lkr-UU
Body:
{"id":"eyJ6b25lIjoiejAiLCJwYXJ0X2lkIjo2Mywib2Zmc2V0IjowfQ==","wait":-1}