全部产品
Search
文档中心

Object Storage Service:GetObject

更新时间:Dec 06, 2025

Operasi GetObject mengambil objek dari bucket. Anda harus memiliki izin baca terhadap objek tersebut untuk dapat memanggil operasi ini.

Sintaksis permintaan

GET /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Range: bytes=ByteRange (Opsional)

Catatan penggunaan

Operasi GetObject mendukung akses melalui HTTP dan HTTPS secara default, serta mendukung unduhan multi-rentang. Anda dapat menentukan beberapa rentang byte dalam satu permintaan untuk meningkatkan efisiensi unduhan.

  • Untuk membatasi akses hanya melalui HTTPS, Anda dapat menggunakan kebijakan bucket.

  • Jika objek berada dalam kelas penyimpanan Archive, Anda harus terlebih dahulu mengirim permintaan RestoreObject atau mengaktifkan real-time access of Archive objects untuk bucket tempat objek tersebut disimpan.

Izin

Secara default, Akun Alibaba Cloud memiliki izin penuh atas semua resource dalam akun tersebut. Namun, Pengguna RAM dan Peran RAM tidak memiliki izin apa pun secara default. Pemilik Akun Alibaba Cloud atau administrator harus memberikan izin kepada Pengguna RAM atau Peran RAM melalui Kebijakan RAM atau kebijakan bucket.

API

Action

Definisi

GetObject

oss:GetObject

Mengunduh objek.

oss:GetObjectVersion

Ketika mengunduh objek, jika Anda menentukan versi objek melalui versionId, izin ini diperlukan.

kms:Decrypt

Ketika mengunduh objek, jika metadata objek berisi X-Oss-Server-Side-Encryption: KMS, izin ini diperlukan.

Pengendalian versi

Secara default, pemanggilan operasi GetObject hanya mengembalikan versi terkini dari objek. Jika Anda menentukan versionId objek dalam parameter kueri, operasi tersebut akan mengembalikan versi yang ditentukan. Jika Anda mengatur versionId ke null, operasi tersebut akan mengembalikan versi yang memiliki versionId bernilai null.

Perilaku API

  • Operasi GetObject kompatibel dengan protokol RFC standar.

  • Unduhan multi-rentang didukung. Anda dapat mengunduh beberapa rentang objek sekaligus.

    • Permintaan unduhan multi-rentang hanya dipicu jika permintaan mencakup header permintaan x-oss-multi-range-behavior: multi-range.

    • Jumlah maksimum interval rentang adalah 50.

Penagihan dan pembatasan kecepatan

  • Saat menggunakan fitur multi-rentang, jumlah panggilan API GetObject untuk penagihan dihitung dengan mengalikan jumlah panggilan API dengan jumlah segmen byte-range per panggilan.

  • Logika yang sama berlaku untuk pembatasan kecepatan. Jumlah panggilan API GetObject untuk pembatasan kecepatan dihitung dengan mengalikan jumlah panggilan API dengan jumlah segmen byte-range per panggilan.

Parameter permintaan

Header permintaan

OSS mendukung header respons kustom dalam permintaan GET. Nilai header respons diatur ke nilai yang Anda tentukan dalam header permintaan GET hanya jika permintaan berhasil dan kode balasan adalah 200 OK.

OSS tidak mendukung header respons kustom dalam permintaan GET untuk akses anonim.

Nama

Tipe

Wajib

Deskripsi

Range

String

Tidak

Rentang objek yang akan ditransfer.

  • Jika rentang yang ditentukan valid, pesan respons mencakup ukuran total objek dan rentang objek yang dikembalikan untuk permintaan saat ini. Contohnya, Content-Range: bytes 0-9/44 menunjukkan bahwa ukuran total objek adalah 44 byte dan rentang yang dikembalikan adalah 0-9.

  • Jika rentang yang ditentukan tidak valid, seluruh objek ditransfer, dan respons tidak mencakup Content-Range.

  • Ketika Anda mengatur x-oss-multi-range-behavior ke multi-range, Anda dapat menentukan beberapa rentang. Contohnya: Range: bytes=0-1,3-4,5-6,7-8. Maksimal 50 interval rentang didukung.

Nilai default: tidak ada

x-oss-multi-range-behavior

String

Tidak

Mengaktifkan fitur unduhan multi-rentang.

  • Jika Anda mengatur header ini ke multi-range, Anda dapat menentukan beberapa rentang byte dalam header Range untuk diunduh.

  • Jika rentang yang ditentukan tidak valid, seluruh objek ditransfer.

  • Ketika Anda menggunakan unduhan multi-rentang, jumlah panggilan API untuk penagihan dan pembatasan kecepatan dihitung sebagai: Jumlah panggilan aktual × Jumlah segmen byte-range.

