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)Untuk informasi tentang cara menghitung signature untuk header Authorization, lihat Header permintaan Authorization.
Saat mengunduh objek besar (lebih dari 100 MB) dari OSS, transfer mungkin gagal karena masalah jaringan. Anda dapat menggunakan permintaan HTTP Range untuk mengambil objek besar secara bertahap. Metode ini memungkinkan unduhan yang dapat dilanjutkan dan unduhan konkuren, serta meningkatkan keandalan transfer. Untuk informasi selengkapnya, lihat Cara mendapatkan sumber daya OSS secara bertahap menggunakan permintaan HTTP Range.
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
Pengendalian versi
Perilaku API
Penagihan dan pembatasan kecepatan
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.
Nilai default: tidak ada |
x-oss-multi-range-behavior | String | Tidak | Mengaktifkan fitur unduhan multi-rentang.
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: 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: 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.
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 |
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.
|
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 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=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/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=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: 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=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/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=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 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:
|
Not Modified | 304 | Kesalahan ini dikembalikan karena alasan berikut:
|
Precondition Failed | 412 | Kesalahan ini dikembalikan karena alasan berikut:
|
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
SDK
Tabel berikut mencantumkan kit pengembangan perangkat lunak (SDK) untuk berbagai bahasa yang dapat Anda gunakan untuk memanggil operasi GetObject.
Antarmuka baris perintah ossutil
Untuk informasi tentang perintah ossutil yang sesuai dengan operasi GetObject, lihat get-object.