## **功能描述** 调用 PutFetchTask 接口创建从指定 URL 抓取资源，并将该资源存储到指定存储桶的异步任务。每次只抓取一个文件，抓取时可以指定存储桶和最终对象名。 ## **服务端加密** 如果您使用服务端加密，TOS 在收到您上传的数据时，在文件级别加密这些数据，再将加密的数据持久化存储；您下载文件时，TOS 自动将加密数据解密后返回给您。关于服务端加密的更多详细信息，请参见[服务端加密概述](/docs/6349/105525)。 ## **ACL** 您可以通过 headers 去设置对象的 ACL。所有的对象默认是私有的。您可以给某个账号或者预定义组授予对应的权限。关于 ACL 的更多详细信息，请参见 [ACL 策略概述](/docs/6349/102134)。 ## **存储类型** TOS 默认使用标准存储类型存储对象。标准存储类型是高可用、高可靠、高性能的存储类型。您也可以根据不同的使用场景，选择不同的存储类型。关于存储类型的更多详细信息，请参见[存储类型](/docs/6349/104493)。 ## 回调 PutFetchTask 支持回调功能，设置回调参数后，将根据抓取结果执行回调，说明如下： * 如果抓取对象成功，按照设置的 CallBack 参数进行回调。 * 如果抓取对象失败，将向第三方应用服务返回特殊的回调消息格式，包含发起请求时的参数和错误信息。 :::tip PutFetchTask 的回调功能当前不支持回调签名。 ::: ## **注意事项** |**类别** |**注意事项** | |---|---| |对象数量 |* 一次只支持抓取一个对象。|\ | |* 最大能够支持 500 GiB，大于 500 GiB 的对象，抓取会失败。 | |URL |仅支持抓取可公开访问的 URL 资源。 | |权限 |请确保您使用的火山引擎账号拥有对应存储桶上传对象的权限，否则异步抓取任务会失败。 | |触发机制 |采用异步触发机制，即不按照顺序逐个执行，可以同时执行多个任务，每个任务的阻塞不会阻碍其他任务的执行。 | |调用结果 |调用 PutFetchTask 接口后，仅会返回此次任务的 ID。如果您想了解此次任务的详细信息，例如任务是否执行成功，您可以调用 GetFethTask 接口，详细介绍，请参见 [GetFetchTask](/docs/6349/1257673)。 | |QPS |调用 PutFetchTask 接口提交任务时，最大支持 100 QPS。 | |桶类型 |[分层桶](/docs/6349/1282866)暂不支持 PutFetchTask 接口。 | ## **请求消息样式** ```JSON POST /?fetchTask HTTP/1.1 Host: bucketname.tos-cn-beijing.volces.com Date: GMT Date Authorization: authorization string { "URL": "http://abc.123/", "Object": "objectName" } ``` ## **请求参数和消息头** 该请求使用的公共请求消息头，请参见[公共参数](/docs/6349/75044)。 |**名称** |**位置** |**参数类型** |**是否必选** |**示例值** |**说明** | |---|---|---|---|---|---| |fetchTask |Query |String |是 |\- |代表 PutFetchTask 请求的特殊标识。 | |x\-storage\-class |Header |String |否 |STANDARD |设置目的对象的存储类型。如果未设置，则目的对象的存储类型，和所在桶的默认存储类型保持一致，取值说明如下：|\ | | | | | ||\ | | | | | |* `STANDARD`：标准存储。|\ | | | | | |* `IA`：低频访问存储。|\ | | | | | |* `INTELLIGENT_TIERING`：智能分层存储。|\ | | | | | |* `ARCHIVE_FR`：归档闪回存储。|\ | | | | | |* `COLD_ARCHIVE`：冷归档存储。|\ | | | | | | :::tip|\ | | | | | | 当前仅华北2（北京）、华东2（上海）和华南1（广州）支持冷归档存储。|\ | | | | | | :::|\ | | | | | |* `DEEP_COLD_ARCHIVE`：深度冷归档|\ | | | | | | :::tip|\ | | | | | | 当前仅华北2（北京）、华东2（上海）和华南1（广州）支持深度冷归档存储，且都处于邀测状态，如您需要使用该存储类型，请联系客户经理。|\ | | | | | ||\ | | | | | | :::| |x\-tos\-acl |Header |String |否 |private |对象的访问权限，有效的权限设置包括：|\ | | | | | ||\ | | | | | |* `private`：私有的。|\ | | | | | |* `public-read`：公共读。|\ | | | | | |* `public-read-write`：公共读写。|\ | | | | | |* `authenticated-read`：认证用户读。|\ | | | | | |* `bucket-owner-read` ：桶所有者读。|\ | | | | | |* `bucket-owner-full-control`：桶所有者完全权限。|\ | | | | | |* `default`：继承桶 ACL，即对象的 ACL 策略和桶 ACL 策略保持一致。 | |x\-tos\-grant\-full\-control |Header |String |否 |id=123,id=456 |创建对象时，使用此头域授权用户具有对象的读（READ）、读（READ） ACP、写（WRITE） ACP 的权限。格式：id=账号1,id=账号2。 | |x\-tos\-grant\-read |Header |String |否 |id=123,id=456 |允许被授权者读取对象和对象元数据的权限。格式：id=账号1,id=账号2。 | |x\-tos\-grant\-read\-acp |Header |String |否 |id=123,id=456 |允许被授权者读取对象 ACL。格式：id=账号1,id=账号2。 | |x\-tos\-grant\-write\-acp |Header |String |否 |id=123,id=456 |允许被授权者修改对象 ACL。格式：id=账号1,id=账号2。 | |x\-tos\-server\-side\-encryption\-customer\-algorithm |Header |String |否 |AES256 |指定 SSE\-C 加密对象要使用的算法，取值说明如下：|\ | | | | | ||\ | | | | | |* `AES256`：使用 AES256 算法加密对象。 | |x\-tos\-server\-side\-encryption\-customer\-key |Header |String |否 |1234567890abcdefghijklmnopqrstuv |指定 SSE\-C 加密对象的密钥。 | |x\-tos\-server\-side\-encryption\-customer\-key\-MD5 |Header |String |否 |0gYVWExOAz67jX5A6qY4+A== |表示加密对象使用的密钥的MD5值。该头域由密钥的 128\-bit MD5 值经过 base64\-encoded 得到，该值用于消息完整性检查，确认加密密钥在传输过程中没有出错。 | |x\-tos\-meta\-\* |Header |String |否 |x\-tos\-meta\-key: value |用来加入自定义的元数据，以便对对象进行自定义管理。当用户获取此对象或查询此对象元数据时，加入的自定义元数据将会在返回消息的头中出现。 | ## **请求元素** |**名称** |**位置** |**参数类型** |**是否必选** |**示例值** |**说明** | |---|---|---|---|---|---| |URL |Body |String |是 |http://abc.123/ |需要抓取的 URL。|\ | | | | | |:::tip|\ | | | | | |当前仅支持单个 URL。|\ | | | | | ||\ | | | | | |:::| |Object |Body |String |是 |objectName |指定存储到 TOS 的对象名称。 | |IgnoreSameKey |Body |Bool |否 |true |存储桶中存在同名文件时的抓取策略，取值说明如下：|\ | | | | | ||\ | | | | | |* `true`：如果存储桶中已存在同名文件，则放弃本次抓取。|\ | | | | | |* `false`：如果存储桶中已存在同名文件，仍然会抓取对象，并且上传该对象时会覆盖存储桶中原对象。|\ | | | | | ||\ | | | | | |默认为 `false`。|\ | | | | | |:::tip|\ | | | | | |根据文件的 key 判断是否是同名文件，不会比较文件的内容。|\ | | | | | ||\ | | | | | |:::| |ContentMD5 |Body |String |否 |XrY7u+Ae7tCTyyK7j1rNww== |待上传文件的 MD5 的 base64 值。设置后，TOS 会计算上传文件的 MD5 值，并与 PutFetchTask 携带的 MD5 值进行校验。如果校验不通过，则抓取对象会失败。 | |CallbackUrl |Body |String |否 |http://domainname.com/callback |回调请求的 URL，用于指定回调请求的第三方应用服务的地址，TOS 服务在上传成功后会向该地址发送 HTTP/HTTPS 请求。具体说明如下：|\ | | | | | ||\ | | | | | |* URL 中的 path 和 query 部分需要经过 URL 编码。|\ | | | | | |* URL 格式为 HTTP/HTTPS 协议地址，不带协议类型时，默认为 `https://`。|\ | | | | | |* 支持最多 5 个用分号 `;` 分割的 URL，TOS 服务端在回调请求时会按顺序依次请求，直至第一个返回成功的 URL 为止。|\ | | | | | ||\ | | | | | |:::warning|\ | | | | | ||\ | | | | | |* 不支持回调参数变量。|\ | | | | | |* 当 `CallbackUrl` 为空时，忽略其他上传回调参数，代表本次请求没有设置上传回调参数。|\ | | | | | |* `CallbackUrl` 包含的域名或 IP 不能是特殊的域名和 IP：127.0.0.1、0.0.0.0、0:0:0:0:0:0:0:1、0:0:0:0:0:0:0:0、localhost。|\ | | | | | ||\ | | | | | |:::| |CallbackHost |Body |String |否 |alternative\-domainname.com |回调请求发送时的 HOST 头域，用于替换 `callbackUrl` 中解析出的 HOST。|\ | | | | | |:::warning|\ | | | | | ||\ | | | | | |* 不支持回调参数变量。|\ | | | | | |* `CallbackHost` 参数可为空。|\ | | | | | |* `CallbackHost` 必须符合域名或 IP 的格式规则，包含的域名或 IP 不能是特殊的域名和 IP：127.0.0.1、0.0.0.0、0:0:0:0:0:0:0:1、0:0:0:0:0:0:0:0、localhost。|\ | | | | | ||\ | | | | | |:::| |CallbackBody |Body |String |否 |{"bucket" : ${bucket}, "object" : ${object}} |回调请求发送时的消息体，格式需与 `callbackBodyType` 指定的类型匹配。|\ | | | | | |:::tip|\ | | | | | ||\ | | | | | |* 支持回调参数变量，且仅支持系统变量，不支持自定义变量。详细介绍，请参见[回调参数变量](/docs/6349/196411#%E5%9B%9E%E8%B0%83%E5%8F%82%E6%95%B0%E5%8F%98%E9%87%8F)。|\ | | | | | |* 当 `CallbackBodyType` 为 `application/json` 时，必须为合法的 JSON 格式，TOS 服务端会强校验该字段；当 `callbackBodyType` 为 `application/x-www-form-urlencoded` 时，可为空。|\ | | | | | |* 如果回调失败，将忽略 CallbackBody 参数。|\ | | | | | ||\ | | | | | |:::| |CallbackBodyType |Body |String |否 |application/json |回调请求的消息体类型（Content\-Type），与 `callbackBody` 配套使用。只支持取值`application/x-www-form-urlencoded` 和 `application/json` ，其他值不合法。|\ | | | | | |默认值为`application/x-www-form-urlencoded`。|\ | | | | | |:::tip|\ | | | | | |不支持回调参数变量。|\ | | | | | ||\ | | | | | |:::| ## **响应消息头** 该请求返回的公共响应消息头，请参见[公共参数](/docs/6349/75044)。 ## **响应元素** 该请求会返回异步任务的 ID。 |**名称** |**参数类型** |**示例值** |**描述** | |---|---|---|---| |TaskID |String |da62d05e\-e6e4\-4bad\-924a\-ed4ab98ae17a |异步任务 ID。 | ## **请求示例** ```JSON POST /?fetchTask HTTP/1.1 Host: bucketname.tos-cn-beijing.volces.com Date: Fri, 30 Jul 2021 08:05:36 +0000 Authorization: authorization string { "URL": "http://abc.123/", "Object": "objectName" } ``` ## **响应示例** ```JSON HTTP/1.1 200 OK Date: Fri, 30 Jul 2021 13:53:55 GMT Server: TosServer x-tos-id-2: 1e89f203jld00006-a444fd0 x-tos-request-id: 1e89f203b2d00006-a444ed0 Content-Length: 143 { "taskid": "da62d05e-e6e4-4bad-924a-ed4ab98ae17a" } ```

对象存储