Object Storage ServiceListObjectsV2（GetBucketV2）介面 - Object Storage Service

ListObjectsV2（GetBucketV2）介面用於列舉儲存空間（Bucket）中的對象檔案（Object）的資訊。

請求文法

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

使用說明

執行ListObjectsV2（GetBucketV2）請求時不會返回Object中自訂的中繼資料。單次請求返回的檔案清單預設最大100條，如需擷取全量檔案清單，需要藉助NextContinuationToken、continuationToken等參數實現分段擷取。

調用該介面列舉Bucket中的所有Object資訊，必須擁有oss:ListObjects許可權。
開啟日誌轉存或即時日誌查詢後，調用該介面產生的訪問日誌中對應的operation欄位為GetBucket。
Bucket開啟版本控制後，覆寫或誤刪除操作會產生大量刪除標記和歷史版本，建議配置生命週期規則定期清理刪除標記和不再需要的歷史版本，避免影響List操作的效能。
調用ListObjectsV2（GetBucketV2）介面按照Put類請求次數計費。更多資訊，請參見Put類API請求。

請求參數

名稱	類型	是否必選	樣本值	描述
list-type	數字	是	2	取值固定為2。
delimiter	字串	否	/	對Object名字進行分組的字元。所有Object名字包含指定首碼且第一次出現delimiter字元之間的Object作為一組元素（即CommonPrefixes）。預設值：無
start-after	字串	否	b	指定從start-after之後按字母排序開始返回Object，用於實現分頁顯示效果。參數長度必須小於1024位元組。執行條件查詢時，即使start-after在列表中不存在，也會從符合start-after字母排序的下一個Object開始返回結果。預設值：無
continuation-token	字串	否	test1.txt	指定List操作需要從此token開始繼續列舉。此token可從上一次ListObjectsV2（GetBucketV2）結果中的NextContinuationToken擷取。
max-keys	數字	否	100	指定返回Object的最大數量。取值：大於0小於等於1000 預設值：100 當因為max-keys設定無法一次完成列舉時，返回結果會包含`NextContinuationToken`作為下次列舉的`continuation-token`參數值。返回的Object數量不保證達到設定的max-keys值。出現這種情況時，需要從返回結果中擷取`NextContinuationToken`作為下次列舉的`continuation-token`參數值。
prefix	字串	否	a	限定返迴文件的Key必須以prefix作為首碼，將prefix設為某個檔案夾名時，可列舉該檔案夾下遞迴的所有檔案和子檔案夾。配合delimiter參數使用時，prefix設定檔案夾路徑，delimiter設定為正斜線（/），可實現只列舉該檔案夾下的直接檔案，子檔案夾名返回在CommonPrefixes中，不展開子檔案夾內容。例如，一個Bucket包含三個Object：fun/test.jpg、fun/movie/001.avi和fun/movie/007.avi。設定prefix為fun/時，返回全部三個Object；在prefix設為fun/基礎上將delimiter設為正斜線（/）時，返回fun/test.jpg檔案和fun/movie/檔案夾。參數長度必須小於1024位元組。設定prefix參數時，不能以正斜線（/）開頭。prefix參數為空白時，預設列舉Bucket內的所有Object。使用prefix查詢時，返回的Key中仍會包含prefix首碼內容。預設值：無
encoding-type	字串	否	url	對返回的內容進行編碼並指定編碼類別型。預設值：無可選值：url 當delimiter、start-after、prefix、NextContinuationToken以及Key中包含XML 1.0標準不支援的控制字元時，通過指定encoding-type參數可對返回結果中的這些欄位進行URL編碼。 delimiter、start-after、prefix、NextContinuationToken以及Key使用UTF-8字元編碼。
fetch-owner	布爾值	否	false	指定是否在返回結果中包含owner資訊。可選值：true、false true：返回結果中包含owner資訊。 false：返回結果中不包含owner資訊。預設值：false

響應參數

