列出 Blob

List Blobs 作業會傳回指定容器下 Blob 的清單。

請求

您可以建構 List Blobs 要求，如下所示。 建議使用 HTTPS。 以記憶體帳戶的名稱取代 myaccount。

仿真的記憶體服務 URI

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

如需詳細資訊，請參閱 使用 Azurite 模擬器進行本機 Azure 記憶體開發。

URI 參數

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

要求標頭

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

要求本文

沒有。

範例要求

如需範例要求，請參閱 列舉 blob 資源。

回應

回應包含 HTTP 狀態代碼、一組響應標頭，以及 XML 格式的回應本文。

狀態代碼

成功的作業會傳回狀態代碼 200 （確定）。 如您需狀態代碼的相關資訊，請參閱 狀態和錯誤碼。

回應標頭

此作業的回應包含下列標頭。 回應也可以包含額外的標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協定規格，。

回應本文

XML 回應的格式如下所示。

請注意，只有在要求 URI 上指定 Prefix、Marker、MaxResults和 Delimiter 元素時，才會存在。 只有當清單結果未完成時，NextMarker 元素才會有值。

只有在要求 URI 上以 include 參數指定快照集、Blob 元數據和未認可的 Blob 時，才會包含在回應中。

在 2009-09-19 版和更新版本中，Blob 的屬性會封裝在 Properties 專案中。

從 2009-09-19 版開始，List Blobs 會在回應本文中傳回下列已重新命名的專案：

• Last-Modified（先前 LastModified）

• Content-Length（先前 Size）

• Content-Type（先前 ContentType）

• Content-Encoding（先前 ContentEncoding）

• Content-Language（先前 ContentLanguage）

使用 2009-09-19 版和更新版本建立的 Blob，會出現 Content-MD5 專案。 在 2012-02-12 版和更新版本中，Blob 記憶體會使用 Put Blob來計算上傳 Blob 時 Content-MD5 值。 當您使用 [放置區塊清單]建立 Blob 時，Blob 記憶體不會計算此專案。 您可以在建立 Blob 時明確設定 Content-MD5 值，或呼叫 放置區塊清單 或 設定 Blob 屬性 作業。

對於 2009-09-19 和更新版本，但在 2015-02-21 版之前，您無法在包含附加 Blob 的容器上呼叫 List Blobs。 如果清單的結果包含附加 Blob，服務會傳回狀態代碼 409 （衝突）。

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

CopyId、CopyStatus、CopySource、CopyProgress、CopyCompletionTime和 CopyStatusDescription 只會出現在 2012-02-12 版和更新版本中，當這項作業包含 include={copy} 參數時。 如果此 Blob 從未在 Copy Blob 作業中成為目的地，則不會出現這些元素。 如果這個 Blob 在結束的 Copy Blob 作業之後，使用 Set Blob Properties、Put Blob或 Put Block List，就不會顯示元素。 這些元素也不會出現在 2012-02-12 版之前，複製 Blob所建立的 Blob。

在 2013-08-15 版和更新版本中，EnumerationResults 元素包含指定 Blob 端點的 ServiceEndpoint 屬性。 這個專案也包含指定容器名稱的 ContainerName 欄位。 在舊版中，這兩個屬性會在 [ContainerName] 字段中合併在一起。 此外，在 2013-08-15 版和更新版本中，已移除 Blob 底下的 Url 元素。

針對 2015-02-21 版和更新版本，List Blobs 傳回所有類型的 Blob（區塊、分頁和附加 Blob）。

針對 2015-12-11 版和更新版本，List Blobs 會傳回 ServerEncrypted 元素。 如果 Blob 和應用程式元數據已完全加密，則此元素會設定為 true，否則 false。

針對 2016-05-31 版和更新版本，List Blobs 傳回累加複製 Blob 和快照集的 IncrementalCopy 元素，值設定為 true。

針對 2017-04-17 版和更新版本，如果明確設定存取層，List Blobs 會傳回 AccessTier 元素。 如需允許的進階分頁 Blob 層清單，請參閱 VM 的高效能進階記憶體和受控磁碟。 針對 Blob 記憶體或一般用途 v2 帳戶，有效值為 Hot、Cool和 Archive。 如果 Blob 處於解除凍結擱置狀態，則會使用其中一個有效值傳回 ArchiveStatus 元素（rehydrate-pending-to-hot、rehydrate-pending-to-cool或 rehydrate-pending-to-cold）。 如需區塊 Blob 階層處理的詳細資訊，請參閱經常性存取、非經常性存取和封存儲存層。

