Object Storage Service ListObjectsV2 (GetBucketV2) API - Object Storage Service

Operasi ListObjectsV2 (GetBucketV2) mencantumkan informasi mengenai objek dalam sebuah bucket.

Sintaksis permintaan

GET /?list-type=2 HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Catatan penggunaan

Permintaan ListObjectsV2 (GetBucketV2) tidak mengembalikan metadata objek kustom. Secara default, satu respons berisi maksimal 100 objek. Untuk mengambil semua objek, Anda harus melakukannya secara bertahap menggunakan parameter seperti NextContinuationToken dan continuationToken.

Untuk mencantumkan semua objek dalam sebuah bucket, Anda harus memiliki izin oss:ListObjects.
Jika Anda mengaktifkan log storage atau real-time log query, nilai bidang operation dalam access log yang dihasilkan untuk operasi ini adalah GetBucket.
Jika versioning diaktifkan untuk sebuah bucket, operasi overwrite atau penghapusan tidak sengaja akan menghasilkan banyak delete marker dan versi sebelumnya. Konfigurasikan aturan lifecycle untuk membersihkan delete marker dan versi sebelumnya yang tidak diperlukan secara berkala guna mencegah penurunan performa pencatatan.
Pemanggilan operasi ListObjectsV2 (GetBucketV2) ditagih sebagai permintaan PUT. Untuk informasi selengkapnya, lihat PUT requests.

Parameter permintaan

Name	Type	Required	Example	Description
list-type	Number	Yes	2	Nilainya tetap 2.
delimiter	String	No	/	Karakter untuk mengelompokkan nama objek. Semua nama objek yang mengandung awalan yang ditentukan dan muncul sebelum kemunculan pertama delimiter dikelompokkan sebagai satu elemen (CommonPrefixes). Nilai default: none
start-after	String	No	b	Menentukan bahwa daftar objek dikembalikan mulai dari objek yang secara alfabetis mengikuti nilai start-after. Parameter ini digunakan untuk pagination. Panjang parameter ini harus kurang dari 1024 byte. Untuk kueri kondisional, meskipun nilai start-after tidak ada dalam daftar, respons dimulai dari objek berikutnya yang mengikuti nilai start-after tersebut secara alfabetis. Nilai default: none
continuation-token	String	No	test1.txt	Menentukan token tempat operasi pencatatan dimulai. Anda dapat memperoleh token ini dari nilai NextContinuationToken dalam respons operasi ListObjectsV2 (GetBucketV2) sebelumnya.
max-keys	Number	No	100	Menentukan jumlah maksimum objek yang dikembalikan. Nilainya harus lebih besar dari 0 dan kurang dari atau sama dengan 1000. Nilai default: 100 Jika tidak semua objek dapat dicantumkan dalam satu respons karena pengaturan max-keys, respons tersebut menyertakan `NextContinuationToken`. Gunakan token ini sebagai `continuation-token` untuk permintaan berikutnya. Jumlah objek yang dikembalikan tidak dijamin mencapai nilai max-keys yang ditentukan. Jika hal ini terjadi, ambil `NextContinuationToken` dari respons dan gunakan sebagai `continuation-token` untuk permintaan berikutnya.
prefix	String	No	a	Membatasi respons hanya pada kunci yang diawali dengan awalan yang ditentukan. Jika Anda menetapkan prefix ke nama folder, operasi ini mencantumkan semua file dan subfolder secara rekursif di dalam folder tersebut. Jika Anda menggunakan parameter prefix bersamaan dengan parameter delimiter yang diatur ke garis miring (/), operasi ini hanya mencantumkan file langsung di dalam folder tersebut. Nama subfolder dikembalikan dalam CommonPrefixes, dan isi subfolder tidak dicantumkan. Sebagai contoh, sebuah bucket berisi tiga objek: fun/test.jpg, fun/movie/001.avi, dan fun/movie/007.avi. Jika Anda menetapkan prefix ke fun/, ketiga objek tersebut dikembalikan. Jika Anda menetapkan prefix ke fun/ dan delimiter ke garis miring (/), file fun/test.jpg dan folder fun/movie/ dikembalikan. Panjang parameter ini harus kurang dari 1024 byte. Parameter prefix tidak boleh diawali dengan garis miring (/). Jika parameter prefix kosong, semua objek dalam bucket akan dicantumkan secara default. Saat Anda melakukan kueri menggunakan prefix, kunci yang dikembalikan tetap menyertakan prefix tersebut. Nilai default: none
encoding-type	String	No	url	Encode respons dan tentukan jenis encoding-nya. Nilai default: none Nilai valid: url Jika `delimiter`, `start-after`, `prefix`, `NextContinuationToken`, atau `Key` mengandung karakter kontrol yang tidak didukung oleh XML 1.0, Anda dapat menentukan parameter `encoding-type` untuk melakukan URL-encode terhadap elemen-elemen tersebut dalam respons. Parameter `delimiter`, `start-after`, `prefix`, `NextContinuationToken`, dan `Key` menggunakan character encoding UTF-8.
fetch-owner	Boolean	No	false	Menentukan apakah informasi pemilik disertakan dalam respons. Nilai valid: true, false true: Respons menyertakan informasi pemilik. false: Respons tidak menyertakan informasi pemilik. Nilai default: false