名稱	類型	樣本值	描述
Contents	容器	不涉及	儲存每個返回Object中繼資料的容器。父節點：ListBucketResult
CommonPrefixes	容器	不涉及	當請求中指定了Delimiter參數時，返迴響應中包含CommonPrefixes元素。該元素表示以Delimiter結尾且具有共同首碼的Object名稱集合。父節點：ListBucketResult 子節點：Prefix
Delimiter	字串	/	對Object名字進行分組的字元。所有名字包含指定首碼且第一次出現Delimiter字元之間的Object作為一組元素CommonPrefixes。父節點：ListBucketResult
EncodingType	字串	不涉及	指明返回結果中編碼使用的類型。當請求參數中指定了Encoding-type時，會對返回結果中的Delimiter、StartAfter、Prefix、NextContinuationToken和Key這些元素進行編碼。父節點：ListBucketResult
DisplayName	字串	user_example	Object擁有者的顯示名稱。父節點：ListBucketResult.Contents.Owner
ETag	字串	5B3C1A2E053D763E1B002CC607C5A0FE1****	ETag在每個Object產生時建立，用於標識Object內容的唯一性。父節點：ListBucketResult.Contents 通過PutObject請求建立的Object，ETag值是其內容的MD5值。通過其他方式建立的Object，ETag值是基於特定計算規則產生的唯一值，但不是其內容的MD5值。 ETag值可用於檢查Object內容是否發生變化，但不建議將ETag值作為Object內容MD5校正資料完整性的依據。
ID	字串	0022012****	Bucket擁有者的使用者ID。父節點：ListBucketResult.Contents.Owner
IsTruncated	枚舉字串	false	請求中返回的結果是否被截斷。傳回值：true、false true表示未返回全部結果。 false表示已返回全部結果。父節點：ListBucketResult
Key	字串	fun/test.jpg	Object的Key名稱。父節點：ListBucketResult.Contents
LastModified	時間	2012-02-24T08:42:32.000Z	Object最後被修改的時間。父節點：ListBucketResult.Contents
ListBucketResult	容器	不涉及	儲存GetBucket請求結果的容器。子節點：Name、Prefix、StartAfter、MaxKeys、 Delimiter、IsTruncated、NextContinuationToken、Contents 父節點：None
StartAfter	字串	test1.txt	當請求中指定了StartAfter參數時，返回的響應中包含StartAfter元素。
MaxKeys	數字	100	響應請求內返回結果的最大數目。父節點：ListBucketResult
Name	字串	examplebucket	Bucket名稱。父節點：ListBucketResult
Owner	容器	不涉及	儲存Bucket擁有者資訊的容器。子節點：DisplayName、ID 父節點：ListBucketResult.Contents
Prefix	字串	fun/	本次查詢結果的首碼。父節點：ListBucketResult
Type	字串	Normal	檔案類型。取值：Normal，Multipart，Appendable，Symlink。父節點：ListBucketResult.Contents
Size	數字	344606	返回Object大小，單位為位元組。父節點：ListBucketResult.Contents
StorageClass	字串	Standard	Object的儲存類型。父節點：ListBucketResult.Contents
SealedTime	時間	2020-05-21T12:07:15.000Z	檔案執行Seal操作的時間。當訪問處於Sealed狀態的可追加寫檔案（Appendable Object）時，返回該欄位。父節點：ListBucketResult.Contents
ContinuationToken	字串	test1.txt	當請求中指定了ContinuationToken參數時，返回的響應中包含ContinuationToken元素。父節點：ListBucketResult
KeyCount	數字	6	此次請求返回的Key個數。當指定了Delimiter參數時，KeyCount為Key和CommonPrefixes的元素總數。父節點：ListBucketResult
NextContinuationToken	字串	CgJiYw--	表明此次ListObjectsV2（GetBucketV2）請求包含後續結果，需要將NextContinuationToken作為下次請求的ContinuationToken參數值來繼續擷取剩餘結果。父節點：ListBucketResult
RestoreInfo	字串	ongoing-request="true"	Object的解凍狀態。如果沒有提交RestoreObject請求或者RestoreObject請求已到期，則不返回該欄位。如果已經提交RestoreObject請求，但解凍操作未完成，則返回的RestoreInfo值為`ongoing-request="true"`。如果已經提交RestoreObject請求，且解凍操作已完成，則返回的RestoreInfo值為`ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"`。其中，`expiry-date`欄位表示解凍完成後Object進入可讀狀態的到期時間。父節點：ListBucketResult.Contents

使用樣本

簡單請求

請求樣本

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

返回樣本

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>

帶prefix參數的請求

請求樣本

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

返回樣本

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>

帶prefix和delimiter參數的請求

請求樣本

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

返回樣本

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>

帶start-after、max-keys和fetch-owner參數的請求

請求樣本

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

返回樣本

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>

請求的Bucket包含歸檔或冷歸檔類型檔案

請求樣本

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

返回樣本

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>

檔案所處的狀態說明如下：

exampleobject1.txt未提交RestoreObject請求或者RestoreObject請求已到期。
exampleobject2.txt已提交RestoreObject請求，但解凍操作未完成。
exampleobject3.txt已提交RestoreObject請求，且解凍操作已完成。

錯誤碼

錯誤碼	HTTP狀態代碼	描述
NoSuchBucket	404	請求的目標Bucket不存在。請檢查請求的Bucket名稱是否符合命名規範。
AccessDenied	403	沒有訪問該Bucket的許可權。只有Bucket擁有者以及被授予`oss:ListObjects`許可權的使用者可以訪問該Bucket。
InvalidArgument	400	max-keys參數值小於0或者大於1000。 prefix、start-after、delimiter參數的長度不符合要求。

整合方式

SDK
ListObjectsV2介面所對應的各語言SDK如下：
Java
Python V2
C
Go V2
Node.js
IOS
Android
Ruby
PHP V2
.NET
命令列工具ossutil
ListObjectsV2介面所對應的ossutil命令，請參見list-objects-v2（get-bucket-v2）。