## 功能描述调用 FetchObject 接口从指定 URL 抓取资源，并将该资源存储到指定存储桶。 ## 服务端加密如果您使用服务端加密，TOS 在收到您上传的数据时，在文件级别加密这些数据，再将加密的数据持久化存储；您下载文件时，TOS 自动将加密数据解密后返回给您。关于服务端加密的更多详细信息，请参见[服务端加密概述](https://www.volcengine.com/docs/6349/105525)。 ## ACL 您可以通过 headers 去设置对象的 ACL。所有的对象默认是私有的。您可以给某个账号或者预定义组授予对应的权限。关于 ACL 的更多详细信息，请参见 [ACL 策略概述](https://www.volcengine.com/docs/6349/102134)。 ## 存储类型 TOS 默认使用标准存储类型存储对象。标准存储类型是高可用、高可靠、高性能的存储类型。您也可以根据不同的使用场景，选择不同的存储类型。关于存储类型的更多详细信息，请参见[存储类型](https://www.volcengine.com/docs/6349/104493)。 ## 注意事项 |类别 |注意事项 | |---|---| |对象数量 |* 一次只支持抓取一个对象。

* 最大能够支持 5 GiB，大于 5 GiB 的对象，抓取会失败。 | |URL |仅支持抓取可公开访问的 URL 资源。 | |权限 |请确保您使用的火山引擎账号拥有对应存储桶上传对象的权限，否则调用 FetchObject 抓取资源会失败。 | ## 请求消息样式 ```JSON POST /objectName?fetch HTTP/1.1 Host: bucketname.tos-cn-beijing.volces.com Date: GMT Date Authorization: authorization string { "URL": "http://abc.123/" } ``` ## 请求参数和消息头该请求使用的公共请求消息头，请参见[公共参数](https://www.volcengine.com/docs/6349/75044)。 |名称 |位置 |参数类型 |是否必选 |示例值 |说明 | |---|---|---|---|---|---| |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（广州）支持深度冷归档存储，且都处于邀测状态，如您需要使用该存储类型，请联系客户经理。

说明

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

说明

目前不支持默认主密钥，如果指定 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。

说明

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

| |ContentMD5 |Body |String |否 |XrY7u+Ae7tCTyyK7j1rN\*\*\*\* |待上传文件的 MD5 的 base64 值。设置后，TOS 会计算上传文件的 MD5 值，并与 FetchObject 携带的 MD5 值进行校验，如果校验不通过，则抓取对象会失败。 | ## 响应消息头该请求返回的公共响应消息头，请参见[公共参数](https://www.volcengine.com/docs/6349/75044)。 |名称 |参数类型 |示例值 |说明 | |---|---|---|---| |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 加密方式详细说明，请参见[服务端加密概述](https://www.volcengine.com/docs/6349/105525)。 | |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 |唯一标识一个对象的内容。 | ## 请求示例 ```JSON 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 { "URL": "http://abc.123/" } ``` ## 响应示例 ```JSON 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 x-qos-delay-time: 5 Transfer-Encoding: chunked { "ETag": "883abc8623528daf10b7e1bb1b2774ba" } ```

对象存储