PutFetchTask--对象存储-火山引擎

文档中心

立即注册

导航

对象存储

PutFetchTask

最近更新时间：2024.08.01 20:30:32首次发布时间：2024.04.26 11:58:13

功能描述

调用 PutFetchTask 接口创建从指定 URL 抓取资源，并将该资源存储到指定存储桶的异步任务。每次只抓取一个文件，抓取时可以指定存储桶和最终对象名。

服务端加密

如果您使用服务端加密，TOS 在收到您上传的数据时，在文件级别加密这些数据，再将加密的数据持久化存储；您下载文件时，TOS 自动将加密数据解密后返回给您。关于服务端加密的更多详细信息，请参见服务端加密概述。

ACL

您可以通过 headers 去设置对象的 ACL。所有的对象默认是私有的。您可以给某个账号或者预定义组授予对应的权限。关于 ACL 的更多详细信息，请参见 ACL 策略概述。

存储类型

TOS 默认使用标准存储类型存储对象。标准存储类型是高可用、高可靠、高性能的存储类型。您也可以根据不同的使用场景，选择不同的存储类型。关于存储类型的更多详细信息，请参见存储类型。

回调

PutFetchTask 支持回调功能，设置回调参数后，将根据抓取结果执行回调，说明如下：

如果抓取对象成功，按照设置的 CallBack 参数进行回调。
如果抓取对象失败，将向第三方应用服务返回特殊的回调消息格式，包含发起请求时的参数和错误信息。

说明

PutFetchTask 的回调功能当前不支持回调签名。

注意事项

类别	注意事项
对象数量	一次只支持抓取一个对象。最大能够支持 500 GiB，大于 500 GiB 的对象，抓取会失败。
URL	仅支持抓取可公开访问的 URL 资源。
权限	请确保您使用的火山引擎账号拥有对应存储桶上传对象的权限，否则异步抓取任务会失败。
触发机制	采用异步触发机制，即不按照顺序逐个执行，可以同时执行多个任务，每个任务的阻塞不会阻碍其他任务的执行。
调用结果	调用 PutFetchTask 接口后，仅会返回此次任务的 ID。如果您想了解此次任务的详细信息，例如任务是否执行成功，您可以调用 GetFethTask 接口，详细介绍，请参见 GetFetchTask。
QPS	调用 PutFetchTask 接口提交任务时，最大支持 100 QPS。

请求消息样式

POST /?fetchTask HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: GMT Date
Authorization: authorization string
<Optional Additional Header>

{
    "URL": "http://abc.123/",
    "Object": "objectName"
}

请求参数和消息头

该请求使用的公共请求消息头，请参见公共参数。

名称	位置	参数类型	是否必选	示例值	说明
fetchTask	Query	String	是	-	代表 PutFetchTask 请求的特殊标识。
x-storage-class	Header	String	否	STANDARD	设置目的对象的存储类型。如果未设置，则目的对象的存储类型，和所在桶的默认存储类型保持一致，取值说明如下： `STANDARD`：标准存储。 `IA`：低频访问存储。 `INTELLIGENT_TIERING`：智能分层存储。 `ARCHIVE_FR`：归档闪回存储。 `COLD_ARCHIVE`：冷归档存储。说明当前仅华北2（北京）和华东2（上海）支持冷归档存储类型 `DEEP_COLD_ARCHIVE`：深度冷归档说明深度冷归档目前处于邀测状态，如您需要使用该存储类型，请联系客户经理。
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。说明当前仅支持单个 URL。
Object	Body	String	是	objectName	指定存储到 TOS 的对象名称。
IgnoreSameKey	Body	Bool	否	true	存储桶中存在同名文件时的抓取策略，取值说明如下： `true`：如果存储桶中已存在同名文件，则放弃本次抓取。 `false`：如果存储桶中已存在同名文件，仍然会抓取对象，并且上传该对象时会覆盖存储桶中原对象。默认为 `false`。说明根据文件的 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 为止。注意不支持回调参数变量。当 `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。注意不支持回调参数变量。 `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` 指定的类型匹配。说明支持回调参数变量，且仅支持系统变量，不支持自定义变量。详细介绍，请参见回调参数变量。当 `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`。说明不支持回调参数变量。

响应消息头

该请求返回的公共响应消息头，请参见公共参数。

响应元素

该请求会返回异步任务的 ID。

名称	参数类型	示例值	描述
TaskID	String	da62d05e-e6e4-4bad-924a-ed4ab98ae17a	异步任务 ID。

请求示例

POST /?fetchTask HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization string
<Optional Additional Header>

{
    "URL": "http://abc.123/",
    "Object": "objectName"
}

响应示例

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"
}