GetObject
更新时间：2026-09-18
接口描述
此命令用于从 BOS 获取某个 Object。此操作需要请求者对该 Object 有读权限。请求者可以在 Header 中设置 Range 来指定需要获取的 Object 数据的范围。
对于开启多版本控制的 Bucket，可以通过请求参数 versionId 获取指定版本的 Object；未指定 versionId 时获取最新版本，指定为 null 时获取空版本信息。
请求
请求结构
获取最新版本或空版本 Object：
Http
1GET /{ObjectKey} HTTP/1.1
2Host: {BucketName}.bj.bcebos.com
3Date: {Date}
4Authorization: {AuthorizationString}
5Range: {RangeString}获取指定版本 Object：
Http
1GET /{ObjectKey}?versionId={VersionId} HTTP/1.1
2Host: {BucketName}.bj.bcebos.com
3Date: {Date}
4Authorization: {AuthorizationString}
5If-Match: {IfMatch}
6If-Modified-Since: {IfModifiedSince}
7If-None-Match: {IfNoneMatch}
8If-Unmodified-Since: {IfUnmodifiedSince}
9Range: {RangeString}请求头域
| 名称 | 类型 | 位置 | 是否必需 | 描述 |
|---|---|---|---|---|
Host |
String | Header | 是 | Bucket 的访问域名，格式为 {BucketName}.bj.bcebos.com。 |
Date |
String | Header | 是 | 请求时间，格式遵循 HTTP 日期格式。 |
Authorization |
String | Header | 是 | 鉴权字符串。 |
Range |
String | Header | 否 | 指定 Object 返回的文件范围。设定 bytes=0-9，表示传送第 0 到第 9 这 10 个字符。默认返回全部数据。 |
If-Match |
String | Header | 否 | 只有 BOS 侧 Object 的 ETag 与 If-Match 提供的值一致时，本次请求才会成功，否则返回 412 Precondition Failed 错误。 |
If-Modified-Since |
String | Header | 否 | 只有 BOS 侧 Object 于 If-Modified-Since 提供的时间之后被修改过，本次请求才会成功，否则返回 304 Not Modified 错误。（注：当 If-None-Match 和 If-Modified-Since 同时存在时，忽略 If-Modified-Since。） |
If-None-Match |
String | Header | 否 | 只有 BOS 侧 Object 的 ETag 与 If-None-Match 提供的值不一致时，本次请求才会成功，否则返回 304 Not Modified 错误。 |
If-Unmodified-Since |
String | Header | 否 | 只有 BOS 侧 Object 于 If-Unmodified-Since 提供的时间之后未被修改过，本次请求才会成功，否则返回 412 Precondition Failed 错误。（注：当 If-Match 和 If-Unmodified-Since 同时存在时，忽略 If-Unmodified-Since。） |
请求参数
| 字段 | 类型 | 位置 | 是否必需 | 描述 |
|---|---|---|---|---|
ObjectKey |
String | Path | 是 | 获取目标 Object 的名称。 |
versionId |
String | Query | 否 | 获取目标 Object 的版本 ID。默认为空，获取最新版本；指定为 null 则获取空版本信息。当版本 ID 包含特殊字符时，需要进行 URL 编码。 |
响应
响应头域
| 名称 | 类型 | 描述 |
|---|---|---|
x-bce-request-id |
String | 请求 ID，用于问题定位。 |
Date |
String | 响应时间。 |
Last-Modified |
String | Object 最后修改时间。 |
Cache-Control |
String | 下载 Object 的 Cache 设置，常见的可取值为 private、no-cache、max-age、must-revalidate。 |
Content-Disposition |
String | 设置浏览器是否下载，可取值为 inline、attachment; filename="download.txt"。 |
Content-Length |
Long Int | 返回 Object 的数据大小。 |
Content-Range |
String | 有 Range 的情况下返回 Object 的数据范围。 |
Content-Type |
String | Object 的类型及编码方式。 |
Expires |
String | 下载 Object 时的缓存失效时间。 |
ETag |
String | Object 的 HTTP 协议实体标签。 |
Accept-Ranges |
String | 表示服务端支持的范围请求单位，通常为 bytes。 |
x-bce-meta-* |
String | 如果有自定义 meta，才返回此项。 |
x-bce-storage-class |
String | 标准存储返回 STANDARD，低频存储返回 STANDARD_IA，冷存储返回 COLD，归档存储返回 ARCHIVE；如果是多 AZ 类型 Bucket，多 AZ 低频存储返回 MAZ_STANDARD_IA，多 AZ 标准存储返回 MAZ_STANDARD。 |
x-bce-server-side-encryption |
String | Object 的服务器端加密类型，当前支持 AES256 和 SM4 加密。 |
x-bce-content-crc32 |
String | 返回 Object 的 CRC32。 |
x-bce-version-id |
String | 返回 Object 的版本 ID。 |
x-bce-expiration-date |
String | 如果设置了对象过期时间，那么显示的是对象过期时间。如果没有设置对象过期时间，那么显示的是对应生命周期规则的过期时间。例如 2025-06-17T08:00:00Z。 |
注意事项
- GetObject 通过
Range参数可以支持断点续传，对于比较大的 Object 建议使用该功能。- 如果在请求头中使用
Range参数，则返回消息中会包含整个文件的长度和此次返回的范围，例如：Content-Range: bytes 0-9/44，表示整个文件长度为 44，此次返回的范围为 0-9。- 对于
Range读大小为 0 字节的对象，会返回 400 错误，Range是前闭后闭区间。- 归档存储类型对象需要先取回才能调用 GetObject 接口。
- 如果请求头中同时包含多个条件 Header（
If-Match、If-None-Match、If-Modified-Since、If-Unmodified-Since），BOS 的判断顺序遵循 RFC 7232 第六章规定，详情请见 RFC 7232。
如需在 response 中获得某些特定 Header 信息，可通过如下两种方式：
-
在 PutObject 时增加 Header 信息，则 GetObject 时会直接返回在 response 里面，请参考 PutObject接口。
注意：
responseContentDisposition的设置在 BOS 自有域名（$region.bcebos.com和*.$region.bcebos.com）无效。 -
GetObject 时，在 queryString 里面直接增加
responseXXX=YYY，返回的 Header 里面会包含XXX: YYY。例如：GET /testBucket/testObject?responseContentType=image%2Fjpg，在这个 HTTP 请求的 response 里面就会有Content-Type: image/jpg。具体的形式为
response$header=urlencode(value)，需要注意，当前$header只支持ContentDisposition、ContentType、ContentLanguage、Expires、CacheControl、ContentEncoding。
响应参数
无结构化响应参数。响应 Body 为 Object 数据；如果请求携带 Range，响应 Body 为指定范围内的 Object 数据。
示例
请求示例
Http
1GET /ObjectName HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: AuthorizationString
5Range: bytes=0-9响应示例
Http
1HTTP/1.1 206 Partial Content
2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
3x-bce-storage-class: STANDARD
4Date: Wed, 06 Apr 2016 06:34:40 GMT
5Last-Modified: Fri, 28 Jan 2011 20:10:32 GMT
6ETag: "b2419b1e3fd45d596ee22bdf62aaaa2f"
7Accept-Ranges: bytes
8Content-Range: bytes 0-9/443
9Content-Type: text/plain
10Content-Length: 10
11Server: BceBos
12
13[10 bytes of object data]多版本请求示例
Http
1GET /ObjectName?versionId=ADCQMlGFiNo%3D HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: AuthorizationString
5Range: bytes=0-9多版本响应示例
Http
1HTTP/1.1 206 Partial Content
2x-bce-request-id: ffaa6a28-1d13-44dd-9266-6ae6181cffdc
3x-bce-storage-class: STANDARD
4Date: Wed, 06 Apr 2016 06:34:40 GMT
5Last-Modified: Fri, 28 Jan 2011 20:10:32 GMT
6ETag: "b2419b1e3fd45d596ee22bdf62aaaa2f"
7Accept-Ranges: bytes
8Content-Range: bytes 0-9/443
9Content-Type: text/plain
10Content-Length: 10
11x-bce-version-id: ADCQMlGFiNo=
12Server: BceBos
13
14[10 bytes of object data]评价此篇文章