ListObjectsV2 GetBucketV2 - list bucket objects OSS API - Object Storage Service

Notlar

Bir paketteki tüm nesneleri listelemek için oss:ListObjects iznine sahip olmanız gerekir.
ListObjectsV2 (GetBucketV2) işlemi özel nesne meta verilerini döndürmez.
Günlük depolama veya gerçek zamanlı günlük sorgusu etkinleştirilmişse bu işlem GetBucket olarak günlüğe kaydedilir.
ListObjectsV2 (GetBucketV2) işlemi PUT API isteği olarak faturalandırılır.
Tek bir yanıt varsayılan olarak en fazla 100 nesne döndürür. Tüm sonuçları sayfalamak için NextContinuationToken ve continuation-token parametrelerini kullanın.
Sürüm oluşturma etkinleştirilmişse nesnelerin üzerine yazılması veya silinmesi silme işaretçilerinin ve önceki sürümlerin birikmesine neden olabilir. Liste performansını korumak için silme işaretçilerini ve gereksiz önceki sürümleri periyodik olarak temizlemek üzere yaşam döngüsü kurallarını yapılandırın.

İstek sözdizimi

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

İstek parametreleri

Ad	Tür	Gerekli	Örnek	Açıklama
list-type	Number	Evet	2	İşlem sürümü. Değer 2 olarak ayarlanır.
delimiter	String	Hayır	/	Nesne anahtarlarını gruplamak için kullanılan karakter. Sınırlayıcının ilk oluşumuna kadar ortak ön eki paylaşan anahtarlar tek bir CommonPrefixes girdisi altında gruplanır. Varsayılan değer: Yok
start-after	String	Hayır	b	Listelemenin başladığı nesne anahtarı. Sonuçlar bu değerden sonra alfabetik olarak gelen ilk anahtardan başlar. Sayfalama için kullanılır. Maksimum uzunluk: 1.024 bayt. Belirtilen start-after değeri mevcut değilse listeleme alfabetik sıradaki sonraki anahtardan başlar. Varsayılan değer: Yok
continuation-token	String	Hayır	test1.txt	Listelemenin başlayacağı belirteç. Bu değeri önceki ListObjectsV2 (GetBucketV2) yanıtındaki NextContinuationToken değerinden alın.
max-keys	String	Hayır	100	Döndürülecek maksimum nesne sayısı. Geçerli değerler: 1 ila 1000 Varsayılan değer: 100 Not Yanıt max-keys nedeniyle kesilmişse döndürülen `NextContinuationToken` değerini sonraki istek için `continuation-token` olarak kullanın. Döndürülen gerçek nesne sayısı max-keys değerinden az olabilir. Bu durumda sonraki istek için yanıtta bulunan `NextContinuationToken` değerini `continuation-token` olarak kullanın.
prefix	String	Hayır	a	Döndürülen nesne anahtarlarının içermesi gereken ön ek. Bir klasör adı olarak ayarlanırsa bu ön eke sahip tüm dosyalar ve alt klasörler özyinelemeli olarak listelenir. Prefix ayarlanır ve delimiter / olarak belirlenirse yalnızca klasördeki dosyalar listelenir. Alt klasör adları özyinelemeli listeleme olmadan CommonPrefixes içinde görünür. Örnek: Bir pakette fun/test.jpg, fun/movie/001.avi ve fun/movie/007.avi bulunur. Prefix değerini fun/ olarak ayarlamak üçünü de döndürür. Prefix değerini fun/ ve delimiter değerini / olarak ayarlamak fun/test.jpg ve fun/movie/ öğelerini döndürür. Not Maksimum uzunluk: 1.024 bayt. Ön ek eğik çizgi (/) ile başlayamaz. Boş bırakılırsa paketteki tüm nesneler listelenir. Döndürülen anahtarlar ön eki içerir. Varsayılan değer: Yok
encoding-type	String	Hayır	url	Yanıt için kodlama türü. Varsayılan değer: Yok Geçerli değer: url Not Delimiter, start-after, prefix, NextContinuationToken veya Key değerleri XML 1.0 tarafından desteklenmeyen kontrol karakterleri içeriyorsa bunları yanıtta kodlamak için encoding-type parametresini belirtin.
fetch-owner	Boolean	Hayır	false	Yanıta sahip bilgilerinin dahil edilip edilmeyeceği. Geçerli değerler: true, false true: Yanıt sahip bilgilerini içerir. false: Yanıt sahip bilgilerini içermez. Varsayılan değer: false

