當您需要列舉儲存空間(Bucket)中所有檔案(Object)的資訊,例如檔案名稱、檔案大小、檔案最後修改時間等,可以調用GetBucket (ListObjects)介面進行擷取。
注意事項
GetBucket (ListObjects)介面已修訂為GetBucketV2 (ListObjectsV2)。建議您在開發應用程式時使用較新的版本GetBucketV2 (ListObjectsV2)。為保證向後相容性,OSS繼續支援GetBucket (ListObjects)。有關GetBucketV2 (ListObjectsV2)的更多資訊,請參見ListObjectsV2(GetBucketV2)。
執行GetBucket (ListObjects)請求時不會返回Object中自訂的中繼資料。
GetBucket (ListObjects)是Bucket層級的操作,按照Bucket儲存類型收取Put類請求費用。調用一次該介面只收取一次Put類請求費用。更多資訊,請參見Put類請求。
請求文法
GET / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
要求標頭
此介面僅涉及公用要求標頭,例如Authorization
、Host
等。更多資訊,請參見公用要求標頭(Common Request Headers)。
請求參數
名稱 | 類型 | 是否必選 | 樣本值 | 描述 |
delimiter | 字串 | 否 | / | 對Object名字進行分組的字元。所有Object名字包含指定的首碼,第一次出現delimiter字元之間的Object作為一組元素(即CommonPrefixes)。 預設值:無 |
marker | 字串 | 否 | test1.txt | 設定從marker之後按字母排序開始返回Object。 marker用來實現分頁顯示效果,參數的長度必須小於1024位元組。 做條件查詢時,即使marker在列表中不存在,也會從符合marker字母排序的下一個開始列印。 預設值:無 |
max-keys | 字串 | 否 | 200 | 指定返回Object的最大數。 如果因為max-keys的設定無法一次完成列舉,返回結果會附加NextMarker元素作為下一次列舉的marker。 取值:大於0小於等於1000 預設值:100 |
prefix | 字串 | 否 | fun | 限定返迴文件的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/。 預設值:無 |
encoding-type | 字串 | 否 | URL | 對返回的內容進行編碼並指定編碼的類型。 預設值:無 可選值:URL 重要 delimiter、marker、prefix、NextMarker以及Key使用UTF-8字元。如果delimiter、marker、prefix、NextMarker以及Key中包含XML 1.0標準不支援的控制字元,您可以通過指定encoding-type對返回結果中的Delimiter、Marker、Prefix、NextMarker以及Key進行編碼。 |
響應元素
名稱 | 類型 | 樣本值 | 描述 |
ListBucketResult | 容器 | 不涉及 | 儲存GetBucket請求結果的容器。 子節點:Name、Prefix、 Marker、MaxKeys、 Delimiter、IsTruncated、Nextmarker、Contents 父節點:None |
Name | 字串 | oss-example | Bucket名稱。 父節點:ListBucketResult |
Prefix | 字串 | fun/ | 本次查詢結果的首碼。 父節點:ListBucketResult或者CommonPrefixes |
Marker | 字串 | test1.txt | 標識此次GetBucket(ListObjects)的起點。 父節點:ListBucketResult |
MaxKeys | 字串 | 100 | 響應請求內返回結果的最大數目。 父節點:ListBucketResult |
Delimiter | 字串 | / | 對Object名字進行分組的字元。所有名字包含指定的首碼且第一次出現Delimiter字元之間的Object作為一組元素CommonPrefixes。 父節點:ListBucketResult |
EncodingType | 字串 | url | 指明了返回結果中編碼使用的類型。如果請求的參數中指定了encoding-type,則會對返回結果中的Delimiter、Marker、Prefix、NextMarker和Key這些元素進行編碼。 父節點:ListBucketResult |
IsTruncated | 枚舉字串 | false | 請求中返回的結果是否被截斷。 傳回值:true、false
父節點:ListBucketResult |
NextMarker | 字串 | test100.txt | 下一次列舉檔案的起點。 父節點:ListBucketResult |
Contents | 容器 | 不涉及 | 儲存每個返回Object中繼資料的容器。 父節點:ListBucketResult |
Key | 字串 | fun/test.jpg | Object的Key。 父節點:ListBucketResult.Contents |
TransitionTime | 時間 | 2024-04-23T07:21:42.000Z | Object通過生命週期規則轉儲為冷歸檔或者深度冷Archive Storage類型的時間。 說明
父節點:ListBucketResult.Contents |
LastModified | 時間 | 2012-02-24T08:42:32.000Z | Object最後被修改的時間。 說明
父節點:ListBucketResult.Contents |
ETag | 字串 | 5B3C1A2E053D763E1B002CC607C5A0FE1**** | ETag(Entity Tag)在每個Object產生時建立,用於標識一個Object的內容。
父節點:ListBucketResult.Contents |
Type | 字串 | Normal | Object類型,分為以下三種:
|
Size | 字串 | 344606 | 返回Object大小,單位為位元組。 父節點:ListBucketResult.Contents |
StorageClass | 字串 | Standard | Object的儲存類型。 父節點:ListBucketResult.Contents |
RestoreInfo | 字串 | ongoing-request="true” | Object的解凍狀態。
|
Owner | 容器 | 不涉及 | 儲存Bucket擁有者資訊的容器。 子節點:DisplayName、ID 父節點:Contents |
ID | 字串 | 0022012**** | Bucket擁有者的使用者ID。 父節點:ListBucketResult.Contents.Owner |
DisplayName | 字串 | user_example | Object擁有者名稱。 父節點:ListBucketResult.Contents.Owner |
CommonPrefixes | 容器 | 不涉及 | 如果請求中指定了Delimiter參數,則會在返回的響應中包含CommonPrefixes元素。該元素表明以Delimiter結尾,並有共同首碼的Object名稱的集合。 父節點:ListBucketResult |
此介面涉及的其他公用回應標頭,例如x-oss-request-id
、Content-Type
等的更多資訊,請參見公用回應標頭(Common Response Headers)。
樣本
簡單請求樣本
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: 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>
帶prefix參數的請求樣本
GET /?prefix=fun 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>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>
帶prefix和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: 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>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>
指定marker分頁列舉的請求樣本
此樣本中指定了max-keys=2,即最多返回2條列舉資訊。
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: OSS qn6q**************:77Dv****************
返回樣本
結果中的NextMarker可以作為下次列舉請求的Marker。
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>
請求的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>
SDK
此介面所對應的各語言SDK如下:
錯誤碼
錯誤碼 | HTTP狀態代碼 | 描述 |
NoSuchBucket | 404 | 請求的目標Bucket不存在。請檢查請求的Bucket名稱是否符合規範。 |
AccessDenied | 403 | 沒有訪問該Bucket的許可權。只有Bucket擁有者以及被授予 |
InvalidArgument | 400 |
|