AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 对象存储 开发参考 API参考 关于Object操作 基础操作 GetObject

GetObject

更新时间：
产品详情
我的收藏

GetObject接口用于获取Bucket中的对象文件（Object），调用此接口需要对目标对象具有读取权限。

请求语法

GET /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Range: bytes=ByteRange（可选）

  • 关于公共请求头Authorization的计算方法，详见Authorization 请求头。

  • OSS ON云盒环境中调用该接口时，需要将Host替换为云盒Endpoint。详细信息请参考云盒Endpoint。

  • 下载OSS中的大文件（超过100 MB）时，如果传输过程中受到网络环境影响，会导致传输失败。通过HTTP Range请求可获取大文件的部分内容，实现断点续传和并发下载，提升传输可靠性。详细信息参见如何通过HTTP Range请求分段获取OSS资源。

使用说明

GetObject接口默认支持HTTP和HTTPS两种访问方式。支持多范围（Multi-Range）下载功能，可在单次请求中指定多个字节范围进行下载，提升下载效率。

  • 如需设置仅允许通过HTTPS方式访问，可使用Bucket Policy的授权访问方式。

  • 如果Object类型为归档类型，需要先完成解冻文件（RestoreObject）请求或为Object所在Bucket开启归档直读功能。

权限要求

阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限，需要阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予操作权限。

API

Action

说明

GetObject

oss:GetObject

下载Object。

oss:GetObjectVersion

下载Object时，如果通过versionId指定了Object的版本，则需要授予此操作的权限。

kms:Decrypt

下载Object时，如果Object的元数据包含X-Oss-Server-Side-Encryption: KMS，则需要此操作的权限。

版本控制

默认情况下，调用GetObject接口仅返回Object的当前版本。如果在查询参数中指定Object的versionId，则返回指定的Object版本。当versionId指定为null时，则返回versionId为null的Object版本。

接口行为

  • GetObject接口兼容标准RFC协议的API行为。

  • 支持多范围（Multi-Range）下载方式，可以一次下载一个对象的多个Range

    • 只有携带x-oss-multi-range-behavior: multi-range请求头才能触发Multi-Range下载请求。

    • 最大Range区间数量限制为50个。

计费与流控

  • 使用Multi-Range功能时，计费侧GetObject API次数 = 调用API次数 × 每次的Range分片数量。

  • 流控计算逻辑相同，流控侧GetObject API次数 = 调用API次数 × 每次的Range分片数量。

请求参数

请求头

OSS支持在GET请求中通过请求头来自定义响应头，但只有请求成功（即返回码为200 OK）才会将响应头的值设置成GET请求头中指定的值。

OSS不支持在匿名访问的GET请求中自定义响应头。

名称

类型

是否必选

描述

Range

字符串

否

指定文件传输的范围。

  • 如果指定的范围符合规范，返回消息中会包含整个Object的大小和此次返回Object的范围。例如：Content-Range: bytes 0~9/44，表示整个Object大小为44，此次返回的范围为0~9。

  • 如果指定的范围不符合规范，则传送整个Object，并且结果中不包含Content-Range。

  • 当使用x-oss-multi-range-behavior: multi-range时，支持指定多个范围，例如：Range: bytes=0-1,3-4,5-6,7-8。最多支持50个Range区间。

默认值：无

x-oss-multi-range-behavior

字符串

否

开启多范围（Multi-Range）下载功能。

  • 设置为multi-range时，可以在Range头中指定多个字节范围进行下载。

  • 如果指定的范围不符合规范，则传送整个Object。

  • 使用多范围下载时，计费和流控的API调用次数 = 实际调用次数 × Range分片数量。

默认值：无

If-Modified-Since

字符串

否

如果指定的时间早于实际修改时间或指定的时间不符合规范，则直接返回Object，并返回200 OK；如果指定的时间等于或者晚于实际修改时间，则返回304 Not Modified。

时间格式：GMT，例如Fri, 13 Nov 2015 14:47:53 GMT

