列出容器

作業會傳回 List Containers 指定之儲存體帳戶下的容器清單。

請求

List Containers 要求的建構如下。 建議使用 HTTPS。 以您的儲存體帳戶名稱取代 我的帳戶

方法 要求 URI HTTP 版本
GET https://myaccount.blob.core.windows.net/?comp=list HTTP/1.1

請注意,URI 一律需包含正斜線 (/),將主機名稱與 URI 的路徑和查詢部分隔開。 若為 List Containers 作業,URI 的路徑部分為空白。

模擬儲存體服務要求

對模擬儲存體服務提出要求時,請將模擬器主機名稱和 Blob 服務通訊埠指定為 127.0.0.1:10000,後面接著模擬儲存體帳戶名稱:

方法 要求 URI HTTP 版本
GET http://127.0.0.1:10000/devstoreaccount1?comp=list HTTP/1.1

請注意,模擬儲存體僅支援最多2個 GiB 的 blob 大小。

如需詳細資訊,請參閱使用 Azure 儲存體 Emulator 進行開發和測試,以及儲存體 Emulator 與 Azure 儲存體服務之間的差異

URI 參數

您可以在要求的 URI 中指定下列其他參數。

參數 描述
prefix 選擇性。 篩選結果,只傳回名稱開頭為指定前置詞的容器。
marker 選擇性。 字串值,識別要在下一個清單作業中傳回的容器清單部分。 NextMarker如果清單作業未傳回與目前頁面一起列出的所有容器,則作業會在回應主體中傳回值。 在 NextMarker 後續的呼叫中,您可以使用此值做為參數的值, marker 以要求下一個清單專案的頁面。

此標記值對於用戶端為不透明。
maxresults 選擇性。 指定要傳回的最大容器數目。 如果要求未指定 maxresults 或指定大於5000的值,伺服器將會傳回最多5000個專案。

請注意,如果清單作業跨越分割區界限,則服務會傳回接續 token,以抓取結果的其餘部分。 基於這個理由,服務可能會傳回比所指定更少的結果 maxresults ,或超過預設值5000。

如果參數設定為小於或等於零的值,伺服器會傳回狀態碼 400 (錯誤的要求) 。
include={metadata,deleted,system} 選擇性。 指定一個或多個包含在回應中的資料集:

-metadata:請注意,使用此參數要求的中繼資料必須根據 Blob 服務2009-09-19 版本所加諸的命名限制來儲存。 從這個版本開始,所有中繼資料名稱必須遵守 c # 識別碼的命名慣例。
-deleted:2019-12-12 版和更新版本。 指定已虛刪除的容器應該包含在回應中。
-system:2020-10-02 版或更新版本。 指定是否要在回應中包含系統容器。 包含這個選項會列出系統容器,例如 $logs 和 $changefeed。 請注意,傳回的特定系統容器會根據儲存體帳戶上啟用的服務功能而有所不同。
timeout 選擇性。 timeout 參數以秒為單位。 如需詳細資訊,請參閱 設定 Blob 服務作業的超時

要求標頭

下表描述必要的和選用的要求標頭。

要求標頭 描述
Authorization 必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊,請參閱授權 Azure 儲存體的要求
Datex-ms-date 必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊,請參閱授權 Azure 儲存體的要求
x-ms-version 所有授權要求都需要。 指定用於這個要求的作業版本。 如需詳細資訊,請參閱Azure 儲存體服務的版本控制
x-ms-client-request-id 選擇性。 提供用戶端產生的不透明值,具有1個 KiB 字元限制,當啟用儲存體分析記錄時,記錄在分析記錄中。 強烈建議使用此標頭來將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊,請參閱關於儲存體分析記錄Azure 記錄:使用記錄檔追蹤儲存體要求

要求本文

無。

回應

回應包括 HTTP 狀態碼、一組回應標頭和 XML 格式的回應主體。

狀態碼

成功的作業會傳回狀態碼 200 (OK)。

如需狀態碼的相關資訊,請參閱 狀態和錯誤碼

回應標頭

這項作業的回應包括下列標頭。 此回應也包含其他標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協定規格

回應標頭 描述
Content-Type 標準 HTTP/1.1 標頭。 指定傳回結果的格式。 此值目前為 application/xml。
x-ms-request-id 此標頭可唯一識別提出的要求,而且可用來進行要求的疑難排解。 如需詳細資訊,請參閱 疑難排解 API 作業
x-ms-version 指出用於執行要求的 Blob 服務版本。 對 2009-09-19 (含) 以上版本提出要求會傳回此標頭。
Date 服務產生的 UTC 日期/時間值,可指出啟動回應的時間。
x-ms-client-request-id 此標頭可用於疑難排解要求和對應的回應。 x-ms-client-request-id如果要求中有標頭的值,且值最多1024個可見的 ASCII 字元,則此標頭的值會等於標頭的值。 如果 x-ms-client-request-id 標頭不存在於要求中,則回應中不會出現此標頭。

回應本文

回應本文的格式如下。

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Containers>  
    <Container>  
      <Name>container-name</Name>  
      <Version>container-version</Version>
      <Deleted>true</Deleted>
      <Properties>  
        <Last-Modified>date/time-value</Last-Modified>  
        <Etag>etag</Etag>  
        <LeaseStatus>locked | unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration> 
        <PublicAccess>container | blob</PublicAccess>
        <HasImmutabilityPolicy>true | false</HasImmutabilityPolicy>
        <HasLegalHold>true | false</HasLegalHold>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Container>  
  </Containers>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>  

