Anda dapat memanggil operasi GetBucket (ListObjects) untuk mendaftarkan informasi tentang semua objek dalam sebuah bucket, termasuk nama objek, ukuran, dan waktu modifikasi terakhir.
Catatan penggunaan
Operasi GetBucket (ListObjects) telah diperbarui menjadi GetBucketV2 (ListObjectsV2). Kami menyarankan Anda menggunakan versi GetBucketV2 (ListObjectsV2) yang lebih baru saat mengembangkan aplikasi. Untuk kompatibilitas mundur, OSS tetap mendukung GetBucket (ListObjects). Informasi lebih lanjut tentang GetBucketV2 (ListObjectsV2) dapat ditemukan di ListObjectsV2 (GetBucketV2).
Metadata objek kustom tidak dikembalikan dalam respons terhadap permintaan GetBucket (ListObjects).
Operasi GetBucket (ListObjects) adalah operasi tingkat bucket. Setiap kali Anda memanggil operasi ini, Anda akan dikenakan biaya setara dengan satu permintaan PUT, berdasarkan kelas penyimpanan bucket. Informasi lebih lanjut dapat ditemukan di Permintaan API PUT.
Jika versioning diaktifkan untuk bucket, menimpa atau menghapus objek akan membuat banyak penanda hapus dan versi sebelumnya. Kami menyarankan Anda mengonfigurasi aturan siklus hidup untuk secara berkala menghapus penanda hapus dan versi sebelumnya yang tidak lagi diperlukan. Ini membantu menghindari penurunan kinerja saat Anda mendaftarkan objek.
Sintaksis permintaan
GET / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValueHeader permintaan
Operasi ini hanya menggunakan header permintaan umum, seperti Authorization dan Host. Informasi lebih lanjut dapat ditemukan di Header Permintaan Umum.
Parameter permintaan
Nama | Tipe | Diperlukan | Contoh | Deskripsi |
delimiter | String | Tidak | / | Karakter untuk mengelompokkan nama objek. Semua nama objek yang mengandung string yang sama dari awalan hingga kemunculan pertama delimiter dikelompokkan sebagai elemen tunggal bernama CommonPrefixes. Nilai default: none. |
marker | String | Tidak | test1.txt | Objek tempat operasi pencatatan dimulai. Objek dikembalikan dalam urutan abjad setelah marker yang ditentukan. Marker digunakan untuk paginasi. Nilai parameter ini harus kurang dari 1.024 byte panjangnya. Untuk kueri bersyarat, meskipun marker yang ditentukan tidak ada, pencatatan dimulai dari objek yang secara alfabetis mengikuti marker. Nilai default: none. |
max-keys | String | Tidak | 200 | Jumlah maksimum objek yang akan dikembalikan. Jika pencatatan tidak lengkap karena batasan ini, respons termasuk elemen NextMarker untuk digunakan sebagai marker untuk permintaan berikutnya. Nilai valid: 1 hingga 1.000. Nilai default: 100. |
prefix | String | Tidak | fun | Awalan yang harus dimiliki oleh nama objek yang akan dicantumkan.
Jika Anda mengatur prefix ke nama direktori, semua objek dan subdirektori yang ada secara rekursif dalam direktori tersebut akan dicantumkan. Jika Anda mengatur delimiter ke garis miring (/) berdasarkan prefix, hanya objek dalam direktori yang dicantumkan. Nama subdirektori dalam direktori dikembalikan dalam CommonPrefixes. Objek dan direktori yang ada secara rekursif dalam subdirektori tidak dicantumkan. Sebagai contoh, sebuah bucket berisi tiga objek: fun/test.jpg, fun/movie/001.avi, dan fun/movie/007.avi. Jika Anda mengatur prefix ke fun/, ketiga objek tersebut dikembalikan. Jika Anda mengatur prefix ke fun/ dan delimiter ke garis miring (/), fun/test.jpg dan fun/movie/ dikembalikan. Nilai default: none. |
encoding-type | String | Tidak | url | Tipe pengkodean konten dalam respons. Nilai default: none. Nilai valid: url Penting Nilai delimiter, marker, prefix, NextMarker, dan Key dienkripsi dalam UTF-8. Jika nilai delimiter, marker, prefix, NextMarker, atau Key mengandung karakter kontrol yang tidak didukung oleh XML 1.0, Anda dapat menentukan parameter encoding-type untuk mengkodekan nilai-nilai ini dalam respons. |
Elemen respons
Nama | Tipe | Contoh | Deskripsi |
ListBucketResult | Container | N/A | Wadah untuk hasil permintaan GetBucket. Node anak: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker, dan Contents Node induk: Tidak ada |
Name | String | oss-example | Nama bucket. Node induk: ListBucketResult |
Prefix | String | fun/ | Awalan hasil kueri. Node induk: ListBucketResult atau CommonPrefixes |
Marker | String | test1.txt | Posisi awal operasi GetBucket (ListObjects) ini. Node induk: ListBucketResult |
MaxKeys | String | 100 | Jumlah maksimum hasil yang dikembalikan dalam respons. Node induk: ListBucketResult |
Delimiter | String | / | Karakter yang digunakan untuk mengelompokkan nama objek. Semua nama objek yang mengandung string yang sama dari awalan hingga kemunculan pertama karakter Delimiter dikelompokkan sebagai elemen tunggal bernama CommonPrefixes. Node induk: ListBucketResult |
EncodingType | String | url | Tipe pengkodean yang digunakan untuk hasil yang dikembalikan. Jika Anda menentukan parameter encoding-type dalam permintaan, elemen Delimiter, Marker, Prefix, NextMarker, dan Key dalam respons dienkripsi. Node induk: ListBucketResult |
IsTruncated | String terenumerasi | false | Menunjukkan apakah hasil yang dikembalikan dalam permintaan dipotong. Nilai valid: true dan false
Node induk: ListBucketResult |
NextMarker | String | test100.txt | Posisi awal pencatatan berikutnya. Node induk: ListBucketResult |
Contents | Container | N/A | Wadah untuk metadata setiap objek yang dikembalikan. Node induk: ListBucketResult |
Key | String | fun/test.jpg | Kunci objek. Node induk: ListBucketResult.Contents |
TransitionTime | Waktu | 2024-04-23T07:21:42.000Z | Waktu ketika objek dialihkan ke kelas penyimpanan Cold Archive atau Deep Cold Archive berdasarkan aturan siklus hidup. Catatan
Node induk: ListBucketResult.Contents |
SealedTime | Waktu | 2020-05-21T12:07:15.000Z | Waktu ketika operasi penyegelan dilakukan pada objek. Catatan Bidang ini hanya dikembalikan untuk objek yang dapat ditambahkan yang dibuat menggunakan operasi AppendObject dan telah disegel. Node induk: ListBucketResult.Contents |
LastModified | Waktu | 2012-02-24T08:42:32.000Z | Waktu ketika objek terakhir dimodifikasi. Catatan
Node induk: ListBucketResult.Contents |
ETag | String | 5B3C1A2E053D763E1B002CC607C5A0FE1**** | Tag entitas (ETag). ETag dibuat ketika objek dibuat untuk mengidentifikasi isi objek.
Node induk: ListBucketResult.Contents |
Type | String | Normal | Tipe objek. Nilai valid:
|
Size | String | 344606 | Ukuran objek yang dikembalikan dalam byte. Node induk: ListBucketResult.Contents |
StorageClass | String | Standard | Kelas penyimpanan objek. Node induk: ListBucketResult.Contents |
RestoreInfo | String | ongoing-request="true” | Status pemulihan objek.
|
Owner | Container | N/A | Wadah untuk informasi tentang pemilik bucket. Node anak: DisplayName dan ID Node induk: ListBucketResult.Contents |
ID | String | 0022012**** | ID pengguna pemilik bucket. Node induk: ListBucketResult.Contents.Owner |
DisplayName | String | user_example | Nama pemilik objek. Node induk: ListBucketResult.Contents.Owner |
CommonPrefixes | Container | N/A | Jika Anda menentukan parameter Delimiter dalam permintaan, respons berisi elemen CommonPrefixes. Elemen ini menunjukkan kumpulan nama objek yang memiliki awalan umum dan diakhiri dengan delimiter. Node induk: ListBucketResult |
Informasi lebih lanjut tentang header respons umum lainnya, seperti x-oss-request-id dan Content-Type, dapat ditemukan di Header Respons Umum.
Contoh
Permintaan sederhana
GET / HTTP/1.1 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eRespons contoh
HTTP/1.1 200 OK x-oss-request-id: 534B371674E88A4D8906**** Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 1866 Connection: keep-alive Server: AliyunOSS <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”> <Name>examplebucket</Name> <Prefix></Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter></Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>fun/movie/001.avi</Key> <TransitionTime>2024-04-23T07:21:42.000Z</TransitionTime> <LastModified>2012-02-24T08:43:07.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/movie/007.avi</Key> <LastModified>2012-02-24T08:43:27.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/test.jpg</Key> <LastModified>2012-02-24T08:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>oss.jpg</Key> <LastModified>2012-02-24T06:07:48.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> </ListBucketResult>Permintaan dengan parameter prefix
GET /?prefix=fun HTTP/1.1 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eRespons contoh
HTTP/1.1 200 OK x-oss-request-id: 534B371674E88A4D8906**** Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 1464 Connection: keep-alive Server: AliyunOSS <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”> <Name>examplebucket</Name> <Prefix>fun</Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter></Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>fun/movie/001.avi</Key> <LastModified>2012-02-24T08:43:07.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/movie/007.avi</Key> <LastModified>2012-02-24T08:43:27.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/test.jpg</Key> <LastModified>2012-02-24T08:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> </ListBucketResult>Permintaan dengan parameter prefix dan delimiter
GET /?prefix=fun/&delimiter=/ HTTP/1.1 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eRespons contoh
HTTP/1.1 200 OK x-oss-request-id: 534B371674E88A4D8906**** Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 712 Connection: keep-alive Server: AliyunOSS <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”> <Name>examplebucket</Name> <Prefix>fun/</Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter>/</Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>fun/test.jpg</Key> <LastModified>2012-02-24T08:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> <CommonPrefixes> <Prefix>fun/movie/</Prefix> </CommonPrefixes> </ListBucketResult>Permintaan berhalaman yang menentukan parameter marker
Dalam contoh ini, max-keys diatur ke 2, yang menunjukkan bahwa maksimum dua objek dikembalikan.
GET /?max-keys=2&marker=test1.txt HTTP/1.1 Host: examplebucket.oss-cn-shenzhen.aliyuncs.com Accept-Encoding: identity Accept: */* Connection: keep-alive User-Agent: aliyun-sdk-python/2.11.0(Darwin/18.2.0/x86_64;3.4.1) date: Tue, 26 May 2020 08:39:48 GMT authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eRespons contoh
Elemen NextMarker dalam respons dapat digunakan sebagai marker untuk permintaan berikutnya.
HTTP/1.1 200 OK Server: AliyunOSS Date: Tue, 26 May 2020 08:39:48 GMT Content-Type: application/xml Content-Length: 1032 Connection: keep-alive x-oss-request-id: 5ECCD5D4881816373582xxx x-oss-server-time: 3 <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult> <Name>examplebucket</Name> <Prefix></Prefix> <Marker>test1.txt</Marker> <MaxKeys>2</MaxKeys> <Delimiter></Delimiter> <EncodingType>url</EncodingType> <IsTruncated>true</IsTruncated> <NextMarker>test100.txt</NextMarker> <Contents> <Key>test10.txt</Key> <LastModified>2020-05-26T07:50:18.000Z</LastModified> <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag> <Type>Normal</Type> <Size>1</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>1305433xxx</ID> <DisplayName>1305433xxx</DisplayName> </Owner> </Contents> <Contents> <Key>test100.txt</Key> <LastModified>2020-05-26T07:50:20.000Z</LastModified> <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag> <Type>Normal</Type> <Size>1</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>1305433xxx</ID> <DisplayName>1305433xxx</DisplayName> </Owner> </Contents> </ListBucketResult>Permintaan untuk bucket yang berisi objek Arsip atau Cold Archive
Asumsikan bahwa bucket examplebucket berisi objek exampleobject1.txt, exampleobject2.txt, dan exampleobject3.txt. Ketiga objek tersebut berada dalam kelas penyimpanan Cold Archive. Status ketiga objek tersebut adalah sebagai berikut:
Untuk exampleobject1.txt, permintaan RestoreObject belum diajukan, atau permintaan RestoreObject yang diajukan telah kedaluwarsa.
Untuk exampleobject2.txt, permintaan RestoreObject telah diajukan, dan operasi pemulihan sedang berlangsung.
Untuk exampleobject3.txt, permintaan RestoreObject telah diajukan dan operasi pemulihan selesai.
Permintaan contoh
GET / HTTP/1.1 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eRespons contoh
HTTP/1.1 200 OK x-oss-request-id: 534B371674E88A4D8906**** Date: Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 1866 Connection: keep-alive Server: AliyunOSS <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”> <Name>examplebucket</Name> <Prefix></Prefix> <Marker></Marker> <MaxKeys></MaxKeys> <Delimiter></Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>exampleobject1.txt</Key> <LastModified>2020-06-22T11:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>ColdArchive</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>exampleobject2.txt</Key> <LastModified>2020-06-22T11:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <RestoreInfo>ongoing-request="true"</RestoreInfo> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>exampleobject3.txt</Key> <LastModified>2020-06-22T11:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <RestoreInfo>ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"</RestoreInfo> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> </ListBucketResult>
SDK
Anda dapat menggunakan SDK untuk bahasa pemrograman berikut untuk memanggil operasi ini:
Alat baris perintah ossutil
Informasi lebih lanjut tentang perintah ossutil yang sesuai dengan operasi GetBucket dapat ditemukan di list-objects (get-bucket).
Kode kesalahan
Kode kesalahan | Status HTTP | Deskripsi |
NoSuchBucket | 404 | Bucket yang ditentukan tidak ada. Periksa apakah nama bucket valid. |
AccessDenied | 403 | Anda tidak memiliki izin yang diperlukan untuk mengakses bucket. Hanya pemilik bucket dan pengguna yang diberikan izin |
InvalidArgument | 400 |
|