取得 Blob

Get Blob 作業可從系統讀取或下載 Blob,包括其中繼資料和屬性。 您也可以呼叫 Get Blob 讀取快照集。

要求

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

GET 方法要求 URI HTTP 版本
https://myaccount.blob.core.windows.net/mycontainer/myblob

https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>

https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>

HTTP/1。0

HTTP/1.1

模擬儲存體服務 URI

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

GET 方法要求 URI HTTP 版本
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob HTTP/1。0

HTTP/1.1

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

URI 參數

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

參數 描述
snapshot 選擇性。 快照集參數是不透明的 DateTime 值,當其存在時,會指定要擷取的 Blob 快照集。 如需使用 blob 快照集的詳細資訊,請參閱 建立 blob 的快照集。
versionid 選擇性,版本2019-12-12 和更新版本。 Versionid 參數是不透明 DateTime 的值,當其存在時,會指定要取出的 Blob 版本。
timeout 選擇性。 timeout 參數以秒為單位。 如需詳細資訊,請參閱 設定 Blob 服務作業的超時

要求標頭

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

要求標頭 描述
Authorization 必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊,請參閱授權 Azure 儲存體的要求
Datex-ms-date 必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊,請參閱授權 Azure 儲存體的要求
x-ms-version 所有授權要求的必要參數,匿名要求為選擇性。 指定用於這個要求的作業版本。 如需詳細資訊,請參閱Azure 儲存體服務的版本控制
Range 選擇性。 僅傳回指定範圍的 Blob 位元組。
x-ms-range 選擇性。 僅傳回指定範圍的 Blob 位元組。 如果同時指定 Rangex-ms-range,服務會使用 x-ms-range 的值。 如果未指定這兩項,則會傳回整個 Blob 內容。 如需詳細資訊,請參閱 指定 Blob 服務作業的範圍標頭
x-ms-lease-id: <ID> 選擇性。 如果指定此標頭,只有同時符合下列兩個條件時,才會執行作業:

-Blob 的租用目前為使用中狀態。
-要求中指定的租用識別碼與 blob 相符。

如果指定此標頭但不符合任何一項條件,則要求和 Get Blob 作業會失敗,並顯示狀態碼 412 (先決條件失敗)。
x-ms-range-get-content-md5: true 選擇性。 當此標頭設定為 true 並與標頭一起指定時 Range ,只要範圍小於或等於 4 MiB 的大小,服務就會傳回範圍的 MD5 雜湊。

如果指定此標頭但未指定 Range 標頭,服務會傳回狀態碼 400 (不正確的要求)。

如果此標頭設定為, true 當範圍大小超過 4 MiB 時,服務會傳回狀態碼 400 (錯誤的要求) 。
x-ms-range-get-content-crc64: true 選擇性。 當此標頭設定為 true 並與標頭一起指定時 Range ,只要範圍小於或等於 4 MiB 的大小,服務就會傳回範圍的 CRC64 雜湊。

如果指定此標頭但未指定 Range 標頭,服務會傳回狀態碼 400 (不正確的要求)。

如果此標頭設定為, true 當範圍大小超過 4 MiB 時,服務會傳回狀態碼 400 (錯誤的要求) 。

如果同時 x-ms-range-get-content-md5 x-ms-range-get-content-crc64 存在和標頭,要求將會失敗,並出現 400 (錯誤的要求) 。

2019-02-02 或更新版本中支援此標頭。
Origin 選擇性。 指定發出要求的來源。 此標頭的顯示會導致在回應上跨原始資源共用 (CORS) 標頭。
x-ms-client-request-id 選擇性。 提供用戶端產生的不透明值,具有1個 KiB 字元限制,當啟用儲存體分析記錄時,記錄在分析記錄中。 強烈建議使用此標頭來將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊,請參閱關於儲存體分析記錄Azure 記錄:使用記錄檔追蹤儲存體要求

