全部產品
Search

搜尋本產品

    ：GetBucket (ListObjects)

    文件中心

    ：GetBucket (ListObjects)

    更新時間：Jun 19, 2024

    當您需要列舉儲存空間（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參數的長度必須小於1024位元組。

    • 使用prefix查詢時，返回的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

    • true表示本次沒有返回全部結果。

    • false表示本次已經返回了全部結果。

    父節點：ListBucketResult

    NextMarker

    字串

    test100.txt

    下一次列舉檔案的起點。

    父節點：ListBucketResult

    Contents

    容器

    不涉及

    儲存每個返回Object中繼資料的容器。

    父節點：ListBucketResult

    Key

    字串

    fun/test.jpg

    Object的Key。

    父節點：ListBucketResult.Contents

    LastModified

    時間

    2012-02-24T08:42:32.000Z

    Object最後被修改的時間。

    父節點：ListBucketResult.Contents

    ETag

    字串

    5B3C1A2E053D763E1B002CC607C5A0FE1****

    ETag（Entity Tag）在每個Object產生時建立，用於標識一個Object的內容。

    • 對於PutObject請求建立的Object，ETag值是其內容的MD5值。

    • 對於其他方式建立的Object，ETag值是基於一定計算規則產生的唯一值，但不是其內容的MD5值。

    • ETag值可以用於檢查Object內容是否發生變化。不建議使用ETag值作為Object內容的MD5校正資料完整性的依據。

    父節點：ListBucketResult.Contents

    Type

    字串

    Normal

    Object類型，分為以下三種：

    • Normal：通過簡單上傳產生的Object類型為Normal。

    • Multipart：通過分區上傳產生的Object類型為Multipart。

    • Appendable：通過追加上傳產生的Object類型為Appendable。

    Size

    字串

    344606

    返回Object大小，單位為位元組。

    父節點：ListBucketResult.Contents

    StorageClass

    字串

    Standard

    Object的儲存類型。

    父節點：ListBucketResult.Contents

    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進入可讀狀態的到期時間。

    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>
      <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擁有者以及被授予oss:ListObjects許可權的使用者可以訪問該Bucket。

    InvalidArgument

    400

    • max-keys小於0或者大於1000。

    • prefix、marker、delimiter參數的長度不符合要求。