异步第三方资源抓取(sisyphus/fetch)
描述
本接口用于从指定 URL 抓取资源,并将该资源存储到指定空间中。每次只抓取一个文件,抓取时可以指定保存空间名和最终资源名。
发起任务
请求语法
POST /sisyphus/fetch HTTP/1.1
Host: api-<Region>.qiniuapi.com
Content-Type: application/json
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu <AccessToken>
{
"url": "<url>",
"host": "<host>",
"bucket": "<bucket>",
"key": "<key>",
"md5": "<md5>",
"callbackurl": "<callbackurl>",
"callbackbody": "<callbackbody>",
"callbackbodytype": "<callbackbodytype>",
"file_type": <file_type>
}
使用说明:
- 抓取动作是异步操作。服务端接收到抓取请求后直接返回成功,资源会在后台抓取后存入存储,并产生一个回调请求通知业务服务器(如果设置了回调参数)。
- 因各种原因抓取失败时,会产生一个 JSON 格式的特殊回调通知业务服务器。
- 如果被抓取的源站屏蔽了来自七牛的抓取操作(例如源站有 IP、UA 等限制策略),则不能确保抓取一定成功。
请求参数
该请求的 URL 参数为空,请参考请求内容中的参数。
请求头
| 头部名称 | 必填 | 说明 |
|---|---|---|
| Host | 是 | `api-<Region>.qiniuapi.com` 中的 `<Region>` 为七牛各区域 ID,请参考七牛支持的区域列表。 |
| Authorization | 是 | 该参数应严格按照管理凭证格式填写,否则会返回 401 错误码。合法的 Authorization 值类似于:`Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他 | 否 | 请查阅公共请求头。 |
请求内容
| 参数名称 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| url | string | N/A | 是 | 需要抓取的 URL。支持设置多个用于高可用,以 `;` 分隔;指定多个 URL 时,前一个 URL 抓取失败会重试下一个。 |
| bucket | string | N/A | 是 | `<Zone>` 所在区域的 bucket。 |
| host | string | 空 | 否 | 从指定 URL 下载数据时使用的 Host。 |
| key | string | 空 | 否 | 文件存储的 key,不传则使用文件 hash 作为 key。 |
| md5 | string | 空 | 否 | 文件 MD5。传入后会在存入存储时对文件做校验,校验失败则不存入指定空间。 |
| etag | string | 空 | 否 | 文件 etag。传入后会在存入存储时对文件做校验,校验失败则不存入指定空间。算法参考 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` 归档存储,`3` 深度归档存储,`4` 归档直读存储,`5` 智能分层存储。 |
| mode | string | 空 | 否 | 可选填入 `m3u8`,此时会解析 m3u8 并下载对应 ts 文件落存储,必须指定 `key`。m3u8 文件解析只支持相对路径模式:ts 文件和 m3u8 文件将保存在指定的同一目录下。 |
| ignore_same_key | bool | false | 否 | 默认情况下,如果已存在同名文件仍会重新抓取。为 `true` 时,如果空间中已存在同名文件则放弃本次抓取(仅对比 key,不校验文件内容)。 |
响应
响应语法
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{}
响应头
| 头部名称 | 必填 | 说明 |
|---|---|---|
| Content-Type | 是 | 正常情况下该值为 `application/json`,表示返回 JSON 格式的文本信息。 |
| 其他 | 否 | 其他可能返回的头部信息,请参考公共响应头。 |
响应内容
请求成功时返回:
{"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 | 错误码。 |
响应状态码
该操作不会返回特殊错误。有关错误和错误码列表的一般信息,请查阅错误响应。
示例
请求:发起异步任务
POST /sisyphus/fetch HTTP/1.1
Host: api-z0.qiniuapi.com
Content-Type: application/json
User-Agent: Go-http-client/1.1
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:FwliyUEz-rL1rb9qVkd0xYosBng=
{
"url": "http://www.qiniu.com",
"bucket": "test",
"key": "qiniu",
"callbackurl": "http://www.qiniu.com/callback",
"callbackbody": "$(bucket)"
}
注意:
Authorization头部的<AccessToken>前需要添加Qiniu和一个半角空格。
响应
HTTP/1.1 200 OK
Content-Length: 94
Connection: keep-alive
Content-Type: application/json
Date: Mon, 02 Jan 2006 15:04:05 GMT
Server: nginx
X-Reqid: jXwAAH8259lkr-UU
{"id":"eyJ6b25lIjoiejAiLCJwYXJ0X2lkIjo2Mywib2Zmc2V0IjowfQ==","wait":-1}
查询任务
请求语法
GET /sisyphus/fetch?id=<ID> HTTP/1.1
Host: api-<Region>.qiniuapi.com
Authorization: Qiniu <AccessToken>
请求参数
| 参数名称 | 必填 | 说明 |
|---|---|---|
| id | 是 | 异步任务 ID。 |
响应内容
{"id": "<ID>", "wait": <Wait>}
文档反馈
(如有产品使用问题,请 提交工单)