418
GetBucket__關於Bucket的操作_API 參考_對象存儲 OSS-阿裏雲
Get Bucket操作可用來list Bucket中所有Object的信息。
請求語法
GET / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
請求參數(Request Parameters)
GetBucket（ListObject）時，可以通過prefix，marker，delimiter和max-keys對list做限定，返回部分結果。另外，可以通過encoding-type對返回結果中的Delimiter、Marker、Prefix、NextMarker和Key這些元素進行編碼。
| 名稱 | 描述 |
|---|---|
| delimiter | 是一個用於對Object名字進行分組的字符。所有名字包含指定的前綴且第一次出現delimiter字符之間的object作為一組元素——CommonPrefixes。 數據類型：字符串 默認值：無 |
| marker | 設定結果從marker之後按字母排序的第一個開始返回。 數據類型：字符串 默認值：無 |
| max-keys | 限定此次返回object的最大數，如果不設定，默認為100，max-keys取值不能大於1000。 數據類型：字符串 默認值：100 |
| prefix | 限定返回的object key必須以prefix作為前綴。注意使用prefix查詢時，返回的key中仍會包含prefix。 數據類型：字符串 默認值：無 |
| encoding-type | 指定對返回的內容進行編碼，指定編碼的類型。Delimiter、Marker、Prefix、NextMarker和Key使用UTF-8字符，但xml 1.0標準不支持解析一些控製字符，比如ascii值從0到10的字符。對於包含xml 1.0標準不支持的控製字符，可以通過指定encoding-type對返回的Delimiter、Marker、Prefix、NextMarker和Key進行編碼。 數據類型：字符串 默認值：無，可選值：url |
響應元素(Response Elements)
| 名稱 | 描述 |
|---|---|
| Contents | 保存每個返回Object meta的容器。 類型：容器 父節點：ListBucketResult |
| CommonPrefixes | 如果請求中指定了delimiter參數，則在OSS返回的響應中包含CommonPrefixes元素。該元素標明那些以delimiter結尾，並有共同前綴的object名稱的集合。 類型：字符串 父節點：ListBucketResult |
| Delimiter | 是一個用於對Object名字進行分組的字符。所有名字包含指定的前綴且第一次出現delimiter字符之間的object作為一組元素——CommonPrefixes。 類型：字符串 父節點：ListBucketResult |
| EncodingType | 指明返回結果中編碼使用的類型。如果請求的參數中指定了encoding-type，那會對返回結果中的Delimiter、Marker、Prefix、NextMarker和Key這些元素進行編碼。 類型：字符串 父節點：ListBucketResult |
| DisplayName | Object 擁有者的名字。 類型：字符串 父節點：ListBucketResult.Contents.Owner |
| ETag | ETag (entity tag) 在每個Object生成的時候被創建，用於標示一個Object的內容。對於Put Object請求創建的Object，ETag值是其內容的MD5值；對於其他方式創建的Object，ETag值是其內容的UUID。ETag值可以用於檢查Object內容是否發生變化。不建議用戶使用ETag來作為Object內容的MD5校驗數據完整性。 類型：字符串 父節點：ListBucketResult.Contents |
| ID | Bucket擁有者的用戶ID。 類型：字符串 父節點：ListBucketResult.Contents.Owner |
| IsTruncated | 指明是否所有的結果都已經返回； “true”表示本次沒有返回全部結果；“false”表示本次已經返回了全部結果。 類型：枚舉字符串 有效值：true、false 父節點：ListBucketResult |
| Key | Object的Key. 類型：字符串 父節點：ListBucketResult.Contents |
| LastModified | Object最後被修改的時間。 類型：時間 父節點：ListBucketResult.Contents |
| ListBucketResult | 保存Get Bucket請求結果的容器. 類型：容器 子節點：Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker, Contents 父節點：None |
| Marker | 標明這次Get Bucket（List Object）的起點。 類型：字符串 父節點：ListBucketResult |
| MaxKeys | 響應請求內返回結果的最大數目。 類型：字符串 父節點：ListBucketResult |
| Name | Bucket名字 類型：字符串 父節點：ListBucketResult |
| Owner | 保存Bucket擁有者信息的容器。 類型：容器 子節點：DisplayName, ID 父節點：ListBucketResult |
| Prefix | 本次查詢結果的開始前綴。 類型：字符串 父節點：ListBucketResult |
| Size | Object的字節數。 類型：字符串 父節點：ListBucketResult.Contents |
| StorageClass | Object的存儲類型，目前隻能是“Standard” 類型：字符串 父節點：ListBucketResult.Contents |
細節分析
- Object中用戶自定義的meta，在GetBucket請求時不會返回。
- 如果訪問的Bucket不存在，包括試圖訪問因為命名不規範無法創建的Bucket，返回404 Not Found錯誤，錯誤碼：NoSuchBucket。
- 如果沒有訪問該Bucket的權限，返回403 Forbidden錯誤，錯誤碼：AccessDenied。
- 如果因為max-keys的設定無法一次完成listing，返回結果會附加一個
<NextMarker>，提示繼續listing可以以此為marker。NextMarker中的值仍在list結果之中。 - 在做條件查詢時，即使marker實際在列表中不存在，返回也從符合marker字母排序的下一個開始打印。如果max-keys小於0或者大於1000，將返回400 Bad Request錯誤。錯誤碼：InvalidArgument。
- 若prefix，marker，delimiter參數不符合長度要求，返回400 Bad Request。錯誤碼：InvalidArgument。
- prefix，marker用來實現分頁顯示效果，參數的長度必須小於1024字節。
- 如果把prefix設為某個文件夾名，就可以羅列以此prefix開頭的文件，即該文件夾下遞歸的所有的文件和子文件夾。如果再把delimiter設置為 / 時，返回值就隻羅列該文件夾下的文件，該文件夾下的子文件名返回在CommonPrefixes部分，子文件夾下遞歸的文件和文件夾不被顯示。如一個bucket存在三個object : fun/test.jpg， fun/movie/001.avi， fun/movie/007.avi。 若設定prefix為”fun/” ，則返回三個object；如果增加設定delimiter為“/”，則返回文件”fun/test.jpg”和前綴”fun/movie/”；即實現了文件夾的邏輯。
舉例場景
在bucket“my_oss”內有4個object，名字分別為：
- oss.jpg
- fun/test.jpg
- fun/movie/001.avi
- fun/movie/007.avi
示例
請求示例：
GET / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=
返回示例：
HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
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=”https://doc.oss-cn-hangzhou.aliyuncs.com”>
<Name>oss-example</Name>
<Prefix></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>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
<Type>Normal</Type>
<Size>344606</Size>
<StorageClass>Standard</StorageClass>
<Owner>
<ID>00220120222</ID>
<DisplayName>user-example</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>fun/movie/007.avi</Key>
<LastModified>2012-02-24T08:43:27.000Z</LastModified>
<ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
<Type>Normal</Type>
<Size>344606</Size>
<StorageClass>Standard</StorageClass>
<Owner>
<ID>00220120222</ID>
<DisplayName>user-example</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>fun/test.jpg</Key>
<LastModified>2012-02-24T08:42:32.000Z</LastModified>
<ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
<Type>Normal</Type>
<Size>344606</Size>
<StorageClass>Standard</StorageClass>
<Owner>
<ID>00220120222</ID>
<DisplayName>user-example</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>oss.jpg</Key>
<LastModified>2012-02-24T06:07:48.000Z</LastModified>
<ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
<Type>Normal</Type>
<Size>344606</Size>
<StorageClass>Standard</StorageClass>
<Owner>
<ID>00220120222</ID>
<DisplayName>user-example</DisplayName>
</Owner>
</Contents>
</ListBucketResult>
請求示例(含Prefix參數)：
GET /?prefix=fun HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=
返回示例：
HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
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=”https://doc.oss-cn-hangzhou.aliyuncs.com”>
<Name>oss-example</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>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
<Type>Normal</Type>
<Size>344606</Size>
<StorageClass>Standard</StorageClass>
<Owner>
<ID>00220120222</ID>
<DisplayName>user_example</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>fun/movie/007.avi</Key>
<LastModified>2012-02-24T08:43:27.000Z</LastModified>
<ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
<Type>Normal</Type>
<Size>344606</Size>
<StorageClass>Standard</StorageClass>
<Owner>
<ID>00220120222</ID>
<DisplayName>user_example</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>fun/test.jpg</Key>
<LastModified>2012-02-24T08:42:32.000Z</LastModified>
<ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
<Type>Normal</Type>
<Size>344606</Size>
<StorageClass>Standard</StorageClass>
<Owner>
<ID>00220120222</ID>
<DisplayName>user_example</DisplayName>
</Owner>
</Contents>
</ListBucketResult>
請求示例(含prefix和delimiter參數)：
GET /?prefix=fun/&delimiter=/ HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY1vY=
返回示例：
HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
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=”https://doc.oss-cn-hangzhou.aliyuncs.com”>
<Name>oss-example</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>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
<Type>Normal</Type>
<Size>344606</Size>
<StorageClass>Standard</StorageClass>
<Owner>
<ID>00220120222</ID>
<DisplayName>user_example</DisplayName>
</Owner>
</Contents>
<CommonPrefixes>
<Prefix>fun/movie/</Prefix>
</CommonPrefixes>
</ListBucketResult>
最後更新：2016-11-23 17:16:08
上一篇：
PutBucketLifecycle__關於Bucket的操作_API 參考_對象存儲 OSS-阿裏雲
下一篇： GetBucketAcl__關於Bucket的操作_API 參考_對象存儲 OSS-阿裏雲
- 提醒_阿裏雲幫助中心-阿裏雲，領先的雲計算服務提供商
- 領域列表_阿裏雲幫助中心-阿裏雲，領先的雲計算服務提供商
- Gartner公布雲計算市場排位：阿裏雲超越穀歌、緊追第二位微軟
- 查看RDS實例IP白名單__實例管理_API 參考_雲數據庫 RDS 版-阿裏雲
- VirtualBorderRouterType__數據類型_API 參考_雲服務器 ECS-阿裏雲
- 賠償說明__產品簡介_消息服務-阿裏雲
- 了解視頻點播流程__開發人員指南_視頻點播-阿裏雲
- 接收刪除消息__隊列消息操作_快速入門_消息服務-阿裏雲
- 【推薦】Windows係統Hang(停止響應)的處理__藍屏夯機_操作係統類問題_Windows操作運維問題_雲服務器 ECS-阿裏雲
- 阿裏雲數據集成__數據傳輸軟件_開發人員指南_E-MapReduce-阿裏雲
相關內容
- 常見錯誤說明__附錄_大數據計算服務-阿裏雲
- 發送短信接口__API使用手冊_短信服務-阿裏雲
- 接口文檔__Android_安全組件教程_移動安全-阿裏雲
- 運營商錯誤碼（聯通）__常見問題_短信服務-阿裏雲
- 設置短信模板__使用手冊_短信服務-阿裏雲
- OSS 權限問題及排查__常見錯誤及排除_最佳實踐_對象存儲 OSS-阿裏雲
- 消息通知__操作指南_批量計算-阿裏雲
- 設備端快速接入(MQTT)__快速開始_阿裏雲物聯網套件-阿裏雲
- 查詢API調用流量數據__API管理相關接口_API_API 網關-阿裏雲
- 使用STS訪問__JavaScript-SDK_SDK 參考_對象存儲 OSS-阿裏雲