列出容器

  • 發行項

作業 List Containers 會傳回指定記憶體帳戶下容器的清單。

要求

您可以依照下列方式建構 List Containers 要求。 建議使用 HTTPS。 以記憶體帳戶的名稱取代 myaccount 。

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

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

模擬記憶體服務要求

當您對仿真的記憶體服務提出要求時，請將模擬器主機名和 Azure Blob 儲存體 埠指定為 127.0.0.1:10000，後面接著仿真的記憶體帳戶名稱。

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

請注意，仿真的記憶體僅支援最多 2 GiB 的 Blob 大小。

如需詳細資訊，請參閱 使用 Azurite 模擬器進行本機 Azure 記憶體開發 ，以及 記憶體模擬器和 Azure 記憶體服務之間的差異。

URI 參數

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

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

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

請注意，如果清單作業跨越數據分割界限，則服務會傳回接續令牌，以擷取結果的其餘部分。 基於這個理由，服務可能會傳回的結果比 指定的 maxresults少，或預設值為 5000。

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

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

要求標頭

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

要求標頭 描述
Authorization 必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
Date 或 x-ms-date 必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
x-ms-version 所有授權要求都需要。 指定用於這個要求的作業版本。 如需詳細資訊，請參閱 Azure 儲存體服務的版本。
x-ms-client-request-id 選擇性。 提供客戶端產生的不透明值，其中包含 1-kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。 強烈建議您使用此標頭，將用戶端活動與伺服器收到的要求相互關聯。 如需詳細資訊，請參閱監視 Azure Blob 儲存體。

要求本文

無。

回應

回應包括 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>

LeaseStatus、LeaseState 和 LeaseDuration 只會出現在 2012-02-12 版及更新版本。

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

Prefix只有在您在 URI 上指定 、 Marker和 MaxResults 元素時，才會存在。 只有在清單結果未完成時，專案 NextMarker 才會有值。

只有在您在 URI 上指定 include=metadata 參數時，專案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 提供。 它指出容器中的數據是否可以公開存取，以及存取層級。 可能的值包括：

  • container：表示容器和 Blob 數據的完整公用讀取許可權。 用戶端可以透過匿名要求列舉容器內的 Blob，但無法列舉記憶體帳戶內的容器。
  • blob：表示 Blob 的公用讀取許可權。 此容器內的 Blob 資料可以透過匿名要求讀取，但無法使用容器數據。 客戶端無法透過匿名要求列舉容器內的 Blob。

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

HasImmutabilityPolicy 和 HasLegalHold 只會出現在 2017-11-09 版和更新版本中。 HasImmutabilityPolicy 如果 true 容器上已設定固定性原則，則 false 為 ，否則為 。 HasLegalHold 如果 true 容器有一或多個法律保留，則 false 為 ，否則為 。

注意

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

Version如果您指定deleted查詢參數include的值，則 、 DeletedTimeDeleted和 元素RemainingRetentiondays只會出現在 2019-12-12 版和更新版本中。 只有在容器已虛刪除且有資格還原時，才會顯示這些專案。 VersionDeleted、、 DeletedTime和 RemainingRetentiondays 元素只會出現在 2019-12-12 版和更新版本中，如果為查詢參數指定include已刪除的值，以及容器已虛刪除且有資格還原。

授權

在 Azure 記憶體中呼叫任何數據存取作業時，需要授權。 您可以授權 List Containers 作業，如下所示。

Azure 記憶體支援使用 Microsoft Entra ID 來授權 Blob 數據的要求。 透過 Microsoft Entra ID，您可以使用 Azure 角色型存取控制 (Azure RBAC) ，將許可權授與安全性主體。 安全性主體可能是使用者、群組、應用程式服務主體或 Azure 受控識別。 安全性主體是由 Microsoft Entra ID 驗證，以傳回 OAuth 2.0 令牌。 權杖接著可以用來授權對 Blob 服務的要求。

若要深入瞭解使用 Microsoft Entra ID 授權，請參閱使用 Microsoft Entra ID 授權 Blob 的存取權。

權限

以下是 Microsoft Entra 使用者、群組或服務主體呼叫List Containers作業所需的 RBAC 動作，以及包含此動作的最低特殊許可權 Azure RBAC 角色：

若要深入瞭解如何使用 Azure RBAC 指派角色，請參閱 指派 Azure 角色以存取 Blob 數據。

備註

如果您為 參數指定值 maxresults ，而要傳回的容器數目超過此值，或超過的 maxresults預設值，則回應本文將包含 NextMarker 專案。 (這也稱為 接續令牌) 。

NextMarker 表示下一個容器在後續要求上傳回。 若要傳回下一組專案，請在後續要求的 URI 上指定 參數的值NextMarkermarker。 請注意，NextMarker 的值應視為不透明。

如果清單作業跨越數據分割界限，則服務會傳 NextMarker 回元素的值，以擷取下一個數據分割的結果其餘部分。 跨越多個數據分割的清單作業會導致傳回的專案集比 所 maxresults指定的還要小，或預設值為 5000。 當您執行清單作業時，應用程式應該一律檢查元素是否存在 NextMarker ，並據以處理它。

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

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

計費

定價要求可能源自使用 Blob 記憶體 API 的用戶端，無論是直接透過 Blob 記憶體 REST API，還是來自 Azure 記憶體用戶端連結庫。 這些要求會累算每個交易的費用。 交易類型會影響帳戶的收費方式。 例如，讀取交易會累算到與寫入交易不同的計費類別。 下表顯示根據記憶體帳戶類型的要求計費類別 List Containers ：

作業 儲存體帳戶類型 計費類別
列出容器 進階區塊 Blob
標準一般用途 v2
標準一般用途 v1		 列出和建立容器作業

若要瞭解指定計費類別的定價，請參閱 Azure Blob 儲存體 定價。

範例要求與回應

下列範例 URI 會要求帳戶的容器清單，將初始作業傳回的最大結果設定為三。

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 記憶體模擬器進行開發和測試
設定 Blob 記憶體作業的逾時