唯有在符合指定條件的情況下,此作業也可支援使用條件式標頭讀取 Blob。 如需詳細資訊,請參閱指定 Blob 服務作業的條件式標頭

要求標頭 (客戶提供的加密金鑰)

從2019-02-02 版開始,您可以在要求上指定下列標頭,以讀取以客戶提供之金鑰加密的 blob。 使用客戶提供的金鑰進行加密 (以及對應的標頭集合) 是選擇性的。 如果 blob 先前已使用客戶提供的金鑰進行加密,則必須在要求中包含這些標頭,才能順利完成讀取作業。

要求標頭 描述
x-ms-encryption-key 必要。 Base64 編碼的 AES-256 加密金鑰。
x-ms-encryption-key-sha256 選擇性。 加密金鑰的 Base64 編碼 SHA256 雜湊。
x-ms-encryption-algorithm: AES256 必要。 指定加密所使用的演算法。 此標頭的值必須是 AES256

要求本文

無。

回應

回應包括 HTTP 狀態碼、一組回應標頭,以及含有 Blob 內容的回應主體。

狀態碼

成功讀取完整 Blob 的作業會傳回狀態碼 200 OK。

成功讀取指定範圍的作業會傳回狀態碼 206 (部分內容)。

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

回應標頭

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

語法 描述
Last-Modified 上次修改 Blob 的日期/時間。 日期格式會依照 RFC 1123。

修改 Blob 的任何作業 (包括 Blob 更新的中繼資料或屬性),都會變更 Blob 上次修改的時間。
x-ms-creation-time 2017-11-09 版和更新版本。 建立 blob 的日期/時間。 日期格式會依照 RFC 1123。
x-ms-meta-name:value 與此 Blob 相關聯的名稱/值組,可做為使用者定義的中繼資料。
x-ms-tag-count 2019-12-12 版或更新版本。 如果 blob 具有任何標籤,則會傳回儲存在 blob 上的標記數目。 如果 blob 上沒有標記,則不會傳回此標頭。
Content-Length 回應主體中現有的位元組數目。
Content-Type 為 blob 指定內容類型。 預設內容類型為 application/octet-stream
Content-Range 表示當用戶端設定 Range 要求標頭以要求 Blob 子集時,所傳回的位元組範圍。
ETag ETag 包含的值可讓您依條件執行作業。 如需詳細資訊,請參閱 指定 Blob 服務作業的條件式標頭 。 如果要求版本為 2011-08-18 或更新版本,ETag 值會加上引號。
Content-MD5 如果 Blob 具有 MD5 雜湊,且此 Get Blob 作業讀取完整的 Blob,則會傳回此回應標頭,以便用戶端檢查訊息內容完整性。

在 2012-02-12 版及更新版本中,Put Blob 會設定區塊 Blob 的 MD5 雜湊值,即使 Put Blob 要求不包含 MD5 標頭亦然。

如果要求是讀取指定的範圍,且 x-ms-range-get-content-md5 設定為 true ,則只要範圍大小為小於或等於 4 MiB,要求便會傳回範圍的 MD5 雜湊。

如果上述幾組條件皆不成立,則 Content-MD5 標頭不會傳回值。

如果指定 x-ms-range-get-content-md5 但未指定 Range 標頭,服務會傳回狀態碼 400 (不正確的要求)。

如果 x-ms-range-get-content-md5 設定為, true 當範圍大小超過 4 MiB 時,服務會傳回狀態碼 400 (錯誤的要求) 。
x-ms-content-crc64 如果要求是讀取指定的範圍,且 x-ms-range-get-content-crc64 設定為 true ,則只要範圍大小為小於或等於 4 MiB,要求便會傳回範圍的 CRC64 雜湊。

如果指定 x-ms-range-get-content-crc64 但未指定 Range 標頭,服務會傳回狀態碼 400 (不正確的要求)。

