Operasi GetObject mengunduh objek dari bucket. Anda harus memiliki izin baca terhadap objek tersebut untuk dapat memanggil operasi ini.
Sintaks permintaan
GET /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Range: bytes=ByteRange (Opsional)Untuk informasi tentang cara menghitung signature untuk header Authorization, lihat Authorization request header.
Saat mengunduh objek besar (lebih dari 100 MB) dari Object Storage Service (OSS), transfer mungkin gagal karena masalah jaringan. Anda dapat menggunakan permintaan HTTP Range untuk mengambil objek besar secara bertahap. Metode ini mendukung unduhan yang dapat dilanjutkan dan unduhan konkuren, sehingga meningkatkan keandalan transfer. Untuk informasi selengkapnya, lihat Cara memperoleh resource OSS secara bertahap menggunakan permintaan HTTP Range.
Catatan penggunaan
Operasi GetObject mendukung akses melalui HTTP dan HTTPS secara default serta mendukung unduhan multi-rentang, yang memungkinkan Anda menentukan beberapa rentang byte dalam satu permintaan guna meningkatkan efisiensi unduhan.
Untuk membatasi akses hanya melalui HTTPS, gunakan bucket policy.
Jika objek berada dalam kelas penyimpanan Archive, Anda harus terlebih dahulu memulihkannya dengan mengirim permintaan RestoreObject atau mengaktifkan akses real-time untuk bucket tempat objek tersebut disimpan.
Izin
Pengendalian versi
Perilaku API
Penagihan dan pembatasan kecepatan
Parameter permintaan
Header permintaan
OSS memungkinkan Anda menyesuaikan header respons dalam permintaan GET. OSS mengatur header respons ke nilai yang Anda tentukan dalam permintaan GET, tetapi hanya jika permintaan berhasil dengan kode status 200 OK.
OSS tidak mendukung header respons kustom dalam permintaan GET untuk akses anonim.
Parameter | Type | Wajib | Deskripsi |
Range | String | Tidak | Menentukan rentang byte objek yang akan diunduh.
Nilai default: Tidak ada |
x-oss-multi-range-behavior | String | Tidak | Mengaktifkan unduhan multi-rentang.
Nilai default: Tidak ada |
If-Modified-Since | String | Tidak | Jika waktu yang ditentukan lebih awal daripada waktu modifikasi aktual objek, atau jika waktu yang ditentukan tidak valid, objek dikembalikan dengan status Format: GMT. Contoh: 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 status Format: GMT. Contoh: 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 status 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 status Anda dapat menggunakan If-Match dan If-None-Match secara bersamaan. Nilai default: Tidak ada |
Accept-Encoding | String | Tidak | Menentukan jenis encoding client. Untuk mentransfer konten yang dikembalikan dalam format terkompresi Gzip, Anda harus secara eksplisit menambahkan OSS mengompresi objek dengan Gzip untuk transfer jika ukurannya minimal 1 KB dan Content-Type-nya didukung. Jika tidak, OSS mentransfer objek tanpa kompresi.
Nilai default: Tidak ada |
Parameter kueri
Parameter | Tipe | Wajib | Deskripsi |
response-content-language | String | Tidak | Menentukan header Nilai default: Tidak ada |
response-expires | String | Tidak | Menentukan header Nilai default: Tidak ada |
response-cache-control | String | Tidak | Menentukan header Nilai default: Tidak ada |
response-content-disposition | String | Tidak | Menentukan header Nilai default: Tidak ada |
response-content-encoding | String | Tidak | Menentukan header Nilai default: Tidak ada |
Parameter respons
Header respons
Jika objek merupakan tautan simbolik, OSS mengembalikan konten objek target. Dalam header respons, Content-Length, ETag, dan Content-Md5 merupakan metadata objek target. Last-Modified adalah waktu modifikasi yang lebih baru antara objek target dan tautan simbolik. Header lain berisi metadata tautan simbolik.
Parameter | Type | Deskripsi |
x-oss-server-side-encryption | String | Jika objek disimpan dengan enkripsi sisi server, OSS secara otomatis mendekripsi dan mengembalikan objek dalam permintaan GET. Header |
x-oss-sealed-time | String | Jika objek merupakan objek yang dapat ditambahkan dan telah disegel, header ini menunjukkan kapan operasi Seal dilakukan. Contoh: |
x-oss-tagging-count | String | Jumlah tag yang terkait dengan objek. Header ini hanya disertakan jika Anda memiliki izin untuk membaca tag. |
x-oss-expiration | String | Waktu kedaluwarsa objek dalam bucket yang dikonfigurasi dengan aturan siklus hidup.
|
x-oss-object-worm-mode | String | Mode kebijakan retensi objek. Jika objek dikonfigurasi dengan kebijakan retensi tingkat objek, nilainya adalah |
x-oss-object-worm-retain-until-date | String | Tanggal kedaluwarsa retensi objek, dalam format ISO 8601. Objek tidak dapat dihapus atau ditimpa sebelum tanggal ini. Header ini hanya disertakan ketika ObjectWorm diaktifkan untuk bucket, pemanggil memiliki izin |
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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eContoh respons (ketika objek adalah 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/jpeg Content-Length: 344606 Server: AliyunOSS [344606 bytes of object data]Contoh respons (ketika objek adalah direktori)
Saat meminta objek direktori, header permintaan yang menyesuaikan respons, seperti
Range, 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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eContoh 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/jpeg 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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eContoh 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 GMTContoh 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: 中文 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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eContoh 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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eContoh 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/jpeg 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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eContoh 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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eContoh 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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eContoh 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 beberapa kode kesalahan umum untuk operasi ini.
Kode kesalahan | Kode status HTTP | Deskripsi |
NoSuchKey | 404 | Objek yang ditentukan 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 | Kesalahan ini dikembalikan ketika Anda mencoba mengunduh objek dengan kelas penyimpanan Archive dalam kondisi berikut:
|
Not Modified | 304 | Kesalahan ini dapat dikembalikan karena alasan berikut:
|
Precondition Failed | 412 | Kesalahan ini dapat dikembalikan karena alasan berikut:
|
Not Found | 404 | Kesalahan ini dikembalikan jika |
Method Not Allowed | 405 | Kesalahan ini dikembalikan jika |