全部產品
Search

搜尋本產品

    Object Storage Service：GetObject

    文件中心

    Object Storage Service：GetObject

    更新時間：Dec 05, 2025

    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中的大檔案（超過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

    • 返回樣本（當Object為檔案時）

      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]

    • 返回樣本（當Object為目錄時）

      當Object為目錄時，如果請求中帶有自訂返回訊息頭例如Range等，則自訂的返回訊息頭無效。

      HTTP/1.1 200 OK
x-oss-request-id: 3a8f-2e2d-7965-3ff9-51c875b*****
x-oss-object-type: Normal
Date: Wed, 31 Mar 2021 06:38:30 GMT
Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
ETag: "null"
Content-Type: application/x-directory
Content-Length: 0
Server: AliyunOSS

    範圍下載

    • 請求樣本

      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對應的是刪除標記時，返回該錯誤。

    整合方式