銷售: 1-800-867-1380

列出 Blob

更新日期: 2014年2月

List Blobs 作業會列舉指定容器下的 Blob 清單。

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

 

方法 要求 URI HTTP 版本

GET

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list

HTTP/1.1

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

 

方法 要求 URI HTTP 版本

GET

http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list

HTTP/1.1

如需詳細資訊,請參閱使用 Azure 儲存體模擬器進行開發和測試

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

 

參數 描述

prefix

選擇性。篩選結果,只傳回名稱開頭為指定前置詞的 Blob。

delimiter

選擇性。要求包含此參數時,作業會在回應主體中傳回 BlobPrefix 項目,做為所有 Blob 的預留位置,在分隔符號字元出現之前,這些 Blob 的名稱開頭為相同的子字串。此分隔符號可以是單一字元或字串。

marker

選擇性。識別下一個清單作業所要傳回之清單部分的字串值。如果傳回的清單不完整,此作業會在回應主體中傳回標記值。您可以接著在要求下一組清單項目的後續呼叫中,使用此標記值。

此標記值對於用戶端為不透明。

maxresults

選擇性。指定要傳回的 Blob 數目上限,包括所有 BlobPrefix 項目。如果要求未指定 maxresults 或指定大於 5,000 的值,伺服器最多將傳回 5,000 個項目。

若將 maxresults 設為小於或等於零的值,將會產生錯誤回應碼 400 (不正確的要求)。

include={snapshots,metadata,uncommittedblobs,copy}

選擇性。指定一個或多個包含在回應中的資料集:

  • snapshots:指定列舉中應包含快照集。回應中的快照集清單是從最舊排到最新。

  • metadata:指定回應中應傳回 Blob 中繼資料。

  • uncommittedblobs:指定回應中包含的 Blob,其區塊已上傳,但是此 Blob 尚未使用 放置區塊清單 認可。

  • copy:2012-02-12 版及更新的版本。指定在回應中包含的中繼資料,此資料與任何目前或先前的 Copy Blob 作業都有關聯。

若要在 URI 中指定上述多個選項,您必須以 URL 編碼的逗號 ("%82") 分隔每一個選項。

timeout

選擇性。timeout 參數以秒為單位。如需詳細資訊,請參閱設定 Blob 服務作業的逾時值

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

 

要求標頭 描述

Authorization

必要項。指定驗證配置、帳戶名稱及簽章。如需詳細資訊,請參閱Azure 儲存體服務的驗證

Datex-ms-date

必要項。指定要求的國際標準時間 (UTC)。如需詳細資訊,請參閱Azure 儲存體服務的驗證

x-ms-version

所有已驗證要求為必要項,匿名要求則為選擇性。指定用於這個要求的作業版本。如需詳細資訊,請參閱Azure 儲存體服務的版本設定

x-ms-client-request-id

選擇性。提供由用戶端產生的不透明值 (具有 1 KB 的字元限制),當儲存體分析記錄為啟用狀態時,此值會記錄在分析記錄檔中。如果是和伺服器所接收的要求相關的用戶端活動,則強烈建議您使用此標頭。如需詳細資訊,請參閱關於儲存體分析記錄Azure 記錄:使用記錄檔追蹤儲存體需求

無。

如需範例要求,請參閱列舉 Blob 資源

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

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

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

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

 

回應標頭 描述

Content-Type

指定傳回結果的格式。此值目前為 application/xml

x-ms-request-id

此標頭可唯一識別提出的要求,而且可用來進行要求的疑難排解。如需詳細資訊,請參閱對應用程式開發介面作業進行疑難排解

x-ms-version

指出用於執行要求的 Blob 服務版本。針對使用 2009-09-19 版及較新版本提出的要求,會傳回此標頭。

如果容器使用 2009-09-19 版的 Blob 服務標示公開存取,也會針對未指定版本的匿名要求傳回此標頭。

Date

服務產生的 UTC 日期/時間值,可指出啟動回應的時間。

XML 回應的格式如下。

