全部產品
Search
文件中心

Object Storage Service:ListBuckets(GetService)

更新時間:Jun 19, 2024

調用ListBuckets(GetService)介面列舉要求者擁有的所有儲存空間(Bucket)。您還可以通過設定prefix、marker或者max-keys參數列舉滿足指定條件的儲存空間。

注意事項

如果您需要列舉OSS Bucket,您必須擁有oss:ListBuckets許可權。

具體操作,請參見為RAM使用者授權自訂的權限原則

請求文法

GET / HTTP/1.1
Host: oss.example.com
Date: GMT Date
Authorization: SignatureValue

要求標頭

名稱

類型

是否必選

樣本值

描述

x-oss-resource-group-id

字串

rg-aek27tc********

指定資源群組ID。

  • 如果在請求中攜帶該要求標頭並指定資源群組ID,則OSS會返回屬於該資源群組的所有Bucket。

    當指定的資源群組ID為rg-default-id時,OSS會返回屬於預設資源群組的所有Bucket。

  • 如果在請求中攜帶了該要求標頭但未指定資源群組ID,則OSS會返回屬於預設資源群組的所有Bucket。

  • 如果在請求中未攜帶該要求標頭,則OSS會返回要求者擁有的所有Bucket。

您可以通過資源管理的控制台或ListResourceGroups介面擷取資源群組ID。具體操作,請分別參見查看資源群組基本資料ListResourceGroups

此介面涉及的其他公用要求標頭,例如Host、Date等的更多資訊,請參見公用要求標頭(Common Request Headers)

請求參數

名稱

類型

是否必選

樣本值

描述

prefix

字串

my

限定返回的Bucket名稱必須以prefix作為首碼。如果不設定,則不過濾首碼資訊。

預設值:無

marker

字串

mybucket10

設定結果從marker之後按字母排序的第一個開始返回。如果不設定,則從頭開始返回資料。

預設值:無

max-keys

Integer

10

限定此次返回Bucket的最大個數。

取值範圍:1~1000

預設值:100

回應標頭

此介面僅涉及公用回應標頭。更多資訊,請參見公用回應標頭(Common Response Headers)

響應元素

說明

調用ListBuckets(GetService)介面時,如果所有Bucket已返回,則返回的XML中不包含Prefix、Marker、MaxKeys、IsTruncated和NextMarker響應元素。

名稱

類型

樣本值

描述

ListAllMyBucketsResult

容器

不涉及

儲存ListBuckets(GetService)請求結果的容器。

子節點:Owner、Buckets

父節點:None

Prefix

字串

my

本次查詢結果的首碼。

父節點:ListAllMyBucketsResult

Marker

字串

mybucket

表示本次ListBuckets(GetService)的起點。

父節點:ListAllMyBucketsResult

MaxKeys

字串

10

響應請求內返回結果的最大個數。

父節點:ListAllMyBucketsResult

IsTruncated

枚舉字串

true

是否所有的結果都已經返回。 取值範圍如下:

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

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

父節點:ListAllMyBucketsResult

NextMarker

字串

mybucket10

用於繼續查詢時給marker賦值。表示下一次ListBuckets(GetService)可以以此為marker,將未返回的結果返回。

父節點:ListAllMyBucketsResult

Owner

容器

不涉及

用於存放Bucket擁有者資訊的容器。

父節點:ListAllMyBucketsResult

ID

字串

ut_test_put_bucket

Bucket擁有者的使用者ID。

父節點:ListAllMyBucketsResult.Owner

DisplayName

字串

ut_test_put_bucket

Bucket擁有者的名稱 (目前和ID一致)。

父節點:ListAllMyBucketsResult.Owner

Buckets

容器

不涉及

儲存多個Bucket資訊的容器。

子節點:Bucket

父節點:ListAllMyBucketsResult

Bucket

容器

不涉及

儲存Bucket資訊的容器。

子節點:Name, CreationDate, Location

父節點:ListAllMyBucketsResult.Buckets

Name

字串

mybucket01

Bucket名稱。

父節點:ListAllMyBucketsResult.Buckets.Bucket

CreationDate

時間

2014-05-15T11:18:32.000Z

Bucket建立時間。格式為yyyy-mm-ddThh:mm:ss.timezone