Parameter respons

Name	Type	Example	Description
Contents	Container	N/A	Wadah untuk metadata setiap objek yang dikembalikan. Node induk: ListBucketResult
CommonPrefixes	Container	N/A	Jika permintaan menentukan parameter Delimiter, respons menyertakan elemen CommonPrefixes. Elemen ini menunjukkan kumpulan nama objek yang diakhiri dengan delimiter dan memiliki awalan umum. Node induk: ListBucketResult Node anak: Prefix
Delimiter	String	/	Karakter yang digunakan untuk mengelompokkan nama objek. Semua nama objek yang mengandung awalan yang ditentukan dan muncul sebelum kemunculan pertama delimiter dikelompokkan sebagai elemen CommonPrefixes. Node induk: ListBucketResult
EncodingType	String	N/A	Jenis encoding yang digunakan dalam respons. Jika `encoding-type` ditentukan dalam permintaan, elemen `Delimiter`, `StartAfter`, `Prefix`, `NextContinuationToken`, dan `Key` dalam respons akan di-encode. Node induk: ListBucketResult
DisplayName	String	user_example	Nama tampilan pemilik objek. Node induk: ListBucketResult.Contents.Owner
ETag	String	5B3C1A2E053D763E1B002CC607C5A0FE1****	ETag dibuat saat objek dihasilkan dan secara unik mengidentifikasi konten objek tersebut. Node induk: ListBucketResult.Contents Untuk objek yang dibuat melalui permintaan PutObject, nilai ETag adalah Hash MD5 dari kontennya. Untuk objek yang dibuat dengan cara lain, nilai ETag adalah nilai unik yang dihasilkan berdasarkan aturan perhitungan tertentu, tetapi bukan Hash MD5 dari kontennya. Nilai ETag dapat digunakan untuk memeriksa apakah konten objek telah berubah. Jangan gunakan nilai ETag sebagai dasar Validasi MD5 untuk memastikan integritas data.
ID	String	0022012****	ID pengguna pemilik bucket. Node induk: ListBucketResult.Contents.Owner
IsTruncated	Enumerated string	false	Menunjukkan apakah hasil yang dikembalikan terpotong. Nilai kembali: true, false true menunjukkan bahwa tidak semua hasil dikembalikan. false menunjukkan bahwa semua hasil dikembalikan. Node induk: ListBucketResult
Key	String	fun/test.jpg	Nama kunci objek. Node induk: ListBucketResult.Contents
LastModified	Time	2012-02-24T08:42:32.000Z	Waktu terakhir objek dimodifikasi. Node induk: ListBucketResult.Contents
ListBucketResult	Container	N/A	Wadah untuk hasil permintaan GetBucket. Node anak: Name, Prefix, StartAfter, MaxKeys, Delimiter, IsTruncated, NextContinuationToken, Contents Node induk: None
StartAfter	String	test1.txt	Jika permintaan menentukan parameter StartAfter, respons menyertakan elemen StartAfter.
MaxKeys	Number	100	Jumlah maksimum hasil yang dikembalikan dalam respons. Node induk: ListBucketResult
Name	String	examplebucket	Nama bucket. Node induk: ListBucketResult
Owner	Container	N/A	Wadah untuk informasi pemilik bucket. Node anak: DisplayName, ID Node induk: ListBucketResult.Contents
Prefix	String	fun/	Awalan hasil kueri. Node induk: ListBucketResult
Type	String	Normal	Jenis file Nilai valid: Normal, Multipart, Appendable, dan Symlink. Node induk: ListBucketResult.Contents
Size	Number	344606	Ukuran objek dalam byte. Node induk: ListBucketResult.Contents
StorageClass	String	Standard	Kelas penyimpanan objek. Node induk: ListBucketResult.Contents
SealedTime	Time	2020-05-21T12:07:15.000Z	Waktu operasi Seal dilakukan pada objek. Bidang ini dikembalikan saat Anda mengakses Appendable Object yang berada dalam keadaan Sealed. Node induk: ListBucketResult.Contents
ContinuationToken	String	test1.txt	Jika permintaan menentukan parameter ContinuationToken, respons menyertakan elemen ContinuationToken. Node induk: ListBucketResult
KeyCount	Number	6	Jumlah kunci yang dikembalikan dalam permintaan ini. Jika parameter Delimiter ditentukan, KeyCount adalah jumlah total elemen Key dan CommonPrefixes. Node induk: ListBucketResult
NextContinuationToken	String	CgJiYw--	Menunjukkan bahwa permintaan ListObjectsV2 (GetBucketV2) masih memiliki hasil tambahan. Untuk mendapatkan set hasil berikutnya, tentukan nilai NextContinuationToken sebagai ContinuationToken untuk permintaan berikutnya. Node induk: ListBucketResult
RestoreInfo	String	ongoing-request="true"	Keadaan dipulihkan objek. Bidang ini tidak dikembalikan jika tidak ada permintaan RestoreObject yang diajukan atau permintaan RestoreObject telah kedaluwarsa. Jika permintaan RestoreObject diajukan tetapi operasi restore belum selesai, nilai RestoreInfo adalah `ongoing-request="true"`. Jika permintaan RestoreObject diajukan dan operasi restore telah selesai, nilai RestoreInfo adalah `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"`. Bidang `expiry-date` menunjukkan waktu kedaluwarsa objek yang telah dipulihkan. Node induk: ListBucketResult.Contents