針對 2017-04-17 版和更新版本，List Blobs 傳回 Blob 記憶體或一般用途 v2 帳戶上的 AccessTierInferred 元素。 如果區塊 Blob 沒有存取層集，則會從記憶體帳戶屬性推斷階層資訊，且此值設定為 true。 只有在從帳戶屬性推斷階層時，才會有此標頭。

針對 2017-04-17 版和更新版本，List Blobs 傳回 Blob 記憶體或一般用途 v2 帳戶上的 AccessTierChangeTime 元素。 只有在已設定區塊 Blob 上的層時，才會傳回這個值。 如需詳細資訊，請參閱在標頭中 日期時間值的表示。

針對 2017-07-29 版和更新版本，當此作業包含 include={deleted} 參數時，會出現 Deleted、DeletedTime和 RemainingRetentionDays。 如果未刪除此 Blob，這些元素就不會顯示。 啟用虛刪除功能時，會針對使用 DELETE 作業刪除的 Blob 或快照集顯示這些專案。 Deleted 元素會設定為 true 虛刪除的 Blob 和快照集。 Deleted-Time 對應至刪除 Blob 的時間。 RemainingRetentionDays 指出虛刪除 Blob 永久刪除後的天數。

針對 2017-11-09 版和更新版本，Creation-Time 傳回建立此 Blob 的時間。

針對 2019-02-02 版和更新版本，如果 Blob 是以客戶提供的密鑰加密，List Blobs 會傳回 CustomerProvidedKeySha256 元素。 值會設定為用來加密 Blob 之金鑰的 SHA-256 哈希。 此外，如果作業包含 include={metadata} 參數，而且在以客戶提供的密鑰加密的 Blob 上有應用程式元數據，則 Metadata 元素會有 Encrypted="true" 屬性。 這個屬性表示 Blob 具有無法解密為 List Blobs 作業一部分的元數據。 若要存取這些 Blob 的元數據，請使用客戶提供的密鑰呼叫 取得 Blob 屬性 或 取得 Blob 元數據。

針對 2019-02-02 版和更新版本，如果 Blob 是以加密範圍加密，List Blobs 會傳回 EncryptionScope 元素。 值會設定為用來加密 Blob 的加密範圍名稱。 如果作業包含 include={metadata} 參數，則 blob 上的應用程式元數據會以透明方式解密，並在 Metadata 專案中提供。

針對 2019-12-12 版和更新版本，如果對象處於 rehydrate pending 狀態，List Blobs 會在 Blob 記憶體或一般用途 v2 帳戶上傳回 RehydratePriority 元素。 有效值為 High 與 Standard。

針對 2019-12-12 版和更新版本，List Blobs 在帳戶上啟用版本設定時，傳回 blob 和產生的 Blob 版本 VersionId 專案。

針對 2019-12-12 版和更新版本，List Blobs 會傳回目前 Blob 版本的 IsCurrentVersion 專案。 值設定為 true。 這個專案可讓您區分目前版本與唯讀自動產生的版本。

針對 2019-12-12 版和更新版本，List Blobs 傳回具有任何標籤之 Blob 的 TagCount 元素。 只有當此作業包含 include={tags} 參數時，才會顯示 Tags 專案。 如果 Blob 上沒有標記，就不會顯示這些專案。

針對 2019-12-12 版和更新版本，List Blobs 會傳回附加 Blob 的 Sealed 專案。 只有當附加 Blob 已密封時，才會顯示 Sealed 專案。 如果附加 Blob 未密封，就不會顯示這些專案。

針對 2020-02-10 版和更新版本，List Blobs 會傳回 LastAccessTime 元素。 元素會根據記憶體帳戶上次存取時間追蹤原則，顯示 Blob 數據上次存取的時間。 如果記憶體帳戶沒有此原則，或已停用原則，則不會傳回 元素。 如需設定帳戶上次存取時間追蹤原則的相關信息，請參閱 Blob 服務 API。 LastAccessTime 元素不會追蹤上次存取 Blob 元數據的時間。