請注意,唯有在要求 URI 中指定 PrefixMarkerMaxResultsDelimiter 項目時,這些項目才存在。只有清單結果不完整時,NextMarker 項目才具有值。

唯有在要求 URI 中以 include 參數指定快照集、Blob 中繼資料和未認可的 Blob,這些項目才會包含在回應中。

在 2009-09-19 版及更新版本中,Blob 的屬性是封裝在 Properties 項目中。

在 2013-08-15 和更新版中,EnumerationResults 元素包含指定 Blob 端點的 ServiceEndpoint 屬性,以及指定容器名稱的 ContainerName 欄位。在舊版中這兩個屬性是合併在 ContainerName 欄位內。在 2013-08-15 和更新版中也移除了 Url 下的 Blob 元素。

<?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>
   <Properties>
    <Last-Modified>date-time-value</Last-Modified>
    <Etag>etag</Etag>
    <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</BlobType>
    <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>
   </Properties>
   <Metadata>  
    <Name>value</Name>
   </Metadata>
  </Blob>
  <BlobPrefix>
   <Name>blob-prefix</Name>
  </BlobPrefix>
 </Blobs>
 <NextMarker />
</EnumerationResults>

LeaseStateLeaseDuration 只出現在 2012-02-12 版及更新版本中。

當此作業包含 include={copy} 參數時,CopyIdCopyStatusCopySourceCopyProgressCopyCompletionTimeCopyStatusDescription 只會出現在 2012-02-12 版及更新版本中。如果此 Blob 從未成為 Copy Blob 作業的目的地,或是如果使用 Copy BlobSet Blob PropertiesPut Blob 進行 Put Block List 作業之後修改此 Blob,這些項目都不會出現。如果是在 2012-02-12 版之前,以 複製 Blob 建立的 Blob,也不會出現這些項目。

note附註
從 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 上傳 Blob 時,Blob 服務會計算 Content-MD5 值,但是當您使用 放置區塊清單 建立 Blob 時,並不會計算此值。您可以在建立 Blob 時明確設定 Content-MD5 值,或是呼叫 放置區塊清單設定 Blob 屬性 作業。

如需範例回應,請參閱列舉 Blob 資源

如果將容器的存取控制清單 (ACL) 設為允許匿名容器的存取,任何用戶端都可以呼叫這項作業。否則,可由帳戶擁有者以及有權在容器中列出 Blob 之共用存取簽章的任何人呼叫此作業。

回應中的 Blob 屬性

如果您已要求將未認可的 Blob 包含在列舉中,請注意有些屬性在認可 Blob 之後才會進行設定,所以有些屬性不會在回應中傳回。

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

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

使用 2009-09-19 版或更新版本,將 Content-MD5 項目設定在 Blob 上,該項目才會出現在回應主體中。您可以在建立 Blob 時設定 Content-MD5 屬性,或是呼叫 設定 Blob 屬性。在 2012-02-12 版及更新版本中,Put Blob 會設定區塊 Blob 的 MD5 值,即使 Put Blob 要求不包含 MD5 標頭亦然。

回應中的中繼資料

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

請注意,您必須根據 2009-09-19 版的 Blob 服務規定的命名限制,藉以儲存使用此參數要求的中繼資料。從這個版本開始,所有中繼資料名稱必須遵守 C# 識別碼的命名慣例。

如有中繼資料名稱/值組違反 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>
   …

回應中的快照集

唯有在 URI 中指定 include=snapshots 參數,快照集才會在回應中列出。在回應中列出的快照集不包括 LeaseStatus 項目,因為快照集不能有作用中租用。

如果使用分隔符號呼叫 List Blobs,也不能將快照集包含在列舉中。同時包含這兩項的要求會傳回 InvalidQueryParameter 錯誤 (HTTP 狀態碼 400 - 不正確的要求)。

回應中的未認可 Blob

唯有在 URI 中指定 include=uncommittedblobs 參數,未認可的 Blob 才會在回應中列出。在回應中列出的未認可 Blob 不包含下列任一項目:

  • Last-Modified

  • Etag

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-MD5

  • Cache-Control

  • Metadata

