You need to enable JavaScript to run this app.
导航
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 指定的类型匹配。

说明

  • 支持回调参数变量,且仅支持系统变量,不支持自定义变量。详细介绍,请参见回调参数变量
  • CallbackBodyTypeapplication/json 时,必须为合法的 JSON 格式,TOS 服务端会强校验该字段;当 callbackBodyTypeapplication/x-www-form-urlencoded 时,可为空。
  • 如果回调失败,将忽略 CallbackBody 参数。

CallbackBodyType

Body

String

application/json

回调请求的消息体类型(Content-Type),与 callbackBody 配套使用。只支持取值application/x-www-form-urlencodedapplication/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"
}