LeaseStatusLeaseStateLeaseDuration 只會出現在 2012-02-12 版及更新版本。

從 2013-08-15 版開始,AccountName 元素的 EnumerationResults 屬性已重新命名為 ServiceEndpointURL 元素也已經從 Container 元素中移除。 若為 2013-08-15 之前的版本,容器的 URL (如 URL 欄位所指定) 不包含 restype=container 參數。 如果您使用此值對列舉的容器進行後續要求,請務必附加此參數,以指定資源類型為容器。

只有在 URI 中指定 PrefixMarkerMaxResults 項目時,這些項目才存在。 只有清單結果不完整時,NextMarker 項目才具有值。

只有在 URI 中指定 Metadata 參數時,include=metadata 項目才存在。 在 Metadata 項目中,每個名稱/值組的值會列於與組合名稱對應的項目內。

如有中繼資料名稱/值組違反 2009-09-19 版本所強制執行的命名限制,回應主體會在 x-ms-invalid-name 項目內指出此問題名稱,如下列 XML 片段所示:

  
<Metadata>  
  <MyMetadata1>first value</MyMetadata1>  
  <MyMetadata2>second value</MyMetadata2>  
  <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>  
</Metadata>  
  

從2016-05-31 版開始,會在 PublicAccess 屬性中提供容器 public 許可權。 它會指出是否可以公開存取容器中的資料,以及存取層級。 可能的值包括:

  • 容器:指出容器和 blob 資料的完整公用讀取權限。 用戶端可以透過匿名要求列舉容器內的 Blob,但無法列舉儲存體帳戶內的容器。
  • blob:表示 blob 的公用讀取權限。 您可以透過匿名要求讀取此容器內的 Blob 資料,但您無法使用容器資料。 用戶端無法透過匿名要求列舉容器內的 Blob。

如果未在中指定這個屬性, 區段中,容器是帳戶擁有者的私人容器。

HasImmutabilityPolicy 而且 HasLegalHold 只會顯示在2017-11-09 版和更新版本中。 HasImmutabilityPolicy``true如果容器上已設定永久性原則,則為, false 否則為。 HasLegalHold``true如果容器有一或多個合法保存 (s) ,則為, false 否則為。

注意

從 2009-09-19 版開始,List Containers 的回應主體會在 Last-Modified 項目中傳回容器上次修改的時間。 在舊版中,此項目的名稱為 LastModified

Version Deleted DeletedTime RemainingRetentiondays 如果 deleted 指定查詢參數的值,且 include 容器已虛刪除且符合可還原的狀態,則、、和元素只會出現在2019-12-12 版和更新版本中。

授權

只有帳戶擁有者可呼叫這項作業。

備註

如果您指定參數的值, maxresults 且要傳回的容器數目超過此值,或超過的預設值, maxresults 回應主體會包含 NextMarker 元素 (也稱為接續 token) 。 NextMarker 指出後續要求所要傳回的下一個容器。 若要傳回下一組專案,請 NextMarker marker 在 URI 上針對後續要求指定的參數值。 請注意,NextMarker 的值應視為不透明。

如果清單作業跨越分割區界限,則服務會傳回專案的值,以抓取 NextMarker 下一個資料分割的其餘結果。 跨越多個分割區的清單作業,會導致傳回的專案數目比指定的專案數少 maxresults ,或是預設值5000。 當您執行清單作業時,您的應用程式應該一律檢查元素是否存在 NextMarker ,並據以進行處理。

容器會依字母順序列於回應主體中。

List Containers 作業將於 30 秒後逾時。

範例要求和回應

下列範例中,URI 要求帳戶的容器清單,並將初始作業所要傳回的最大結果數目設為 3。

GET https://myaccount.blob.core.windows.net/?comp=list&maxresults=3 HTTP/1.1  

所傳送的要求包含下列標頭:

x-ms-version: 2016-05-31  
x-ms-date: Wed, 26 Oct 2016 22:08:44 GMT  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/D5Gy0fXvg=  

傳回的狀態碼和回應標頭如下:

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Wed, 26 Oct 2016 22:08:54 GMT  
x-ms-version: 2016-05-31  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
  

此要求的回應 XML 如下。 請注意,NextMarker 項目跟隨在一組容器之後,並包含所要傳回之下一個容器的名稱。

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net/">  
  <MaxResults>3</MaxResults>  
  <Containers>  
    <Container>  
      <Name>audio</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C6B1B2</Etag> 
        <PublicAccess>container</PublicAccess> 
      </Properties>  
    </Container>  
    <Container>  
      <Name>images</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C1EEEC</Etag>  
      </Properties>  
    </Container>  
    <Container>  
      <Name>textfiles</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7BACAC3</Etag>  
      </Properties>  
    </Container>  
  </Containers>  
  <NextMarker>video</NextMarker>  
</EnumerationResults>  

後續清單作業在要求 URI 中指定標記 (如下所示)。 下一組結果在回傳時,會以標記所指定的容器起始。

https://myaccount.blob.core.windows.net/?comp=list&maxresults=3&marker=video  

另請參閱

授權 Azure 儲存體的要求
狀態和錯誤碼
Blob 服務錯誤碼
列舉 Blob 資源
使用 Azure 儲存體 Emulator 進行開發和測試
設定 Blob 服務作業的逾時值