默认值：无

If-Unmodified-Since

字符串

否

如果指定的时间等于或者晚于Object实际修改时间，则正常传输Object，并返回200 OK；如果指定的时间早于实际修改时间，则返回412 Precondition Failed。

时间格式：GMT，例如Fri, 13 Nov 2015 14:47:53 GMT

If-Modified-Since和If-Unmodified-Since可以同时使用。

默认值：无

If-Match

字符串

否

如果传入的ETag和Object的ETag匹配，则正常传输Object，并返回200 OK；如果传入的ETag和Object的ETag不匹配，则返回412 Precondition Failed。

Object的ETag值用于验证数据是否发生了更改，基于ETag值可验证数据完整性。

默认值：无

If-None-Match

字符串

否

如果传入的ETag值和Object的ETag不匹配，则正常传输Object，并返回200 OK；如果传入的ETag和Object的ETag匹配，则返回304 Not Modified。

If-Match和If-None-Match可以同时使用。

默认值：无

Accept-Encoding

字符串

否

指定客户端的编码类型。

如果要对返回内容进行Gzip压缩传输，需要在请求头中以显示方式加入Accept-Encoding:gzip。

OSS会根据Object的Content-Type和Object大小（不小于1KB），判断传输过程中是否对数据进行Gzip压缩。满足条件时，数据以压缩形式传输，否则，数据以原始形式传输。

  • 如果采用了Gzip压缩且压缩生效，则不会附带ETag和Content-Length信息。

  • 目前OSS支持对以下Content-Type类型的数据进行Gzip压缩：text/cache-manifest、text/xml、text/css、text/html、text/plain、application/javascript、application/x-javascript、application/rss+xml、application/json、text/json。

默认值：无

查询参数

名称

类型

是否必选

描述

response-content-language

字符串

否

指定OSS返回请求的content-language头。

默认值：无

response-expires

字符串

否

指定OSS返回请求的expires头。

默认值：无

response-cache-control

字符串

否

指定OSS返回请求的cache-control头。

默认值：无

response-content-disposition

字符串

否

指定OSS返回请求的content-disposition头。

默认值：无

response-content-encoding

字符串

否

指定OSS返回请求的content-encoding头。

默认值：无

返回参数

响应头

如果Object类型为软链接，则返回目标Object的内容。响应头中Content-Length、ETag、Content-Md5为目标Object的元数据；Last-Modified取目标Object和软链接对应的最大值（即在两者中取更新较晚的时间）；其他均为软链接的元数据。

名称

类型

描述

x-oss-server-side-encryption

字符串

若Object在服务器端采用熵编码加密存储，使用GET请求时，系统会自动解密返回给用户，并且在响应头中返回x-oss-server-side-encryption，表明该Object的服务器端加密算法。

x-oss-sealed-time

字符串

如果Object为已执行Seal操作的Appendable Object，则返回该请求头，表示该文件执行Seal操作的时间。取值类似Sat, 11 Oct 2025 06:41:42 GMT。

x-oss-tagging-count

字符串

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

x-oss-expiration

字符串

配置了生命周期规则的Bucket中Object的过期时间。

  • Bucket已开启版本控制

    • 未携带versionId发起请求

      如果请求的Object命中生命周期的删除规则，响应头中会返回x-oss-expiration头，表示Object当前版本的过期时间。

    • 携带versionId发起请求

      无论请求的Object是否命中生命周期的删除规则，响应头中都不会返回x-oss-expiration头。

  • Bucket未开启版本控制

    • 如果请求的Object命中生命周期的删除规则，则响应头中会返回x-oss-expiration头。

    • 如果请求的Object未命中生命周期的删除规则，则响应头中不会返回x-oss-expiration头。

使用示例

基本下载

  • 请求示例

    GET /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 06:38:30 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

  • 返回示例

    HTTP/1.1 200 OK
