功能描述

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

服务端加密

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

ACL

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

存储类型

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

注意事项

类别	注意事项
对象数量	一次只支持抓取一个对象。最大能够支持 5 GiB，大于 5 GiB 的对象，抓取会失败。
URL	仅支持抓取可公开访问的 URL 资源。
权限	请确保您使用的火山引擎账号拥有对应存储桶上传对象的权限，否则调用 FetchObject 抓取资源会失败。

请求消息样式

请求参数和消息头

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

名称	位置	参数类型	是否必选	示例值	说明
fetch	Query	String	是	-	代表 FetchObject 请求的特殊标识。
x-storage-class	Header	string	否	STANDARD	设置目的对象的存储类型。如果未设置，则目的对象的存储类型，和所在桶的默认存储类型保持一致，取值说明如下： STANDARD：标准存储。 IA：低频访问存储。 INTELLIGENT_TIERING：智能分层存储。 ARCHIVE_FR：归档闪回存储。 COLD_ARCHIVE：冷归档存储。说明当前仅华北 2（北京）、华东 2（上海）和华南 1（广州）支持冷归档存储。 DEEP_COLD_ARCHIVE：深度冷归档存储。说明当前仅华北 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-meta-*	Header	string	否	x-tos-meta-key: value	用来加入自定义的元数据，以便对对象进行自定义管理。当用户获取此对象或查询此对象元数据时，加入的自定义元数据将会在返回消息的头中出现。
x-tos-server-side-encryption	Header	String	否	AES256	设置目标对象的加密方式，如果未设置，默认为非加密对象，取值说明如下： AES256：使用 SSE-TOS 加密方式，并采用 AES256 加密算法。 SM4：使用 SSE-TOS 加密方式，并采用 SM4 加密算法。 kms: 使用 SSE-KMS 加密方式。关于 SSE-TOS、 SSE-KMS 加密方式详细说明，请参见服务端加密概述。说明使用 SSE-KMS 进行服务端加密会产生 API 调用费用，创建 KMS 密钥会产生密钥托管费用，由 KMS 收取，更多信息，请参见 KMS 计费说明。
x-tos-server-side-data-encryption	Header	String	否	AES256	设置使用 SSE-KMS 加密方式时的加密算法，取值说明如下： AES256： AES256 加密算法。 SM4: SM4 加密算法。默认为 AES256 算法。
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 得到，该值用于消息完整性检查，确认加密密钥在传输过程中没有出错。
x-tos-fetch-with-header-*	Header	String	否	"x-tos-fetch-with-header-if-match":"d41d8cd98f00b204e9800998********"	在执行 FetchObject 操作时，向源站透传自定义的 Header。如：携带x-tos-fetch-with-header-key1:val1，则在抓取数据时TOS将携带 key1:val1 这个 Header。

请求元素

名称	位置	参数类型	是否必选	示例值	说明
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	kms	对象是 SSE-TOS 加密或 SSE-KMS 时返回该头域，该头域表示对象的服务端加密方式，取值如下： AES256：使用 SSE-TOS 加密方式，并采用 AES256 加密算法。 SM4：使用 SSE-TOS 加密方式，并采用 SM4 加密算法。 kms: 使用 SSE-KMS 加密方式。关于 SSE-TOS、 SSE-KMS 加密方式详细说明，请参见服务端加密概述。
x-tos-server-side-encryption-kms-key-id	String	trn:kms:cn-beijing:2000****:keyrings/ring-test/keys/key-test	对象采用 SSE-KMS 加密方式时返回该头域，该头域表示 SSE-KMS 加密使用的 KMS 主密钥 ID。
x-tos-server-side-encryption-customer-algorithm	String	AES256	对象是 SSE-C 加密时返回此头域，确认使用的加密算法。
x-tos-server-side-encryption-customer-key-MD5	String	0gYVWExOAz67jX5A6qY4+A==	对象是 SSE-C 加密时返回此头域，该头域表示加密使用的密钥的 MD5 值。
x-tos-version-id	String	57AF1A32CECB56721267	对象的版本号。如果不存在版本号，则该消息头不会出现在响应消息中。
x-qos-delay-time	String	5	预计的延迟时间。当AvgQosDelayTime不为 0 时，才会计算并添加 x-qos-delay-time Header。如果该值为 0，则不添加此 Header，标识未受到流控。

响应元素

名称	参数类型	示例值	说明
ETag	String	883abc8623528daf10b7e1bb1b2774ba	唯一标识一个对象的内容。

请求示例

响应示例

对象存储