You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /
  • 对象存储

PutFetchTask

最近更新时间：2024.04.26 15:22:49

首次发布时间：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：桶所有者完全权限。

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}, "key1" : ${x:key1}, "key2" : ${x:key2}}

回调请求发送时的消息体，格式需与 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

异步任务 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"
}