x-oss-request-id: 3a8f-2e2d-7965-3ff9-51c875b*****
x-oss-object-type: Normal
Date: Fri, 24 Feb 2012 06:38:30 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E0563E1B002CC607C*****"
Content-Type: image/jpg
Content-Length: 344606
Server: AliyunOSS
[344606 bytes of object data]

范围下载

  • 请求示例

    GET /oss.jpg HTTP/1.1
Host:oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Feb 2012 05:38:42 GMT
Range: bytes=100-900
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

  • 返回示例

    HTTP/1.1 206 Partial Content
x-oss-request-id: 28f6-15ea-8224-234e-c0ce407*****
x-oss-object-type: Normal
Date: Fri, 28 Feb 2012 05:38:42 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E05E1B002CC607C*****"
Accept-Ranges: bytes
Content-Range: bytes 100-900/344606
Content-Type: image/jpg
Content-Length: 801
Server: AliyunOSS
[801 bytes of object data]

多范围下载

  • 请求示例

    GET /oss.jpg HTTP/1.1
Host:oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Feb 2012 05:38:42 GMT
Range: bytes=0-1,3-4,5-6,7-8
x-oss-multi-range-behavior: multi-range
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

  • 返回示例

    HTTP/1.1 206 Partial Content
x-oss-request-id: 28f6-15ea-8224-234e-c0ce407*****
x-oss-object-type: Normal
Date: Fri, 28 Feb 2012 05:38:42 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E05E1B002CC607C*****"
Accept-Ranges: bytes
Content-Type: multipart/byteranges;boundary=63ce7776-c104-417f-8a65-ccaa3b17f428
Content-Length: 446
Server: AliyunOSS

--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 0-1/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 3-4/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 5-6/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 7-8/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428--

自定义响应头

  • 请求示例

    GET /oss.jpg?response-expires=Thu%2C%2001%20Feb%202012%2017%3A00%3A00%20GMT&response-cache-control=No-cache&response-content-disposition=attachment%253B%2520filename%253Dtesting.txt&response-content-encoding=utf-8&response-content-language=%E4%B8%AD%E6%96%87 HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com:
Date: Fri, 24 Feb 2012 06:09:48 GMT

  • 返回示例

    HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC75A644*****
x-oss-object-type: Normal
Date: Fri, 24 Feb 2012 06:09:48 GMT 
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E053D1B002CC607*****"
Content-Length: 344606
Connection: keep-alive
Content-disposition: attachment; filename=testing.txt
Content-language: 中文
Content-type: jpg
Cache-control: no-cache
Expires: Fri, 24 Feb 2012 17:00:00 GMT
Server: AliyunOSS
[344606 bytes of object data]

软链接对象

  • 请求示例

    GET /link-to-oss.jpg HTTP/1.1
Accept-Encoding: identity
Date: Tue, 08 Nov 2016 03:17:58 GMT
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

  • 返回示例

    HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 08 Nov 2016 03:17:58 GMT
Content-Type: application/octet-stream
Content-Length: 20
Connection: keep-alive
x-oss-request-id: 582143E6A212AD*****
Accept-Ranges: bytes
ETag: "8086265EFC021F9A2F09BF4****"
Last-Modified: Tue, 08 Nov 2016 03:17:58 GMT
x-oss-object-type: Symlink
Content-MD5: gIYmXvwCEe0fmi8Jv0Y****

归档对象（已解冻）

  • 请求示例

    GET /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Sat, 15 Apr 2017 09:38:30 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

  • 返回示例

    HTTP/1.1 200 OK
x-oss-request-id: 58F723829F29F18D7F00*****
x-oss-object-type: Normal
x-oss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT"
Date: Sat, 15 Apr 2017 09:38:30 GMT
Last-Modified: Sat, 15 Apr 2017 06:07:48 GMT
ETag: "5B3C1A2E0763E1B002CC607C*****"
Content-Type: image/jpg
Content-Length: 344606
Server: AliyunOSS
[344606 bytes of object data]

