列出 Blob
本文為機器翻譯文章。如需檢視英文版,請選取 [原文] 核取方塊。您也可以將滑鼠指標移到文字上,即可在快顯視窗顯示英文原文。
譯文
原文

列出 Blob

 

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 的預留位置回應主體中的項目。 分隔符號可以是單一字元或字串。

marker

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

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

maxresults

選擇性的。 指定要傳回的 blob 最大數目,包括所有 BlobPrefix 項目。 如果要求未指定 maxresults 或指定的值大於 5000,伺服器會傳回最多 5000 個項目。

設定 maxresults 值小於或等於零會導致錯誤回應碼 400 (不正確的要求)。

include={snapshots,metadata,uncommittedblobs,copy}

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

  • snapshots:指定應該在列舉中包含快照集。 快照集從最舊到最新的回應中列出。

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

  • uncommittedblobs:指定之 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 (確定)。

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

這項作業的回應包括下列標頭。 回應也可能包括其他標準 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 回應的格式如下所示。

請注意, 前置詞, ,標記, ,MaxResults, ,和 分隔符號 項目才會出現在要求 URI 上指定。 NextMarker 項目清單結果不完整時,才會有一個值。

只有當它們所指定的回應包含未認可的 blob 和快照集,blob 中繼資料, include 要求 URI 上的參數。

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

在 2013年-08-15 版和更新版本中, EnumerationResults 項目包含 ServiceEndpoint 屬性指定的 blob 端點,以及 ContainerName 指定容器的名稱欄位。 在舊版中這兩個屬性合併在 ContainerName 欄位。 此外在 2013年-08-15 版和更新版本中, Url 項目底下 Blob 已移除。

版本 2015年-02-21 和更新版本, 列出 Blob 傳回所有類型的 blob (封鎖、 頁面和附加 blob)。

從 2009年-09-19 版本和更新版本,但之前的版本 2015年-02-21 呼叫 列出 Blob 容器,其中包含附加 blob 將會失敗,狀態碼 409 (FeatureVersionMismatch) 如果清單的結果會包含附加 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|AppendBlob</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 版及更新版本。

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 這些項目也不會出現所建立的 blob 複製 Blob 2012年-02-12 版之前。

System_CAPS_note注意事項

從 2009年-09-19 版開始 List Blobs 傳回下列重新命名為回應主體中的項目:

  • 上次修改 (先前 LastModified)

  • Content-length (先前 大小)

  • Content-type (先前 ContentType)

  • Content-encoding (先前 ContentEncoding)

  • 內容語言 (先前 ContentLanguage)

Content-md5 blob 建立,並以 2009年-09-19 版及更新版本的項目會出現。 在 2012年-02-12 版及更新版本中,Blob 服務會計算 content-md5 值,當您上傳 blob,使用 放置 Blob, ,但不會計算這當您建立 blob,使用 放置區塊清單 您可以明確設定 content-md5 值,當您建立 blob,或藉由呼叫 放置區塊清單設定 Blob 屬性 作業。

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

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

在回應中的 blob 屬性

如果您已要求在列舉中包含未認可的 blob,請注意,某些屬性才會進行設定 blob 是受到認可,因此可能不會在回應中傳回某些屬性。

X-ms-blob--序號 的分頁 blob,才會傳回項目。

分頁 blob 傳回的值在 Content-length 項目對應至 blob 的值 x-ms-blob-content-length 標頭。

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

在回應中的中繼資料

中繼資料 項目不存在才 include=metadata URI 上指定參數。中繼資料 組名稱對應的項目中列出項目,每個名稱 / 值組的值。

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

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


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

在回應中的快照集

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

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

在回應中未認可的 Blob

未認可的 blob 會列在回應才 include=uncommittedblobs URI 上指定參數。 在回應中列出的未認可的 blob 不包含任何下列項目:

  • 上次修改

  • Etag

  • 內容類型

  • 內容編碼方式

  • 內容語言

  • 內容 MD5

  • 快取控制

  • 中繼資料

使用標記值傳回的結果集

如果您指定的值 maxresults 參數和傳回的 blob 數目超過此值,或超過預設值 maxresults, ,回應主體會包含 NextMarker 元素會指出後續要求傳回的下一個 blob。 若要傳回下的一個項目集,指定的值 NextMarker 為針對後續的要求 URI 中的標記參數。

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

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

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

您可以使用的值 BlobPrefix 讓清單開頭的 blob,使用此前置詞,藉由指定的值的後續呼叫 BlobPrefixprefix 要求 URI 上的參數。

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

Blob 會在回應主體中,依字母順序列出,大寫字母先列出使用。

CopyStatusDescription 中的複製錯誤

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

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

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

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

元件

描述

HTTP 狀態碼

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

錯誤碼

描述錯誤由 Azure 提供的 < e > 項目中的關鍵字。 如果沒有 < e > 項目出現時,會使用關鍵字,其中包含與 HTTP 規格中 3 位數 HTTP 狀態碼相關聯的標準錯誤文字。 請參閱 常見的 REST 應用程式開發介面錯誤碼

資訊

詳細的描述失敗,請以引號括住。

下表描述 CopyStatusCopyStatusDescription 常見失敗案例的值。

System_CAPS_important重要事項

描述文字如下所示可以變更,而不發出警告,即使沒有版本的變更,因此請勿依賴完全相符的文字。

案例

CopyStatus 值

CopyStatusDescription 值

複製作業已順利完成。

成功

Empty

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

已中止

Empty

在複製作業時,從來源 blob 讀取時,發生錯誤,但將重試作業。

暫止

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

寫入複製作業的目的地 blob 時,發生錯誤,但將重試作業。

暫止

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

讀取來源 blob 複製作業時,就會發生無法復原失敗。

失敗

404 ResourceNotFound 「 無法讀取來源時複製 」。

System_CAPS_note注意事項

Azure 時報告此錯誤的基礎,傳回 ResourceNotFound < 錯誤碼 > 項目中。 如果沒有 < e > 項目出現在回應中,標準的字串表示的 HTTP 狀態例如 找不到 就會出現。

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

失敗

500 OperationCancelled 「 複製超過允許的時間上限。 」

複製作業失敗次數過於頻繁,從來源讀取時並沒有符合的嘗試成功的最小比率。 (這個逾時可避免超過 2 週而失敗之前重試非常不良的來源)。

失敗

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

顯示:
© 2016 Microsoft