調用GetBucketV2列舉儲存空間 -

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

注意事項

要列舉Bucket中的所有Object資訊，您必須擁有oss:ListObjects許可權。
執行ListObjectsV2（GetBucketV2）請求時不會返回Object中自訂的中繼資料。
如果您開啟了日誌轉存或者即時日誌查詢，則調用該介面產生的訪問日誌中對應的operation欄位為GetBucket。
調用ListObjectsV2（GetBucketV2）介面按照Put類請求次數計費。更多資訊，請參見點擊查看Put類型請求。
一次返回的檔案清單存在數量上限，預設最大展示100條。如需拉取全量檔案，需要藉助NextContinuationToken、continuationToken等參數分段擷取。

請求文法

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

請求參數

名稱	類型	是否必選	樣本值	描述
list-type	數字	是	2	取值只能為2。
delimiter	字串	否	/	對Object名字進行分組的字元。所有Object名字包含指定的首碼，第一次出現delimiter字元之間的Object作為一組元素（即CommonPrefixes）。預設值：無
start-after	字串	否	b	設定從start-after之後按字母排序開始返回Object。 start-after用來實現分頁顯示效果，參數的長度必須小於1024位元組。做條件查詢時，即使start-after在列表中不存在，也會從符合start-after字母排序的下一個開始列印。預設值：無
continuation-token	字串	否	test1.txt	指定List操作需要從此token開始。您可從ListObjectsV2（GetBucketV2）結果中的NextContinuationToken擷取此token。
max-keys	字串	否	100	指定返回Object的最大數。取值：大於0小於等於1000 預設值：100 說明如果因為max-keys的設定無法一次完成列舉，返回結果會附加`NextContinuationToken`作為下一次列舉的`continuation-token`。返回的Object數量不保證達到設定的max-keys。出現這種情況時，需要從返回結果中擷取`NextContinuationToken`作為下一次列舉的`continuation-token`。
prefix	字串	否	a	限定返迴文件的Key必須以prefix作為首碼。如果把prefix設為某個檔案夾名，則列舉以此prefix開頭的檔案，即該檔案夾下遞迴的所有檔案和子檔案夾。在設定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使用UTF-8字元。如果delimiter、start-after、prefix、NextContinuationToken以及Key中包含XML 1.0標準不支援的控制字元，您可以通過指定encoding-type對返回結果中的delimiter、start-after、prefix、NextContinuationToken以及Key進行編碼。
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
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: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

返回樣本

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參數的請求樣本

GET /?list-type=2&prefix=a HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

返回樣本

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和delimiter參數的請求樣本

GET /?list-type=2&prefix=a/&delimiter=/ HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

返回樣本

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和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: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

返回樣本

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>

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

假設examplebucket中包含檔案exampleobject1.txt、exampleobject2.txt和exampleobject3.txt，其儲存類型均為冷Archive Storage類型（ColdArchive）。這三個檔案所處的狀態說明如下：

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

請求樣本

GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

返回樣本

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>

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