Yanıt öğeleri

Ad	Tür	Örnek	Açıklama
Contents	Container	Uygulanamaz	Döndürülen her nesnenin meta verileri için kapsayıcı. Üst düğüm: ListBucketResult
CommonPrefixes	Container	Uygulanamaz	Delimiter parametresi belirtilirse yanıt CommonPrefixes öğesini içerir. Bu öğe ortak bir ön eki paylaşan ve sınırlayıcı ile biten nesne adı ön eklerini listeler. Üst düğüm: ListBucketResult Alt düğüm: Prefix
Delimiter	String	/	Nesne anahtarlarını gruplamak için kullanılan karakter. İlk sınırlayıcı oluşumuna kadar ortak ön eki paylaşan anahtarlar tek bir CommonPrefixes girdisi altında gruplanır. Üst düğüm: ListBucketResult
EncodingType	String	Uygulanamaz	Yanıtta kullanılan kodlama türü. İstekte Encoding-type belirtilirse Delimiter, StartAfter, Prefix, NextContinuationToken ve Key kodlanır. Üst düğüm: ListBucketResult
DisplayName	String	user_example	Nesne sahibinin adı. Üst düğüm: ListBucketResult.Contents.Owner
ETag	String	5B3C1A2E053D763E1B002CC607C5A0FE1****	ETag nesne oluşturulduğunda üretilen ve nesne içeriğini tanımlayan bir değerdir. Üst düğüm: ListBucketResult.Contents PutObject isteğiyle oluşturulan nesneler için ETag değeri nesne içeriğinin MD5 karmasıdır. Diğer yöntemlerle oluşturulan nesneler için ETag değeri belirli bir kurala göre hesaplanan benzersiz bir değerdir ancak nesne içeriğinin MD5 karması değildir. ETag nesne içeriğinin değişip değişmediğini kontrol edebilir ancak veri bütünlüğü doğrulaması için uygun değildir. Bunun yerine MD5 karmasını kullanın.
ID	String	0022012****	Paket sahibinin kullanıcı kimliği. Üst düğüm: ListBucketResult.Contents.Owner
IsTruncated	Enumerated string	false	Döndürülen sonuçların kesilip kesilmediğini gösterir. Geçerli değerler: true, false true: Bu sefer tüm sonuçlar döndürülmemiştir. false: Bu sefer tüm sonuçlar döndürülmüştür. Üst düğüm: ListBucketResult
Key	String	fun/test.jpg	Nesnenin anahtarı. Üst düğüm: ListBucketResult.Contents
LastModified	Time	2012-02-24T08:42:32.000Z	Nesnenin son değiştirilme zamanı. Üst düğüm: ListBucketResult.Contents
ListBucketResult	Container	Uygulanamaz	GetBucket isteğinin sonuçları için kapsayıcı. Alt düğümler: Name, Prefix, StartAfter, MaxKeys, Delimiter, IsTruncated, NextContinuationToken, Contents Üst düğüm: Yok
StartAfter	String	test1.txt	İstekte StartAfter parametresini belirtirseniz yanıt StartAfter öğesini içerir.
MaxKeys	String	100	Yanıtta döndürülen maksimum sonuç sayısı. Üst düğüm: ListBucketResult
Name	String	examplebucket	Paketin adı. Üst düğüm: ListBucketResult
Owner	Container	Uygulanamaz	Paket sahibi bilgileri için kapsayıcı. Alt düğümler: DisplayName, ID Üst düğüm: ListBucketResult.Contents
Prefix	String	fun/	Sorgu sonuçlarının ön eki. Üst düğüm: ListBucketResult
Type	String	Normal	Nesne türü. Geçerli değerler: Normal, Multipart, Appendable, Symlink. Üst düğüm: ListBucketResult.Contents
Size	String	344606	Nesnenin bayt cinsinden boyutu. Üst düğüm: ListBucketResult.Contents
StorageClass	String	Standard	Nesnenin depolama sınıfı. Üst düğüm: ListBucketResult.Contents
SealedTime	Time	2020-05-21T12:07:15.000Z	Nesnenin mühürlendiği zaman. Yalnızca mühürlenmiş eklenebilir nesneler için döndürülür. Üst düğüm: ListBucketResult.Contents
ContinuationToken	String	test1.txt	İstekte ContinuationToken parametresini belirtirseniz yanıt ContinuationToken öğesini içerir. Üst düğüm: ListBucketResult
KeyCount	Number	6	Döndürülen anahtar sayısı. Delimiter belirtilirse KeyCount Key ve CommonPrefixes öğelerinin toplamıdır. Üst düğüm: ListBucketResult
NextContinuationToken	String	CgJiYw--	Sonraki sonuç sayfasını almak için kullanılan belirteç. Bu değeri sonraki ListObjectsV2 (GetBucketV2) isteğinde continuation-token olarak kullanın. Üst düğüm: ListBucketResult
RestoreInfo	String	ongoing-request="true"	Nesnenin geri yükleme durumu. RestoreObject isteği gönderilmediyse veya gönderilen RestoreObject isteğinin süresi dolduysa döndürülmez. RestoreObject isteği gönderildiyse ancak geri yükleme işlemi tamamlanmadıysa RestoreInfo değeri `ongoing-request="true"` olur. RestoreObject isteği gönderildiyse ve geri yükleme işlemi tamamlandıysa RestoreInfo değeri `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"` olur. `expiry-date` alanı geri yüklenen nesnenin sona erme zamanını gösterir. Üst düğüm: ListBucketResult.Contents