如果 x-ms-range-get-content-crc64 設定為, true 當範圍大小超過 4 MiB 時,服務會傳回狀態碼 400 (錯誤的要求) 。
Content-Encoding 此標頭傳回 Content-Encoding 要求標頭中所指定的值。
Content-Language 此標頭傳回 Content-Language 要求標頭中所指定的值。
Cache-Control 如果之前已指定 Blob,則會傳回此標頭。
Content-Disposition 對 2013-08-15 及更新版本提出要求會傳回此標頭。 此標頭傳回 x-ms-blob-content-disposition 標頭中所指定的值。

Content-Disposition 回應標頭欄位會傳遞如何處理回應裝載的其他資訊,也可用來附加其他中繼資料。 例如,如果設為 attachment,它會指出使用者代理程式不該顯示回應,而要顯示具有檔案名稱而不是指定之 Blob 名稱的 [另存新檔] 對話方塊。
x-ms-blob-sequence-number 分頁 Blob 目前的序號。

區塊 blob 或附加 blob 不會傳回此標頭。
x-ms-blob-type: <BlockBlob | PageBlob | AppendBlob> 傳回 Blob 的類型。
x-ms-copy-completion-time: <datetime> 2012-02-12 版及更新版本。 上次嘗試之 Copy Blob 作業 (此 Blob 為目的地 Blob) 的完成時間。 此值可指定完成、中止或複製嘗試失敗的時間。 在下列情況下,不會顯示此標頭:暫止複製;此 Blob 從未成為 Copy Blob 作業的目的地;或完成 Copy Blob 作業之後,使用 Set Blob PropertiesPut BlobPut Block List 修改了此 Blob。
x-ms-copy-status-description: <error string> 2012-02-12 版及更新版本。 只有在 x-ms-copy-statusfailedpending 時才會出現。 針對上次嚴重或不嚴重複製的作業,描述其失敗的原因。 在下列情況下,不會顯示此標頭:此 Blob 從未成為 Copy Blob 作業的目的地;或完成 Copy Blob 作業之後,使用 Set Blob PropertiesPut BlobPut Block List 修改了此 Blob。
x-ms-copy-id: <id> 2012-02-12 版及更新版本。 上次嘗試之 Copy Blob 作業 (此 Blob 為目的地 Blob) 的字串識別碼。 在下列情況下,不會顯示此標頭:此 Blob 從未成為 Copy Blob 作業的目的地;或完成 Copy Blob 作業之後,使用 Set Blob PropertiesPut BlobPut Block List 修改了此 Blob。
x-ms-copy-progress: <bytes copied/bytes total> 2012-02-12 版及更新版本。 包含上次嘗試的 Copy Blob 作業 (此 Blob 為目的地 Blob) 之來源中複製的位元組數及位元組總計。 可顯示已複製 0 到 Content-Length 位元組之間。 在下列情況下,不會顯示此標頭:此 Blob 從未成為 Copy Blob 作業的目的地;或完成 Copy Blob 作業之後,使用 Set Blob PropertiesPut BlobPut Block List 修改了此 Blob。
x-ms-copy-source: url 2012-02-12 版及更新版本。 最多2個 KiB 長度的 URL,指定上次嘗試的作業 Copy Blob (此 blob 為目的地 blob)所使用的來源 blob 或檔案。 在下列情況下,不會顯示此標頭:此 Blob 從未成為 Copy Blob 作業的目的地;或完成 Copy Blob 作業之後,使用 Set Blob PropertiesPut BlobPut Block List 修改了此 Blob。

此標頭中傳回的 URL 包含來源 blob 的複製作業中所使用的任何要求參數,包括用來存取來源 blob 的 SAS 權杖。
x-ms-copy-status: <pending | success | aborted | failed> 2012-02-12 版及更新版本。 由 x-ms-copy-id 識別之複製作業的狀態,其值如下:

- success:複製已順利完成。
- pending:複製進行中。 檢查 x-ms-copy-status-description 是否有間歇性、不嚴重的錯誤減緩複製進度,但未造成失敗。
- aborted:已結束複製 Abort Copy Blob
- failed:複製失敗。 請參閱 x-ms-copy-status-description,以取得失敗的詳細資料。

在下列情況下,不會顯示此標頭:此 Blob 從未成為 Copy Blob 作業的目的地;或完成 Copy Blob 作業之後,使用 Set Blob PropertiesPut BlobPut Block List 修改了此 Blob。
x-ms-lease-duration: <infinite | fixed> 2012-02-12 版及更新版本。 租用 Blob 時,指定租用期為無限或固定時間。
x-ms-lease-state: <available | leased | expired | breaking | broken> 2012-02-12 版及更新版本。 Blob 的租用狀態。
x-ms-lease-status:<locked | unlocked> Blob 的目前租用狀態。
x-ms-request-id 此標頭可唯一識別提出的要求,而且可用來進行要求的疑難排解。 如需詳細資訊,請參閱 疑難排解 API 作業
x-ms-version 指出用於執行要求的 Blob 服務版本。 使用 2009/9/19 版及更新版本提出的要求會包含此項。

如果容器使用 2009-09-19 版的 Blob 服務標示公開存取,也會針對未指定版本的匿名要求傳回此標頭。
Accept-Ranges: bytes 表示服務支援部分 Blob 內容的要求。 使用 2011-08-18 版及更新版本提出的要求,以及 SDK 1.6 版或更新版本中的本機儲存體服務會包含此項。
Date 服務產生的 UTC 日期/時間值,可指出啟動回應的時間。
Access-Control-Allow-Origin 如果要求包含 Origin 標頭,並啟用 CORS 及比對規則,則傳回此標頭。 此標頭會在相符時傳回原始要求標頭的值。
Access-Control-Expose-Headers 如果要求包含 Origin 標頭,並啟用 CORS 及比對規則,則傳回此標頭。 傳回向要求的用戶端或簽發者公開的回應標頭清單。
Vary 指定 CORS 規則時,會傳回此標頭及 Origin 標頭值。 如需詳細資訊,請參閱儲存體服務的 CORS 支援
Access-Control-Allow-Credentials 如果要求包含 Origin 標頭,並啟用 CORS 及不允許所有來源的比對規則,則傳回此標頭。 這個標頭會設定為 true。
x-ms-blob-committed-block-count 存在於 blob 中的認可區塊數目。 只有附加 blob 才會傳回此標頭。
x-ms-server-encrypted: true/false 2015-12-11 版或更新版本。 true如果 blob 資料和應用程式中繼資料使用指定的演算法完全加密,此標頭的值會設定為。 否則, false 當 blob 未加密,或只有部分 blob/應用程式中繼資料) 加密時,此值會設定為 (。
x-ms-encryption-key-sha256 2019-02-02 版或更新版本。 如果 blob 是使用客戶提供的金鑰來加密,則會傳回此標頭。
x-ms-encryption-scope 2019-02-02 版或更新版本。 如果 blob 是以加密範圍加密,就會傳回此標頭。
x-ms-blob-content-md5 從2016-05-31 版開始,如果 blob 具有 MD5 雜湊,而且如果要求包含範圍標頭 (範圍或 x 毫秒範圍) ,此回應標頭會以整個 blob 的 MD5 值的值傳回。 此值不一定等於在 Content-type-MD5 標頭中傳回的值,後者則是從要求的範圍計算。
x-ms-client-request-id 此標頭可用於疑難排解要求和對應的回應。 x-ms-client-request-id如果要求中有標頭的值,且值最多1024個可見的 ASCII 字元,則此標頭的值會等於標頭的值。 如果 x-ms-client-request-id 標頭不存在於要求中,則回應中不會出現此標頭。
x-ms-last-access-time 2020-02-10 版或更新版本。 指出上次存取 blob 資料的時間,是根據儲存體帳戶的上次存取時間追蹤原則。 如果儲存體帳戶沒有上次存取時間追蹤原則,或已停用此原則,則不會傳回此標頭。 如需有關設定儲存體帳戶的上次存取時間追蹤原則的詳細資訊,請參閱 Blob 服務 API
x-ms-blob-sealed 版本2019-12-12 或更新版本,只會針對附加 blob 傳回。 如果附加 blob 已密封,則值會是 true,請參閱 密封附加 blob
x-ms-immutability-policy-until-date 2020-06-12 版或更新版本。 指定 blob 上的「保留到」日期集。 這是可保護 blob 不受修改或刪除的日期。 只有在 blob 上設定了永久性原則時才會傳回。 此標頭的值為 RFC1123 格式。
x-ms-immutability-policy-mode: unlocked/locked 2020-06-12 版或更新版本。 如果在 blob 上設定了永久性原則,則會傳回永久性原則模式。 值為 unlocked / lockedunlocked 指出使用者可以藉由增加或減少保留期限,來變更原則。 locked 表示禁止這些動作。
x-ms-legal-hold: true/false 2020-06-12 版或更新版本。 如果 blob 沒有合法保存,則不會傳回此標頭。 如果 blob 包含合法保存,且其值為 true,則此標頭的值會設定為 true。 否則,如果 blob 包含合法保存且其值為 false,則此值會設為 false。
x-ms-owner 只有已啟用階層命名空間的帳戶版本2020-06-12 或更新版本。 傳回檔案或目錄的擁有者使用者。
x-ms-group 只有已啟用階層命名空間的帳戶版本2020-06-12 或更新版本。 傳回檔案或目錄的擁有群組。
x-ms-permissions 只有已啟用階層命名空間的帳戶版本2020-06-12 或更新版本。 傳回檔案或目錄上 ' user '、' group ' 和 ' other ' 的許可權集合。 每個個別許可權都是 [r,w,x,-] {3} 格式。
x-ms-resource-type 只有已啟用階層命名空間的帳戶版本2020-10-02 或更新版本。 傳回路徑的資源類型,可以是 file / directory

回應本文

回應主體包含 Blob 的內容。

範例回應

Status Response:  
HTTP/1.1 200 OK  
  
Response Headers:  
x-ms-blob-type: BlockBlob  
x-ms-lease-status: unlocked  
x-ms-lease-state: available  
x-ms-meta-m1: v1  
x-ms-meta-m2: v2  
Content-Length: 11  
Content-Type: text/plain; charset=UTF-8  
Date: <date>  
ETag: "0x8CB171DBEAD6A6B"  
Vary: Origin  
Last-Modified: <date>  
x-ms-version: 2015-02-21  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-copy-id: 36650d67-05c9-4a24-9a7d-a2213e53caf6  
x-ms-copy-source: <url>  
x-ms-copy-status: success  
x-ms-copy-progress: 11/11  
x-ms-copy-completion-time: <date>  
  

授權

如果將容器的存取控制清單 (ACL) 設為允許匿名存取 Blob,任何用戶端都可以呼叫這項作業。 若為私人容器,只有帳戶擁有者及任何使用共用存取簽章並有權讀取 Blob 的人,才能執行這項作業。

備註

若為分頁 Blob,對尚無內容或已遭到清除的頁面範圍執行 Get Blob 作業,會傳回零位元組。

如果對未指定範圍的分頁 Blob 呼叫 Get Blob,服務會傳回 x-ms-blob-content-length 標頭所指定之值以前的頁面範圍。 針對缺少內容的任何頁面,服務會傳回零位元組。

針對附加 blob,作業會傳回 Get Blob x-ms-blob-committed-block-count 標頭。 此標頭會指出 blob 中認可的區塊數目。 x-ms-blob-committed-block-count區塊 blob 或分頁 blob 的標頭不會傳回。

Get Blob每個 MiB 可以有2分鐘的時間來完成操作。 如果作業平均每個 MiB 花費的時間超過2分鐘,則作業將會超時。

擷取屬於私人容器的 Blob 時,需要 x-ms-version 標頭。 如果 Blob 屬於可完全或部分公開存取的容器,任何用戶端都可以讀取 Blob,而不需要指定版本,擷取屬於公開容器的 Blob 時,不需要服務版本。 如需詳細資訊,請參閱 限制對容器和 Blob 的存取

封存 Get Blob 區塊 blob 上的會失敗。

複製作業

若要判斷 Copy Blob 作業是否已經完成,請先檢查目的地 Blob 的 x-ms-copy-id 標頭值是否符合 Copy Blob 的原始呼叫所提供的複製識別碼。 如果相符,則可確保其他應用程式不會中止複製並啟動新的 Copy Blob 作業。 然後檢查 x-ms-copy-status: success 標頭。 但是請注意,除了 LeasePut PagePut Block 作業之外,所有寫入 Blob 的作業都會從 Blob 中移除所有 x-ms-copy-* 屬性。 使用 2012-02-12 之前版本的 Copy Blob 作業也不會複製這些屬性。

警告

標頭中傳回的 URL x-ms-copy-source 包含在來源 blob 的複製作業中使用的任何要求參數。 如果使用 SAS 權杖來存取來源 blob,則在 x-ms-copy-source Get Blob 目的地 blob 上呼叫時,該 sas 權杖將會出現在標頭中。

當回應中出現 x-ms-copy-status: failed 時,x-ms-copy-status-description 包含 Copy Blob 失敗的詳細資訊。

下表說明每個 x-ms-copy-status-description 值的三個欄位。

元件 描述
HTTP 狀態碼 指定失敗的標準 3 位數整數。
錯誤碼 關鍵字,描述 Azure 在 <ErrorCode 元素中提供的錯誤 > 。 如果未出現任何 <ErrorCode > 元素,則會使用包含與 HTTP 規格中3位數 HTTP 狀態碼相關聯之標準錯誤文字的關鍵字。 請參閱 常見的 REST API 錯誤碼
資訊 失敗的詳細描述 (含引號)。

下表說明常見失敗案例的 x-ms-copy-statusx-ms-copy-status-description 值。

重要

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

案例 x-ms-copy-status 值 x-ms-copy-status-description 值
複製作業已順利完成。 成功 empty
使用者在完成前已中止複製作業。 aborted empty
複製期間從來源 Blob 讀取時失敗,但將重試作業。 暫止 502 BadGateway「讀取來源時,發生可重試的錯誤。 將重試。 失敗 > 的時間: <時間」
寫入複製作業的目的地 Blob 發生失敗,但將重試作業。 暫止 500 InternalServerError「發生可重試的錯誤。 將重試。 失敗 > 的時間: <時間」
從複製作業的來源 Blob 在讀取時,發生無法復原的失敗。 失敗 404 ResourceNotFound「讀取來源時,複製失敗。」

注意: 回報此基礎錯誤時,Azure 會 ResourceNotFound 在元素中傳回 ErrorCode 。 如果回應中未 ErrorCode 出現任何元素,則會顯示 HTTP 狀態的標準字串標記法,例如 NotFound
限制所有複製作業的逾時期限已過。 (目前的逾時期限為 2 週。) 失敗 500 OperationCancelled「複製超過允許的最長時間。」
從來源讀取時,複製作業的失敗次數過於頻繁,且未達到嘗試成功的最低比率。 (針對非常不良的來源,此逾時可避免超過 2 週的重試,才宣告失敗)。 失敗 500 OperationCancelled「讀取來源時,複製失敗。」

x-ms-last-access-time 追蹤依據儲存體帳戶的上次存取時間追蹤原則存取 blob 資料的時間。 存取 blob 的中繼資料並不會變更其上次存取時間。

另請參閱

授權 Azure 儲存體的要求
狀態和錯誤碼
Blob 服務錯誤碼
設定 Blob 服務作業的逾時值