You need to enable JavaScript to run this app.
导航
FetchObject
最近更新时间:2024.04.26 15:22:49首次发布时间:2024.04.26 11:58:13

功能描述

调用 FetchObject 接口从指定 URL 抓取资源,并将该资源存储到指定存储桶。

服务端加密

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

ACL

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

存储类型

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

注意事项

类别

注意事项

对象数量

  • 一次只支持抓取一个对象。
  • 最大能够支持 5 GiB,大于 5 GiB 的对象,抓取会失败。

URL

仅支持抓取可公开访问的 URL 资源。

权限

请确保您使用的火山引擎账号拥有对应存储桶上传对象的权限,否则调用 FetchObject 抓取资源会失败。

请求消息样式

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

{
    "URL": "http://abc.123/"
}

请求参数和消息头

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

名称

位置

参数类型

是否必选

示例值

说明

fetch

Query

String

-

代表 FetchObject 请求的特殊标识。

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-meta-*

Header

string

x-tos-meta-key: value

用来加入自定义的元数据,以便对对象进行自定义管理。当用户获取此对象或查询此对象元数据时,加入的自定义元数据将会在返回消息的头中出现。

x-tos-server-side-encryption

Header

String

AES256

设置目标对象的加密方式,如果未设置,默认为非加密对象,取值说明如下:

  • AES256:使用 SSE-TOS 加密方式。
  • kms: 使用 SSE-KMS 加密方式。

关于 SSE-TOS、 SSE-KMS 加密方式详细说明,请参见服务端加密概述

说明

使用 SSE-KMS 进行服务端加密会产生 API 调用费用,创建 KMS 密钥会产生密钥托管费用,由 KMS 收取,更多信息,请参见 KMS 计费说明

x-tos-server-side-encryption-kms-key-id

Header

String

否,使用 SSE-KMS 加密时,必选。

trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test

指定 SSE-KMS 加密目标对象使用的主密钥,格式如下:
trn:kms:<region>:<accountID>:keyrings/<keyring>/keys/<key>:KMS 主密钥的 TRN,其中 region 为使用密钥所属 Region ID,accountID 为密钥所属账号的 ID,keyring 为密钥环别名,key 为主密钥别名。

说明

目前不支持默认主密钥,如果指定 SSE-KMS 加密而没有提供该头域,服务端会返回 400 InvalidRequest 错误。

x-tos-server-side-encryption-customer-algorithm

Header

String

否,使用 SSE-C 加密时,必选。

AES256

指定 SSE-C 加密对象要使用的算法,取值说明如下:

  • AES256:使用 AES256 算法加密对象。

x-tos-server-side-encryption-customer-key

Header

String

否,使用 SSE-C 加密时,必选。

YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh****

x-tos-server-side-encryption-customer-algorithm 配套使用,指定 SSE-C 加密目标对象的密钥,格式为 base64 编码的 256 bit 的加密密钥。

x-tos-server-side-encryption-customer-key-MD5

Header

String

否,使用 SSE-C 加密时,必选。

0gYVWExOAz67jX5A6qY4****

x-tos-server-side-encryption-customer-key 配套使用,该头域表示加密对象使用的密钥的MD5值。该头域由密钥的 128-bit MD5 值经过 base64-encoded 得到,该值用于消息完整性检查,确认加密密钥在传输过程中没有出错。

请求元素

名称

位置

参数类型

是否必选

示例值

说明

URL

Body

String

http://abc/obj

需要抓取的 URL。

说明

当前仅支持单个 URL。

IgnoreSameKey

Body

Bool

true

存储桶中存在同名文件时的抓取策略,取值说明如下:

  • true:如果存储桶中已存在同名文件,则放弃本次抓取。
  • false:如果存储桶中已存在同名文件,仍然会抓取对象,并且上传该对象时会覆盖存储桶中原对象。

默认为 false

说明

根据文件的 key 判断是否是同名文件,不会比较文件的内容。

ContentMD5

Body

String

XrY7u+Ae7tCTyyK7j1rN****

待上传文件的 MD5 的 base64 值。设置后,TOS 会计算上传文件的 MD5 值,并与 FetchObject 携带的 MD5 值进行校验,如果校验不通过,则抓取对象会失败。

响应消息头

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

名称

参数类型

说明

x-tos-server-side-encryption

String

对象是 SSE-TOS 加密或 SSE-KMS 时返回该头域,该头域表示对象的服务端加密方式,取值如下:

  • AES256:使用 SSE-TOS 加密方式。
  • kms:使用 SSE-KMS 加密方式。

关于 SSE-TOS、 SSE-KMS 加密方式详细说明,请参见服务端加密概述

x-tos-server-side-encryption-kms-key-id

String

对象采用 SSE-KMS 加密方式时返回该头域,该头域表示 SSE-KMS 加密使用的 KMS 主密钥 ID。

x-tos-server-side-encryption-customer-algorithm

String

对象是 SSE-C 加密时返回此头域,确认使用的加密算法。

x-tos-server-side-encryption-customer-key-MD5

String

对象是 SSE-C 加密时返回此头域,该头域表示加密使用的密钥的 MD5 值。

x-tos-version-id

String

对象的版本号。如果不存在版本号,则该消息头不会出现在响应消息中。

响应元素

名称

参数类型

说明

ETag

String

唯一标识一个对象的内容。

请求示例

POST /objectName?fetch 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/",
}

响应示例

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
Transfer-Encoding: chunked
{
    "ETag": "883abc8623528daf10b7e1bb1b2774ba"
}