FetchObject
更新时间：2026-09-18
接口描述
此接口用于从指定 URL 抓取资源，并将资源存储到指定的 Bucket 中。此操作需要请求者对该 Bucket 有写权限，每次只能抓取一个 Object，且用户可以自定义 Object 的名称。
说明：
FetchObject接口抓取资源的大小限制为0~48.8 TB。
请求
请求结构
Http
1POST /{ObjectName}?fetch HTTP/1.1
2Host: {BucketName}.bj.bcebos.com
3Content-Length: 0
4Date: {Date}
5x-bce-fetch-source: {Source}
6x-bce-fetch-mode: {FetchMode}
7x-bce-storage-class: {StorageClass}
8Authorization: {AuthorizationString}请求头域
| 名称 | 类型 | 位置 | 是否必需 | 描述 |
|---|---|---|---|---|
Authorization |
String | Header | 是 | BOS 请求鉴权字符串。 |
x-bce-fetch-source |
String | Header/Query | 是 | 抓取文件的源地址，如 http://www.abc.com/img.jpg。该参数可以放到 query string 中；当放到 query string 时需要进行 URL Encode。 |
x-bce-fetch-mode |
String | Header/Query | 否 | 抓取模式，支持异步抓取 async 和同步抓取 sync。异步模式下 BOS 收到抓取任务后立刻返回成功；同步模式下 BOS 需要等到抓取 Object 完成后才会返回成功。对于数据量小或关注抓取结果实时性的场景，建议使用同步模式；异步模式不需要等待，适用于不需要实时查看抓取结果的场景，可以后续再对抓取结果进行查询。默认值为 sync。该参数可以放到 query string 中。 |
x-bce-storage-class |
String | Header/Query | 否 | 存储类型，支持标准存储 STANDARD、低频存储 STANDARD_IA、冷存储 COLD 和归档存储 ARCHIVE，默认存储为 STANDARD；如果是多 AZ 类型 Bucket，支持 MAZ_STANDARD_IA 代表多 AZ 低频存储，不指定时默认是 MAZ_STANDARD 多 AZ 标准存储类型，不能是其他取值。该参数可以放到 query string 中。 |
x-bce-server-side-encryption |
String | Header | 否 | 服务端加密算法，当前支持 AES256 和 SM4 加密。 |
x-bce-callback-address |
String | Header | 否 | fetch 结果回调地址。若选择异步抓取，抓取完成后会将结果推送到该地址。 |
referer |
String | Header | 否 | 源站 fetch 时需要透传的 Referer 头域。 |
user-agent |
String | Header | 否 | 源站 fetch 时需要透传的 User-Agent 头域。 |
请求参数
| 名称 | 类型 | 位置 | 是否必需 | 描述 |
|---|---|---|---|---|
ObjectName |
String | Path | 是 | 抓取后保存到 BOS 的 Object 名称。 |
fetch |
String | Query | 是 | 子资源标识，用于指定执行 FetchObject 操作。请求中仅需携带该标识，无需设置业务值。 |
除上述 Path 和 Query 标识外，无其他请求参数；请求 Body 为空，Content-Length 为 0。
响应
响应头域
无特殊响应头域。响应中可能包含 BOS 公共响应头，如 x-bce-request-id。
响应参数
| 名称 | 类型 | 位置 | 出现条件 | 描述 |
|---|---|---|---|---|
code |
String | Body | 总是 | 返回请求成功或失败的返回码，成功返回 success，错误返回 错误码。 |
message |
String | Body | 总是 | 返回请求成功或失败的信息，成功返回 success，错误返回 code 对应的 错误码。 |
requestId |
String | Body | 总是 | 请求 ID。 |
jobId |
String | Body | 异步模式 | 异步模式才会返回该参数，表示请求任务的 ID，可用于后续任务状态查询。 |
x-bce-version-id |
String | Header | 当返回版本信息时 | Object 的版本 ID。 |
示例
请求示例
同步模式
Http
1POST /ObjectName?fetch HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Content-Length: 0
4Date: <Date>
5x-bce-fetch-source: http://www.abc.com/demo.html
6x-bce-fetch-mode: sync
7x-bce-storage-class: STANDARD
8Authorization: AuthorizationString响应示例
同步模式
Http
1HTTP/1.1 200 OK
2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
3Transfer-Encoding: chunked
4Date: Wed, 25 May 2016 06:34:40 GMT
5Server: BceBos
6
7{
8 "code": "success",
9 "message": "success",
10 "requestId": "4db2b34d-654d-4d8a-b49b-3049ca786409"
11}异步模式
Http
1POST /ObjectName?fetch HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Content-Length: 0
4Date: <Date>
5x-bce-fetch-source: http://www.abc.com/demo.html
6x-bce-fetch-mode: async
7x-bce-storage-class: STANDARD_IA
8Authorization: AuthorizationString异步模式
Http
1HTTP/1.1 200 OK
2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
3Content-Type: application/json; charset=utf-8
4Date: Wed, 25 May 2016 06:34:40 GMT
5Server: BceBos
6
7{
8 "code": "success",
9 "message": "success",
10 "requestId": "4db2b34d-654d-4d8a-b49b-3049ca786409",
11 "jobId": "b2419b1e3fd45d596ee22bdf62aaaa2f"
12}异步模式，通知回调地址
Http
1POST /ObjectName?fetch HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Content-Length: 0
4Date: <Date>
5x-bce-fetch-source: http://www.abc.com/demo.html
6x-bce-fetch-mode: async
7x-bce-storage-class: STANDARD_IA
8x-bce-callback-address: http://www.example.com/fetch/callback
9Authorization: AuthorizationString异步模式，通知回调地址
Http
1HTTP/1.1 200 OK
2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
3Content-Type: application/json; charset=utf-8
4Date: Wed, 25 May 2016 06:34:40 GMT
5Server: BceBos
6
7{
8 "code": "success",
9 "message": "success",
10 "requestId": "4db2b34d-654d-4d8a-b49b-3049ca786409",
11 "jobId": "fo-9a98f238d56a33b4eb6664fede20b747"
12}回调地址收到的信息示例
fetch 成功
JSON
1{
2 "code": "success",
3 "jobid": "fo-9a98f238d56a33b4eb6664fede20b747",
4 "message": "success",
5 "requestId": "61c41bdf-672b-49c4-921e-3d6bde8112a6"
6}fetch 失败
JSON
1{
2 "code": "NoSuchKey",
3 "jobid": "fo-9a98f238d56a33b4eb6664fede20b747",
4 "message": "The specified key does not exist.",
5 "requestId": "24ff8d6c-f793-45ef-b55b-973837141c90"
6}评价此篇文章