Örnekler

Basit istek

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

Örnek yanıt

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

Prefix parametreli istek

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

Örnek yanıt

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

Prefix ve delimiter parametreli istek

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

Örnek yanıt

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

Start-after, max-keys ve fetch-owner parametreleriyle istek gönderme

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

Örnek yanıt

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

Arşiv veya Soğuk Arşiv nesneleri içeren paket için istek

examplebucket paketinin exampleobject1.txt, exampleobject2.txt ve exampleobject3.txt nesnelerini içerdiğini varsayalım. Üç nesne de Soğuk Arşiv depolama sınıfındadır. Nesnelerin durumları aşağıdaki gibidir:

exampleobject1.txt için RestoreObject isteği gönderilmemiştir veya gönderilen RestoreObject isteğinin süresi dolmuştur.
exampleobject2.txt için RestoreObject isteği gönderilmiştir ve geri yükleme işlemi devam etmektedir.
exampleobject3.txt için RestoreObject isteği gönderilmiştir ve geri yükleme işlemi tamamlanmıştır.

Örnek istek

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

Örnek yanıt

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

Bu işlem için SDK'lar:

ossutil komut satırı aracı

İlgili ossutil komutu list-objects-v2 (get-bucket-v2) komutudur.

Hata kodu	HTTP durum kodu	Açıklama
NoSuchBucket	404	Belirtilen paket mevcut değil. Paket adının geçerli olup olmadığını kontrol edin.
AccessDenied	403	Gerekli izinlere sahip değilsiniz. Bu işlemi yalnızca paket sahibi veya `oss:ListObjects` izni verilmiş kullanıcılar yapabilir.
InvalidArgument	400	max-keys değeri 0'dan küçük veya 1.000'den büyüktür. prefix, marker veya delimiter parametresinin uzunluğu geçersizdir.