Contoh

Permintaan sederhana

Contoh permintaan

GET /?list-type=2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 08:43:27 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: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 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>
    <MaxKeys>100</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a</Key>
        <LastModified>2020-05-18T05:45:43.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>b</Key>
        <LastModified>2020-05-18T05:45:50.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>b/c</Key>
        <LastModified>2020-05-18T05:45:54.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>bc</Key>
        <LastModified>2020-05-18T05:45:59.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>c</Key>
        <LastModified>2020-05-18T05:45:57.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <KeyCount>6</KeyCount>
</ListBucketResult>

Permintaan dengan parameter prefix

Contoh permintaan

GET /?list-type=2&prefix=a HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 08:43:27 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: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 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>a</Prefix>
    <MaxKeys>100</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a</Key>
        <LastModified>2020-05-18T05:45:43.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <KeyCount>2</KeyCount>
</ListBucketResult>

Permintaan dengan parameter prefix dan delimiter

Contoh permintaan

GET /?list-type=2&prefix=a/&delimiter=/ HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 08:43:27 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: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 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>a/</Prefix>
    <MaxKeys>100</MaxKeys>
    <Delimiter>/</Delimiter>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <CommonPrefixes>
        <Prefix>a/b/</Prefix>
    </CommonPrefixes>
    <KeyCount>2</KeyCount>
</ListBucketResult>

Permintaan dengan parameter start-after, max-keys, dan fetch-owner

Contoh permintaan

GET /?list-type=2&start-after=b&max-keys=3&fetch-owner=true HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 08:43:27 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: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 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></Prefix>
    <StartAfter>b</StartAfter>
    <MaxKeys>3</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>true</IsTruncated>
    <NextContinuationToken>CgJiYw--</NextContinuationToken>
    <Contents>
        <Key>b/c</Key>
        <LastModified>2020-05-18T05:45:54.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>ba</Key>
        <LastModified>2020-05-18T11:17:58.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>bc</Key>
        <LastModified>2020-05-18T05:45:59.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <KeyCount>3</KeyCount>
</ListBucketResult>

Permintaan untuk bucket yang berisi objek Archive atau Cold Archive

Contoh permintaan

GET /?list-type=2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 08:43:27 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: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 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>
  <MaxKeys>100</MaxKeys>
  <EncodingType>url</EncodingType>
  <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>

Berikut penjelasan mengenai status file:

Untuk exampleobject1.txt, permintaan RestoreObject belum diajukan atau telah kedaluwarsa.
Untuk exampleobject2.txt, permintaan RestoreObject telah diajukan, tetapi proses restore belum selesai.
Untuk exampleobject3.txt, permintaan RestoreObject telah diajukan, dan proses restore telah selesai.

Kode error

Error code	HTTP status code	Description
NoSuchBucket	404	Bucket yang ditentukan tidak ada. Periksa apakah nama bucket dalam permintaan sesuai dengan Konvensi penamaan.
AccessDenied	403	Anda tidak memiliki izin untuk mengakses bucket tersebut. Hanya pemilik bucket dan pengguna yang diberikan izin `oss:ListObjects` yang dapat mengakses bucket tersebut.
InvalidArgument	400	Nilai parameter max-keys kurang dari 0 atau lebih dari 1000. Panjang parameter prefix, start-after, atau delimiter tidak valid.

Metode integrasi

SDK
Anda dapat menggunakan SDK berikut untuk memanggil operasi ListObjectsV2:
Java
Python V2
C
Go V2
Node.js
IOS
Android
Ruby
PHP V2
.NET
antarmuka baris perintah ossutil
Untuk informasi mengenai perintah ossutil untuk operasi ListObjectsV2, lihat list-objects-v2 (get-bucket-v2).