針對 2020-06-12 版和更新版本，當此作業包含 include={immutabilitypolicy} 參數時，List Blobs 會傳回 ImmutabilityPolicyUntilDate 和 ImmutabilityPolicyMode 元素。

針對 2020-06-12 版和更新版本，當此作業包含 include={legalhold} 參數時，List Blobs 會傳回 LegalHold 元素。

針對 2020-06-12 版和更新版本，針對已啟用階層命名空間的帳戶，List Blobs 會傳回 Owner、Group、Permissions和 Acl 元素。 要求必須包含 include={permissions} 參數。 請注意，Acl 項目是檔案或目錄上設定之存取和預設訪問控制清單的合併清單。

針對 2020-06-12 版和更新版本，針對已啟用階層命名空間的帳戶，List Blobs 具有分隔符的帳戶會傳回 BlobPrefix 元素中的 Properties 專案。 這會對應至目錄上的屬性。

針對 2020-08-04 版和更新版本，針對已啟用階層命名空間的帳戶，List Blobs 會傳回已刪除 Blob 的 DeletionId 元素。 DeletionId 是未簽署的64位標識碼。 元素可唯一識別虛刪除的路徑，以便與具有相同路徑的其他已刪除 Blob 區別。

針對 2020-10-02 版和更新版本，針對已啟用階層命名空間的帳戶，List Blobs 會傳回路徑的 ResourceType 屬性元素。 這可以是 file 或 directory。

針對 2021-02-12 版和更新版本，List Blobs 會根據 RFC 2396 百分比編碼所有 BlobName 或 BlobPrefixName 元素值。 具體來說，它會針對包含 XML 中無效字元的值執行此動作（U+FFFE 或 U+FFFF）。 如果編碼，Name 專案會包含 Encoded=true 屬性。 請注意，這隻會針對 xml 中含有無效字元的 Name 專案值發生，而不是回應中的其餘 Name 專案。

針對 2021-06-08 版和更新版本，針對已啟用階層命名空間的帳戶，List Blobs 會傳回 Placeholder properties 元素。 它會在佔位元目錄的 BlobPrefix 元素中傳回這個專案，以分隔符列出已刪除的 Blob。 這些佔位元目錄存在，可協助流覽虛刪除的 Blob。

針對 2021-06-08 版和更新版本，針對已啟用階層命名空間的帳戶，List Blobs 會傳回 EncryptionContext 元素。 如果已設定加密內容屬性值，則會傳回 set 值。

針對 2020-02-10 版和更新版本，針對已啟用階層命名空間的帳戶，List Blobs 傳回已刪除 Blob 的 Expiry-Time 元素。 Expiry-Time 是檔案到期的時間，如果到期時間相同，則會傳回該檔案。

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="http://myaccount.blob.core.windows.net/"  ContainerName="mycontainer">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Delimiter>string-value</Delimiter>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</name>  
      <Snapshot>date-time-value</Snapshot>  
      <VersionId>date-time-vlue</VersionId>
      <IsCurrentVersion>true</IsCurrentVersion>
      <Deleted>true</Deleted>
      <Properties> 
        <Creation-Time>date-time-value</Creation-Time>
        <Last-Modified>date-time-value</Last-Modified>  
        <Etag>etag</Etag>
        <Owner>owner user id</Owner>
        <Group>owning group id</Group>
        <Permissions>permission string</Permissions>
        <Acl>access control list</Acl>
        <ResourceType>file | directory</ResourceType>
        <Placeholder>true</Placeholder>
        <Content-Length>size-in-bytes</Content-Length>  
        <Content-Type>blob-content-type</Content-Type>  
        <Content-Encoding />  
        <Content-Language />  
        <Content-MD5 />  
        <Cache-Control />  
        <x-ms-blob-sequence-number>sequence-number</x-ms-blob-sequence-number>  
        <BlobType>BlockBlob|PageBlob|AppendBlob</BlobType>  
        <AccessTier>tier</AccessTier>  
        <LeaseStatus>locked|unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration>  
        <CopyId>id</CopyId>  
        <CopyStatus>pending | success | aborted | failed </CopyStatus>  
        <CopySource>source url</CopySource>  
        <CopyProgress>bytes copied/bytes total</CopyProgress>  
        <CopyCompletionTime>datetime</CopyCompletionTime>  
        <CopyStatusDescription>error string</CopyStatusDescription>  
        <ServerEncrypted>true</ServerEncrypted> 
        <CustomerProvidedKeySha256>encryption-key-sha256</CustomerProvidedKeySha256>
        <EncryptionContext>encryption-context<EncryptionContext>
        <EncryptionScope>encryption-scope-name</EncryptionScope>
        <IncrementalCopy>true</IncrementalCopy>
        <AccessTierInferred>true</AccessTierInferred>
        <AccessTierChangeTime>datetime</AccessTierChangeTime>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
        <TagCount>number of tags between 1 to 10</TagCount>
        <RehydratePriority>rehydrate priority</RehydratePriority>
        <Expiry-Time>date-time-value</Expiry-Time>
      </Properties>  
      <Metadata>     
        <Name>value</Name>  
      </Metadata>  
      <Tags>
          <TagSet>
              <Tag>
                  <Key>TagName</Key>
                  <Value>TagValue</Value>
              </Tag>
          </TagSet>
      </Tags>
      <OrMetadata />
    </Blob>  
    <BlobPrefix>  
      <Name>blob-prefix</Name>  
    </BlobPrefix>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>  