使用標記值傳回結果集

如果您指定 maxresults 參數的值,且要傳回的 Blob 數目超過此值,或超過 maxresults 的預設值,回應主體會包含 NextMarker 項目,該項目指出後續要求中傳回的下一個 Blob。若要傳回下一組項目,請指定 NextMarker 的值做為 URI 中的標記參數,以進行後續要求。

請注意,NextMarker 的值應視為不透明。

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

delimiter 參數可讓呼叫者藉由使用者設定的分隔符號周遊 Blob 命名空間。如此一來,您便可以周遊 Blob 的虛擬階層,就像是檔案系統一般。此分隔符號可以是單一字元或字串。當要求包含此參數時,作業會傳回 BlobPrefix 項目。傳回的 BlobPrefix 項目會取代名稱開頭為相同子字串 (分隔符號字元出現之前) 的所有 Blob。BlobPrefix 元素的值為 substring+delimiter,其中 substring 是一或多個 Blob 名稱開頭共用的子字串,而 delimiterdelimiter 參數的值。

您可以使用 BlobPrefix 的值進行後續呼叫,列出開頭為此前置詞的所有 Blob,方法是在要求 URI 中,為 prefix 參數指定 BlobPrefix 的值。

請注意,每個傳回的 BlobPrefix 項目會計入最大結果數目,就像每個 Blob 項目一樣。

Blob 會按照字母順序在回應主體中列出,大寫字母先列出。

CopyStatusDescription 中的複製錯誤

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

  • 當複製嘗試失敗,而且 Blob 服務仍在重試此作業,CopyStatus 會設為 pending,而且 CopyStatusDescription 文字會描述上次複製嘗試期間發生的失敗。

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

下表說明每個 CopyStatusDescription 值的三個欄位。

 

元件 描述

HTTP 狀態碼

指定失敗的標準 3 位數整數。

錯誤碼

Azure 在 <ErrorCode> 項目中提供描述錯誤的關鍵字。如果未顯示 <ErrorCode> 項目,則會使用含有與 HTTP 規格中 3 位數 HTTP 狀態碼相關聯之標準錯誤文字的關鍵字。請參閱<常見的 REST 應用程式開發介面錯誤碼>。

資訊

失敗的詳細描述 (含引號)。

下表說明常見失敗案例的 CopyStatusCopyStatusDescription 值。

Important重要事項
此處顯示的描述文字可能不會發出警告而直接變更 (甚至未變更版本),因此請勿依賴完全相符的文字。

 

案例 CopyStatus 值 CopyStatusDescription 值

複製作業已順利完成。

成功

空白

使用者在完成前已中止複製作業。

aborted

空白

複製期間從來源 Blob 讀取時失敗,但將重試作業。

暫止

502 BadGateway「讀取來源時,發生可重試的錯誤。將重試。失敗的時間:<時間>」

寫入複製作業的目的地 Blob 發生失敗,但將重試作業。

暫止

500 InternalServerError「發生可重試的錯誤。將重試。失敗的時間:<時間>」

從複製作業的來源 Blob 在讀取時,發生無法復原的失敗。

失敗

404 ResourceNotFound「讀取來源時,複製失敗。」

note附註
報告此基本錯誤時,Azure 在 ResourceNotFoundErrorCode< 項目中傳回 >。如果回應中未顯示 <ErrorCode> 項目,則會顯示 HTTP 狀態的標準字串表示法,例如 NotFound

限制所有複製作業的逾時期限已過。(目前的逾時期限為 2 週。)

失敗

500 OperationCancelled「複製超過允許的最長時間。」

從來源讀取時,複製作業的失敗次數過於頻繁,且未達到嘗試成功的最低比率。(針對非常不良的來源,此逾時可避免超過 2 週的重試,才宣告失敗)。

失敗

500 OperationCancelled「讀取來源時,複製失敗。」

本文對您有任何幫助嗎?
(剩餘 1500 個字元)
感謝您提供意見
顯示:
© 2014 Microsoft