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

GetObject

最近更新时间：2024.03.20 17:34:49

首次发布时间：2021.10.13 16:14:07

我的收藏

功能描述

此接口用于从桶中下载指定对象。桶的拥有者或者被授权的用户才具有调用此接口下载对象的权限。多版本状态下，如果未指定版本号，下载当前版本的对象，如果指定versionId，则返回指定版本的对象。

服务端加密

如果要下载的对象使用 TOS 托管加密密钥的服务端加密（SSE-TOS）或使用 KMS 托管加密密钥的服务端加密（SSE-KMS），则不应在 GET 请求中携带加密请求头域，如：x-tos-server-side-encryption，如果携带了该加密头域，会收到 HTTP 400 BadRequest 错误。
如果客户端在对象上传时，使用客户提供的加密密钥（SSE-C）进行服务端加密，当下载对象时，你必须携带以下头域：

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

关于服务端加密的更多详细信息，请参见服务端加密概述。

注意事项

使用 GetObject 接口下载归档存储、冷归档存储和深度冷归档存储对象前，需要先恢复对象。

请求消息样式

GET /objectName HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: GMT Date
Authorization: authorization string

请求参数和消息头

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

名称

位置

参数类型

是否必选

示例值

说明

Range

Header

String

否

bytes=0-4

指定对象的获取范围。如未指定，则获取整个对象。Range 是一个范围，它的起始值最小为 0，最大为对象长度减 1。Range 范围的起始值为必填项，如果 Range 只包含起始值，表示获取起始值到对象长度减 1 这个区间的对象内容。格式为：bytes=start-end。

说明

携带 Range 头域后，响应消息的 ETag 仍是对象的 ETag，而不是 Range 范围内对象的 ETag。

If-Match

Header

String

否

8a36be0d764367db4eea2deb16b71543

只有当传入的 ETag 与对象的 ETag 相等才返回对象，否则返回 412 Precondition Failed。

If-Modified-Since

Header

String

否

Mon, 04 Jul 2022 02:57:31 GMT

只有在对象自指定时间以来被修改过时才返回该对象，否则返回 304 Not Modified。时间格式为 RFC1123 GMT。

If-None-Match

Header

String

否

8a36be0d764367db4eea2deb16b71543

只有当传入的 ETag 与对象的 ETag 不相等才返回对象，否则返回 304 Not Modified。

If-Unmodified-Since

Header

String

否

Mon, 04 Jul 2022 02:57:31 GMT

只有在对象自指定时间以来未被修改过时才返回该对象，否则返回412 Precondition Failed。时间格式为 RFC1123 GMT。

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 加密时，必选。

YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE=

与 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+A==

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

x-tos-traffic-limit

Header

String

否

819200

TOS 提供单链接限速功能，在上传、下载文件等操作中进行流控控制，以保证其他应用的网络带宽。取值说明如下：

  • 取值范围：245760-838860800，单位为bit/s
  • Header和Query中不能同时存在此参数

x-tos-traffic-limit

Query

String

否

819200

TOS 提供单链接限速功能，在上传、下载文件等操作中进行流控控制，以保证其他应用的网络带宽。取值说明如下：

  • 取值范围：245760-838860800，单位为bit/s
  • Header和Query中不能同时存在此参数

response-content-disposition

Query

String

否

attachment; filename=123.txt

指定服务端返回的 Content-Disposition 响应头。

response-content-encoding

Query

String

否

gzip

指定服务端返回的 Content-Encoding 响应头。

response-content-language

Query

String

否

en-US

指定服务端返回的 Content-Language 响应头。

response-content-type

Query

String

否

text/plain

指定服务端返回的 Content-Type 响应头。

response-expires

Query

String

否

Mon, 04 Jul 2022 02:57:31 GMT

指定服务端返回的 Expires 响应头。

versionId

Query

String

否

123

获取指定版本号的对象。

请求元素

该请求消息中无请求元素。

响应消息头

该请求返回公共响应消息头，请参见公共参数。

名称

参数类型

说明

Content-Range

String

返回的对象数据范围。

Last-Modified

String

对象最后更新日期。

x-tos-delete-marker

Bool

对象是否标记删除。如果不是，不会返回此消息头。

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

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

x-tos-website-redirect-location

String

当桶设置了 Website 配置，可以将获取这个对象的请求重定向到桶内另一个对象或一个外部的 URL，TOS 将这个值从头域中取出，保存在对象的元数据中。

x-tos-object-type

String

对象为非 Normal 对象时，会返回此头域，取值说明如下：

  • Appendable：该对象为追加写接口上传的对象。

x-tos-storage-class

String

对象的存储类型，取值说明如下：

  • STANDARD：标准存储。
  • IA：低频访问存储。
  • INTELLIGENT_TIERING：智能分层存储。
  • ARCHIVE_FR：归档闪回存储。
  • ARCHIVE：归档存储。
  • COLD_ARCHIVE：冷归档存储。
  • DEEP_COLD_ARCHIVE：深度冷归档存储。

说明

深度冷归档目前处于邀测状态，如您需要使用该存储类型，请联系客户经理。

x-tos-hash-crc64ecma

Integer

表示该对象的 64 位 CRC 值。该 64 位 CRC 根据 ECMA-182 标准计算得出。

说明

对 TOS 服务端支持 64 位 CRC 校验前创建的对象，则该消息头不会出现在响应消息中。

x‑tos‑tagging‑count

String

对象的标签个数。仅当拥有对象标签读取权限时返回。

X-Tos-Expiration

String

如果对象所在的桶设置了删除生命周期规则，且对象匹配该生命周期规则，将返回该头域。返回内容如下：

  • expiry-date：对象的删除日期。
  • rule-id：生命周期规则 ID。

x-tos-replication-status

String

对象的跨区域或同区域复制状态，存在以下两种情况：

  • 如果是源存储桶的对象，该参数取值如下：
    • COMPLETE：该对象已成功复制到目标桶。
    • PENDING：该对象正在复制中。
    • FAILED：该对象复制失败。
  • 如果是目标存储桶的对象，该参数只有一个取值，即 REPLICA，表示该对象是通过跨区域复制或同区域复制功能同步过来的。

注意

  • 查询对象跨区域复制或同区域复制状态功能（即 x-tos-replication-status 参数）目前处于邀测状态，如您需要使用该功能，请联系客户经理。
  • 仅该对象为跨区域复制或同区域复制规则中源存储桶或目标存储桶的对象时，才会返回该参数。
  • 仅支持查询配置了一条跨区域复制规则或同区域复制规则的源存储桶的对象复制状态，例如在源存储桶设置了多条复制规则，将 A 对象复制到 B、C、D 存储桶，则不支持查询 A 对象的复制状态。目标存储桶的对象则没有该限制。

x-tos-restore

String

如果对象为归档、冷归档或深度冷归档对象（即存储类型为 ARCHIVE 、COLD_ARCHIVE 或 DEEP_COLD_ARCHIVE），会返回副本删除时间，例如
ongoing-request="false", expiry-date="Sat, 1 Jan 2022 00:00:00 GMT"。

响应元素

该请求响应中无消息元素。

请求示例

GET /objectName HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 GMT
Authorization: authorization string

响应示例

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 120
Date: Fri, 30 Jul 2021 08:05:36 GMT
ETag: "900150983cd24fb0d6963f7d28e17f72"
Last-Modified: Mon, 02 Jul 2021 10:29:28 GMT
server: TosServer
x-tos-id-2: d604607e63b001f-a444ed0
x-tos-request-id: d604607e63b001f-a444ed0
x-tos-hash-crc64ecma: 6186290338114851376

[ 120 Bytes object content]