父節點:ListAllMyBucketsResult.Buckets.Bucket

Location

字串

oss-cn-hangzhou

OSS專用Region ID。

父節點:ListAllMyBucketsResult.Buckets.Bucket

ExtranetEndpoint

字串

oss-cn-hangzhou.aliyuncs.com

外網訪問網域名稱。

父節點:ListAllMyBucketsResult.Buckets.Bucket

IntranetEndpoint

字串

oss-cn-hangzhou-internal.aliyuncs.com

內網訪問網域名稱。

父節點:ListAllMyBucketsResult.Buckets.Bucket

Region

字串

cn-hangzhou

阿里雲通用Region ID。

父節點:ListAllMyBucketsResult.Buckets.Bucket

StorageClass

字串

Standard

Bucket儲存類型,支援StandardIAArchiveColdArchiveDeepColdArchive多種儲存類型。

父節點:ListAllMyBucketsResult.Buckets.Bucket

ResourceGroupId

字串

rg-aek27tc********

Bucket所屬資源群組ID。如果Bucket屬於預設資源群組,則傳回值為rg-default-id。

父節點:ListAllMyBucketsResult.Buckets.Bucket

樣本

  • 擷取要求者擁有的所有Bucket

    請求樣本

    GET / HTTP/1.1
    Date: Thu, 15 May 2014 11:18:32 GMT
    Host: oss-cn-hangzhou.aliyuncs.com
    Authorization: OSS qn6q**************:77Dv****************

    返回樣本

    HTTP/1.1 200 OK
    Date: Thu, 15 May 2014 11:18:32 GMT
    Content-Type: application/xml
    Content-Length: 556
    Connection: keep-alive
    Server: AliyunOSS
    x-oss-request-id: 5374A2880232A65C2300****
    <?xml version="1.0" encoding="UTF-8"?>
    <ListAllMyBucketsResult>
      <Owner>
        <ID>512**</ID>
        <DisplayName>51264</DisplayName>
      </Owner>
      <Buckets>
        <Bucket>
          <CreationDate>2014-02-17T18:12:43.000Z</CreationDate>
          <ExtranetEndpoint>oss-cn-shanghai.aliyuncs.com</ExtranetEndpoint>
          <IntranetEndpoint>oss-cn-shanghai-internal.aliyuncs.com</IntranetEndpoint>
          <Location>oss-cn-shanghai</Location>
          <Name>app-base-oss</Name>
          <Region>cn-shanghai</Region>
          <StorageClass>Standard</StorageClass>
        </Bucket>
        <Bucket>
          <CreationDate>2014-02-25T11:21:04.000Z</CreationDate>
          <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
          <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
          <Location>oss-cn-hangzhou</Location>
          <Name>mybucket</Name>
          <Region>cn-hangzhou</Region>
          <StorageClass>IA</StorageClass>
        </Bucket>
      </Buckets>
    </ListAllMyBucketsResult>
  • 根據指定首碼、最大返回個數等擷取Bucket

    請求樣本

    GET /?prefix=my&max-keys=10 HTTP/1.1
    Date: Thu, 15 May 2014 11:18:32 GMT
    Host: oss-cn-hangzhou.aliyuncs.com
    Authorization: OSS qn6q**************:77Dv****************

    返回樣本

    HTTP/1.1 200 OK
    Date: Thu, 15 May 2014 11:18:32 GMT
    Content-Type: application/xml
    Content-Length: 545
    Connection: keep-alive
    Server: AliyunOSS
    x-oss-request-id: 5374A2880232A65C2300****
    <?xml version="1.0" encoding="UTF-8"?>
    <ListAllMyBucketsResult>
      <Prefix>my</Prefix>
      <Marker>mybucket</Marker>
      <MaxKeys>10</MaxKeys>
      <IsTruncated>true</IsTruncated>
      <NextMarker>mybucket10</NextMarker>
      <Owner>
        <ID>ut_test_put_bucket</ID>
        <DisplayName>ut_test_put_bucket</DisplayName>
      </Owner>
      <Buckets>
        <Bucket>
          <CreationDate>2014-05-14T11:18:32.000Z</CreationDate>
          <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
          <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
          <Location>oss-cn-hangzhou</Location>
          <Name>mybucket01</Name>
          <Region>cn-hangzhou</Region>
          <StorageClass>Standard</StorageClass>
        </Bucket>
      </Buckets>
    </ListAllMyBucketsResult>
  • 擷取指定資源群組中的所有Bucket

    請求樣本

    GET / HTTP/1.1
    Date: Thu, 15 May 2014 11:18:32 GMT
    Host: oss-cn-hangzhou.aliyuncs.com
    Authorization: OSS qn6q**************:77Dv****************
    x-oss-resource-group-id: rg-aek27tc********

    返回樣本

    HTTP/1.1 200 OK
    Date: Thu, 15 May 2014 11:18:32 GMT
    Content-Type: application/xml
    Content-Length: 556
    Connection: keep-alive
    Server: AliyunOSS
    x-oss-request-id: 5374A2880232A65C2300****
    <?xml version="1.0" encoding="UTF-8"?>
    <ListAllMyBucketsResult>
      <Owner>
        <ID>512**</ID>
        <DisplayName>51264</DisplayName>
      </Owner>
      <Buckets>
        <Bucket>
          <CreationDate>2014-02-07T18:12:43.000Z</CreationDate>
          <ExtranetEndpoint>oss-cn-shanghai.aliyuncs.com</ExtranetEndpoint>
          <IntranetEndpoint>oss-cn-shanghai-internal.aliyuncs.com</IntranetEndpoint>
          <Location>oss-cn-shanghai</Location>
          <Name>test-bucket-1</Name>
          <Region>cn-shanghai</Region>
          <StorageClass>Standard</StorageClass>
          <ResourceGroupId>rg-aek27tc********</ResourceGroupId>
        </Bucket>
        <Bucket>
          <CreationDate>2014-02-05T11:21:04.000Z</CreationDate>
          <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
          <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
          <Location>oss-cn-hangzhou</Location>
          <Name>test-bucket-2</Name>
          <Region>cn-hangzhou</Region>
          <StorageClass>IA</StorageClass>
          <ResourceGroupId>rg-aek27tc********</ResourceGroupId>
        </Bucket>
      </Buckets>
    </ListAllMyBucketsResult>
  • 擷取預設資源群組中的所有Bucket

    請求樣本

    GET / HTTP/1.1
    Date: Thu, 15 May 2014 11:18:32 GMT
    Host: oss-cn-hangzhou.aliyuncs.com
    Authorization: OSS qn6q**************:77Dv****************
    x-oss-resource-group-id:rg-default-id

    返回樣本

    HTTP/1.1 200 OK
    Date: Thu, 15 May 2014 11:18:32 GMT
    Content-Type: application/xml
    Content-Length: 556
    Connection: keep-alive
    Server: AliyunOSS
    x-oss-request-id: 5374A2880232A65C2300****
    <?xml version="1.0" encoding="UTF-8"?>
    <ListAllMyBucketsResult>
      <Owner>
        <ID>512**</ID>
        <DisplayName>51264</DisplayName>
      </Owner>
      <Buckets>
        <Bucket>
          <CreationDate>2014-02-07T18:12:43.000Z</CreationDate>
          <ExtranetEndpoint>oss-cn-shanghai.aliyuncs.com</ExtranetEndpoint>
          <IntranetEndpoint>oss-cn-shanghai-internal.aliyuncs.com</IntranetEndpoint>
          <Location>oss-cn-shanghai</Location>
          <Name>test-bucket-3</Name>
          <Region>cn-shanghai</Region>
          <StorageClass>Standard</StorageClass>
          <ResourceGroupId>rg-default-id</ResourceGroupId>
        </Bucket>
        <Bucket>
          <CreationDate>2014-02-05T11:21:04.000Z</CreationDate>
          <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
          <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
          <Location>oss-cn-hangzhou</Location>
          <Name>test-bucket-4</Name>
          <Region>cn-hangzhou</Region>
          <StorageClass>IA</StorageClass>
          <ResourceGroupId>rg-default-id</ResourceGroupId>
        </Bucket>
      </Buckets>
    </ListAllMyBucketsResult>

SDK

此介面所對應的各語言SDK如下:

錯誤碼

錯誤碼

HTTP狀態代碼

描述

AccessDenied

403

請求中沒有使用者驗證資訊(即匿名訪問)。