範例回應

如需範例回應，請參閱 列舉 blob 資源。

授權

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

言論

回應中的 Blob 屬性

如果您已要求將未認可的 Blob 包含在列舉中，請注意，在認可 Blob 之前，不會設定某些屬性。 某些屬性可能不會在回應中傳回。

x-ms-blob-sequence-number 專案只會針對分頁 Blob 傳回。

OrMetadata 專案只會針對區塊 Blob 傳回。

對於分頁 Blob，Content-Length 項目中傳回的值會對應至 blob x-ms-blob-content-length 標頭的值。

只有當已使用 2009-09-19 版或更新版本在 Blob 上設定 Content-MD5 專案才會出現在響應主體中。 您可以在建立 Blob 時設定 Content-MD5 屬性，或呼叫 [設定 Blob 屬性]。 在 2012-02-12 版和更新版本中，Put Blob 設定區塊 Blob 的 MD5 值，即使 Put Blob 要求不包含 MD5 標頭也一定。

回應中的元數據

只有在 URI 上指定了 include=metadata 參數時，才會有 Metadata 專案。 在 Metadata 元素內，每個名稱/值組的值都會列在對應至配對名稱的專案內。

請注意，使用此參數要求的元數據必須根據 2009-09-19 版 Blob 記憶體所強加的命名限制來儲存。 從這個版本開始，所有元資料名稱都必須遵守 C# 識別子的命名慣例，。

如果元數據名稱/值組違反這些命名限制，回應本文會指出 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>  
…  
  

回應中的標記

只有在 URI 上指定了 include=tags 參數，而且 Blob 上有標記時，才會有 Tags 專案。 在 TagSet 專案中，最多會傳回 10 個 Tag 元素，每個元素都包含使用者定義 Blob 索引標記的 key 和 value。 回應中不保證標記的順序。

如果 Blob 上沒有標記，則不會傳回 Tags 和 TagCount 專案。

記憶體服務會維護 Blob 與其標籤之間的強式一致性，但次要索引最終會保持一致。 標記可以在回應 List Blobs 中看見，然後才能 Find Blobs by Tags 作業。

回應中的快照集

只有在 URI 上指定了 include=snapshots 參數時，才會在回應中列出快照集。 回應中列出的快照集不包含 LeaseStatus 項目，因為快照集不能有作用中租用。

使用服務版本 2021-06-08 和更新版本，您可以使用分隔符呼叫 List Blobs，並在列舉中包含快照集。 對於 2021-06-08 之前的服務版本，包含兩者的要求都會傳回 InvalidQueryParameter 錯誤（HTTP 狀態代碼 400 – 不正確的要求）。

回應中未認可的 Blob