Nilai default: tidak ada

If-Modified-Since

String

Tidak

Jika waktu yang ditentukan lebih awal daripada waktu modifikasi aktual objek atau waktu yang ditentukan tidak valid, objek dikembalikan dengan status 200 OK. Jika waktu yang ditentukan sama dengan atau lebih baru daripada waktu modifikasi aktual, respons 304 Not Modified dikembalikan.

Format: GMT. Contoh: Fri, 13 Nov 2015 14:47:53 GMT

Nilai default: tidak ada

If-Unmodified-Since

String

Tidak

Jika waktu yang ditentukan sama dengan atau lebih baru daripada waktu modifikasi aktual objek, objek ditransfer dan respons 200 OK dikembalikan. Jika waktu yang ditentukan lebih awal daripada waktu modifikasi aktual, respons 412 Precondition Failed dikembalikan.

Format: GMT. Contoh: Fri, 13 Nov 2015 14:47:53 GMT

Anda dapat menggunakan If-Modified-Since dan If-Unmodified-Since secara bersamaan.

Nilai default: tidak ada

If-Match

String

Tidak

Jika ETag yang Anda berikan sesuai dengan ETag objek, objek ditransfer dan respons 200 OK dikembalikan. Jika ETag yang Anda berikan tidak sesuai dengan ETag objek, respons 412 Precondition Failed dikembalikan.

ETag objek digunakan untuk memeriksa apakah data telah berubah. Anda dapat menggunakan nilai ETag untuk memverifikasi integritas data.

Nilai default: tidak ada

If-None-Match

String

Tidak

Jika ETag yang Anda berikan tidak sesuai dengan ETag objek, objek ditransfer dan respons 200 OK dikembalikan. Jika ETag yang Anda berikan sesuai dengan ETag objek, respons 304 Not Modified dikembalikan.

Anda dapat menggunakan If-Match dan If-None-Match secara bersamaan.

Nilai default: tidak ada

Accept-Encoding

String

Tidak

Tipe encoding client.

Untuk mentransfer konten yang dikembalikan dalam format terkompresi Gzip, Anda harus secara eksplisit menambahkan Accept-Encoding:gzip ke header permintaan.

OSS menentukan apakah akan mengompresi data menggunakan Gzip selama transfer berdasarkan Content-Type dan ukuran objek (minimal 1 KB). Jika kondisi terpenuhi, data ditransfer dalam format terkompresi. Jika tidak, data ditransfer dalam format aslinya.

  • Jika kompresi Gzip digunakan dan berlaku, informasi ETag dan Content-Length tidak disertakan.

  • OSS mendukung kompresi Gzip untuk data dengan tipe Content-Type berikut: text/cache-manifest, text/xml, text/css, text/html, text/plain, application/javascript, application/x-javascript, application/rss+xml, application/json, text/json.

Nilai default: tidak ada

Parameter kueri

Nama

Tipe

Wajib

Deskripsi

response-content-language

String

Tidak

Menentukan header content-language yang dikembalikan OSS untuk permintaan tersebut.

Nilai default: tidak ada

response-expires

String

Tidak

Menentukan header expires yang dikembalikan OSS untuk permintaan tersebut.

Nilai default: tidak ada

response-cache-control

String

Tidak

Menentukan header cache-control yang dikembalikan OSS untuk permintaan tersebut.

Nilai default: tidak ada

response-content-disposition

String

Tidak

Menentukan header content-disposition yang dikembalikan OSS untuk permintaan tersebut.

Nilai default: tidak ada

response-content-encoding

String

Tidak

Menentukan header content-encoding yang dikembalikan OSS untuk permintaan tersebut.

Nilai default: tidak ada

Parameter respons

Header respons

Jika objek merupakan tautan simbolik, konten objek target dikembalikan. Dalam header respons, Content-Length, ETag, dan Content-Md5 merupakan metadata objek target. Last-Modified adalah waktu modifikasi terbaru antara objek target dan tautan simbolik. Header lainnya berisi metadata tautan simbolik.

Nama

Tipe

Deskripsi

x-oss-server-side-encryption

String

Jika objek disimpan dengan enkripsi sisi server, objek tersebut secara otomatis didekripsi dan dikembalikan ketika Anda mengirim permintaan GET. Header x-oss-server-side-encryption dikembalikan dalam respons untuk menunjukkan algoritma enkripsi sisi server objek tersebut.

x-oss-sealed-time

String

