GetBucket介面可用來列出 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這些元素進行編碼。

表 1. 請求參數
名稱 類型 是否必需 描述
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)

表 2. 響應元素
名稱 類型 描述
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=”http://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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</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=”http://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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</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=”http://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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</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>