版本控制场景

  • 指定版本ID

    • 请求示例

      GET /example?versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0**** HTTP/1.1
Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 02:58:06 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

    • 返回示例

      HTTP/1.1 200 OK
x-oss-request-id: 5CAC0A3EDE0170*****
x-oss-version-id: CAEQNhiBgM0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY*****
x-oss-object-type: Normal
Date: Tue, 17 Apr 2025 02:58:06 GMT
Last-Modified: Fri, 22 Mar 2018 08:07:50 GMT
ETag: "5B3C1A2E053D7002CC607C5A*****"
Content-Type: text/html
Content-Length: 362149
Server: AliyunOSS
[362149 bytes of object data]

  • 当前版本为删除标记

    • 请求示例

      GET /example HTTP/1.1
Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 17 Apr 2025 03:22:33 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

    • 返回示例

      HTTP/1.1 404 Not Found
x-oss-request-id: 5CAC0FEADE0170*****
x-oss-delete-marker: true
x-oss-version-id: CAEQNxiBgyA0BYiIDc4ZDdmNTA2MGViZTRiNjE5NzZlZWM4OWM5OT*****
Date: Tue, 17 Apr 2025 03:22:33 GMT
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
  <RequestId>5CAC0FEADE0170*****</RequestId>
  <HostId>versioning-get.oss-cn-hangzhou.aliyun*****</HostId>
  <Key>example</Key>
</Error>

  • 指定删除标记版本ID

    • 请求示例

      GET /example?versionId=CAEQMxiBgMCfqaWA0BYiIDliMWI4MGQ0MTVmMjQ3MmE5MDNlMmY4YmFkYTk3**** HTTP/1.1
Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 17 Apr 2025 03:09:44 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

    • 返回示例

      HTTP/1.1 405 Method Not Allowed
x-oss-request-id: 5CAC0CF8DE01700*****
x-oss-delete-marker: true
x-oss-version-id: CAEQMxiBgMCfqaWADliMWI4MGQ0MTVmMjQ3MmE5MDNlMmY4YmFkYTk*****
Allow: DELETE
Date: Tue, 17 Apr 2025 03:09:44 GMT
Content-Type: application/xml
Content-Length: 318
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>MethodNotAllowed</Code>
  <Message>The specified method is not allowed against this resource.</Message>
  <RequestId>5CAC0CF8DE0170*****</RequestId>
  <HostId>versioning-get.oss-cn-hangzhou.aliyunc*****</HostId>
  <Method>GET</Method>
  <ResourceType>DeleteMarker</ResourceType>
</Error>

错误码

如果请求失败，OSS将返回包含错误码的响应体，具体错误码如下表所示。

错误码

HTTP状态码

说明

NoSuchKey

404

目标Object不存在。

SymlinkTargetNotExist

404

Object类型为软链接，且目标Object不存在。

InvalidTargetType

400

Object类型为软链接，且目标Object类型仍为软链接。

InvalidObjectState

403

下载归档类型的Object时：

  • 没有提交RestoreObject请求或者上一次提交RestoreObject已经超时。

  • 已经提交RestoreObject请求，但数据的RestoreObject操作还没有完成。

Not Modified

304

返回该错误的可能原因如下：

  • 指定了If-Modified-Since请求头，但请求的Object在指定的时间后没被修改过。

  • 指定了If-None-Match请求头，且请求的Object的ETag值和提供的ETag相等。

Precondition Failed

412

返回该错误的可能原因如下：

  • 指定了If-Unmodified-Since，但指定的时间早于Object实际修改时间 。

  • 指定了If-Match，但请求的Object的ETag值和提供的ETag值不相等。

Not Found

404

在请求中未指定Object的versionId，且Object的当前版本是删除标记（Delete Marker）时，返回该错误。

Method Not Allowed

405

在请求中指定了Object的versionId，且versionId对应的是删除标记时，返回该错误。

集成方式

上一篇：PutObject下一篇：CopyObject