Jika objek merupakan objek yang dapat ditambahkan dan telah menjalani operasi Seal, header ini dikembalikan untuk menunjukkan waktu ketika operasi Seal dilakukan pada file tersebut. Nilainya mirip dengan Sat, 11 Oct 2025 06:41:42 GMT.

x-oss-tagging-count

String

Jumlah tag yang terkait dengan objek. Header ini hanya dikembalikan jika Anda memiliki izin untuk membaca tag.

x-oss-expiration

String

Waktu kedaluwarsa objek dalam bucket yang dikonfigurasi dengan aturan siklus hidup.

  • Bucket memiliki pengendalian versi diaktifkan

    • Permintaan dikirim tanpa versionId

      Jika objek yang diminta sesuai dengan aturan hapus dalam lifecycle, header x-oss-expiration dikembalikan dalam respons untuk menunjukkan waktu kedaluwarsa versi terkini objek tersebut.

    • Permintaan dikirim dengan versionId

      Header x-oss-expiration tidak dikembalikan dalam respons, terlepas dari apakah objek yang diminta sesuai dengan aturan hapus dalam lifecycle atau tidak.

  • Bucket tidak memiliki pengendalian versi diaktifkan

    • Jika objek yang diminta sesuai dengan aturan hapus dalam lifecycle, header x-oss-expiration dikembalikan dalam respons.

    • Jika objek yang diminta tidak sesuai dengan aturan hapus dalam lifecycle, header x-oss-expiration tidak dikembalikan dalam respons.

Contoh

Unduhan dasar

  • Contoh permintaan

    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
  • Contoh respons (ketika objek berupa file)

    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]
  • Contoh respons (ketika objek berupa folder)

    Ketika objek berupa folder, header respons kustom seperti Range dalam permintaan diabaikan.

    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

Unduhan rentang

  • Contoh permintaan

    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
  • Contoh respons

    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]

Unduhan multi-rentang

  • Contoh permintaan

    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
  • Contoh respons

    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--

Header respons kustom

  • Contoh permintaan

    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
  • Contoh respons

    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: Chinese
    Content-type: jpg
    Cache-control: no-cache
    Expires: Fri, 24 Feb 2012 17:00:00 GMT
    Server: AliyunOSS
    [344606 bytes of object data]

Objek tautan simbolik

  • Contoh permintaan

    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
  • Contoh respons

    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****

Objek Archive (telah dipulihkan)

  • Contoh permintaan

    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
  • Contoh respons

    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]

Skenario pengendalian versi

  • Menentukan ID versi

    • Contoh permintaan

      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
    • Contoh respons

      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]
  • Versi terkini adalah penanda hapus

    • Contoh permintaan

      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
    • Contoh respons

      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>
  • Menentukan ID versi dari penanda hapus

    • Contoh permintaan

      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
    • Contoh respons

      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>

Kode kesalahan

Jika permintaan gagal, OSS mengembalikan badan respons yang berisi kode kesalahan. Tabel berikut mencantumkan kode kesalahan untuk operasi ini.

Kode kesalahan

Kode status HTTP

Deskripsi

NoSuchKey

404

Objek target tidak ada.

SymlinkTargetNotExist

404

Objek merupakan tautan simbolik, dan objek target tidak ada.

InvalidTargetType

400

Objek merupakan tautan simbolik, dan objek target juga merupakan tautan simbolik.

InvalidObjectState

403

Ketika Anda mengunduh objek dengan kelas penyimpanan Archive:

  • Permintaan RestoreObject belum diajukan, atau permintaan RestoreObject terakhir telah kedaluwarsa.

  • Permintaan RestoreObject telah diajukan, tetapi operasi pemulihan belum selesai.

Not Modified

304

Kesalahan ini dikembalikan karena alasan berikut:

  • Header permintaan If-Modified-Since ditentukan, tetapi objek yang diminta belum dimodifikasi setelah waktu yang ditentukan.

  • Header permintaan If-None-Match ditentukan, dan ETag objek yang diminta sama dengan ETag yang diberikan.

Precondition Failed

412

Kesalahan ini dikembalikan karena alasan berikut:

  • Header If-Unmodified-Since ditentukan, tetapi waktu yang ditentukan lebih awal daripada waktu modifikasi aktual objek.

  • Header If-Match ditentukan, tetapi ETag objek yang diminta tidak sama dengan ETag yang diberikan.

Not Found

404

Kesalahan ini dikembalikan jika versionId objek tidak ditentukan dalam permintaan dan versi terkini objek tersebut merupakan penanda hapus.

Method Not Allowed

405

Kesalahan ini dikembalikan jika versionId objek ditentukan dalam permintaan dan versionId tersebut sesuai dengan penanda hapus.

Metode integrasi