只有在 URI 上指定了 include=uncommittedblobs 參數時，才會在回應中列出未認可的 Blob。 回應中列出的未認可的 Blob 不包含下列任何元素：

• Last-Modified

• Etag

• Content-Type

• Content-Encoding

• Content-Language

• Content-MD5

• Cache-Control

• Metadata

回應中已刪除的 Blob

只有在 URI 上指定了 include=deleted 參數時，才會在回應中列出已刪除的 Blob。 回應中所列的已刪除 Blob 不包含 租用 元素，因為已刪除的 Blob 不能有作用中租用。

如果已在 URI 上指定 include=deleted,snapshot，則會在清單回應中包含已刪除的快照集。

回應中的物件復寫元數據

在 Blob 上評估物件複寫策略，並使用版本 2019-12-12 或更新版本進行 List Blobs 呼叫時，就會出現 OrMetadata 專案。 在 OrMetadata 元素內，每個名稱/值組的值都會列在對應至配對名稱的專案內。 名稱的格式為 or-{policy-id}_{rule-id}，其中 {policy-id} 是 GUID，代表記憶體帳戶上的物件復寫原則標識碼。 {rule-id} 是 GUID，代表記憶體容器上的規則識別碼。 有效值為 complete 或 failed。

  
…  
<OrMetadata>  
  <or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>complete</or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>  
  <or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>failed</or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>  
</OrMetadata>  
…  
  

回應中的不變性原則

只有在 URI 上指定了 include=immutabilitypolicy 參數時，才會有 ImmutabilityPolicyUntilDate 和 ImmutabilityPolicyMode 元素。

<Properties> 
   <ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>   
   <ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>  
</Properties> 

回應中的法律保留

只有在 URI 上指定了 include=legalhold 參數時，才會有 LegalHold 專案。

<Properties> 
  <LegalHold>true | false </LegalHold>  
</Properties> 

使用標記值傳回結果集

如果您為 maxresults 參數指定值，而傳回的 Blob 數目超過此值，或超過 maxresults的預設值，響應主體會包含 NextMarker 專案。 這個專案表示在後續要求上傳回的下一個 Blob。 在某些情況下，即使傳回的結果數目小於 maxresults的值，服務還是可能會傳回 NextMarker 專案。

若要傳回下一組專案，請將 NextMarker 的值指定為後續要求的 URI 上的標記參數。 請注意，NextMarker 的值應該視為不透明。

使用分隔符周遊 Blob 命名空間

delimiter 參數可讓呼叫者使用用戶設定的分隔符來周遊 Blob 命名空間。 如此一來，您就可以周遊 Blob 的虛擬階層，就像是文件系統一樣。 分隔符可以是單一字元或字串。

當要求包含此參數時，作業會傳回 BlobPrefix 專案。 傳回 BlobPrefix 專案，取代名稱開頭為相同子字串的所有 Blob，最多到分隔符的外觀。 BlobPrefix 元素的值是 子字串+分隔符，其中 子字串 是開始一或多個 Blob 名稱的常見子字元串，而 分隔符 是 delimiter 參數的值。

您可以使用 BlobPrefix 的值進行後續呼叫，以列出開頭為這個前置詞的 Blob。 您可以藉由指定要求 URI 上 prefix 參數的 BlobPrefix 值來執行此動作。

請注意，每個傳回 BlobPrefix 專案都會計入結果上限，就像每個 Blob 項目一樣。

Blob 會依字母順序列在回應本文中，並先列出大寫字母。

複製狀態描述中的複製錯誤

CopyStatusDescription 包含 Copy Blob 失敗的詳細資訊。

• 當複製嘗試失敗時，如果 Blob 記憶體仍在重試作業，CopyStatus 會設定為 pending。 CopyStatusDescription 文字描述上次複製嘗試期間可能發生的失敗。

• 當 CopyStatus 設定為 failed時，CopyStatusDescription 文字描述導致複製作業失敗的錯誤。

下表描述每個 CopyStatusDescription 值的欄位。

下表說明常見失敗案例的 CopyStatus 和 CopyStatusDescription 值。

計費

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

若要瞭解指定計費類別的定價，請參閱 azure Blob 記憶體定價。

另請參閱

狀態和錯誤碼
Blob 記憶體錯誤碼