Blob Batch

發行項
03/05/2024

此 Blob Batch 作業可讓多個 API 呼叫內嵌到單一 HTTP 要求中。此 API 支援兩種類型的子佇列：設定區塊 Blob 的 Blob 層和刪除 Blob。伺服器針對批次要求所傳回的回應包含批次中每個子查詢的結果。批次要求和回應會使用批處理規格的 OData 語法，並修改語意。從 2018-11-09 版開始，即可使用此 API。

要求

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

方法	要求 URI	HTTP 版本
`POST`	`https://myaccount.blob.core.windows.net/?comp=batch` `https://myaccount.blob.core.windows.net/containername?restype=container&comp=batch`	HTTP/1.1

URI 參數

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

參數	描述
`timeout`	選擇性。逾時參數是以秒表示，最大值為120秒。如需詳細資訊，請參閱設定 Blob 記憶體作業的逾時。
`restype`	選擇性版本 2020-04-08 和更新版本。參數唯一 `restype` 支援的值是 `container`。指定此參數時，URI 必須包含容器名稱。任何子查詢都必須限定為相同的容器。

要求標頭

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

要求標頭	描述
`Authorization`	必要。指定授權配置、記憶體帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`Date` 或 `x-ms-date`	必要。指定要求的「國際標準時間」(UTC)。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`x-ms-version`	所有已授權要求都需要。指定用於這個要求的作業版本。此版本將用於所有子查詢。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`Content-Length`	必要。要求的長度。
`Content-Type`	必要。此標頭的值必須是 `multipart/mixed`，且具有批次界限。範例標頭值： `multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252`。
`x-ms-client-request-id`	選擇性。提供客戶端產生的不透明值，其中包含設定記錄時記錄的 1 kibibyte (KiB) 字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器接收的要求相互關聯。如需詳細資訊，請參閱監視 Azure Blob 儲存體。

要求本文

Blob 批次的要求本文包含所有子查詢的清單。格式會使用批次規格的 OData 語法，並修改語意。

要求本文以批次界限開頭，後面接著兩個必要標頭： Content-Type 具有值的 application/http標頭，以及 Content-Transfer-Encoding 具有值的 binary標頭。後面接著選擇性 Content-ID 標頭，並具有字串值來追蹤每個子查詢。回應包含 Content-ID 每個對應子查詢回應的標頭，以用於追蹤。

這些要求標頭後面接著必要的空白行，然後是每個子查詢的定義。每個子查詢的本文都是完整的 HTTP 要求，其中包含要求所需的動詞、URL、標頭和本文。請注意下列注意事項：

子查詢不應該有 x-ms-version header。所有子查詢都會以最上層批次要求版本執行。
子查詢 URL 應該只有 URL 的路徑 (，而沒有主機) 。
每個批次要求最多支援 256 個子要求。
所有子查詢都必須是相同的要求類型。
每個子查詢都會分別獲得授權，以及子查詢中提供的資訊。
要求本文中的每個行都應該以 \r\n 字元結尾。

範例要求

POST http://account.blob.core.windows.net/?comp=batch HTTP/1.1 
Content-Type: multipart/mixed; boundary=batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
x-ms-version: 2018-11-09 
Authorization: SharedKey account:QvaoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI=
Host: 127.0.0.1:10000 
Content-Length: 1569 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 0 

DELETE /container0/blob0 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:G4jjBXA7LI/RnWKIOQ8i9xH4p76pAQ+4Fs4R1VxasaE= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 1 

DELETE /container1/blob1 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:IvCoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 2 

DELETE /container2/blob2 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:S37N2JTjcmOQVLHLbDmp2johz+KpTJvKhbVc4M7+UqI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525--

回應

回應包含 HTTP 狀態代碼，以及最上層批次要求的一組響應標頭。回應也包含其所有子查詢的回應資訊。

回應本文

批次回應是回應 multipart/mixed ，其中包含每個子查詢的回應。回應會分區塊化。每個子回應都是以 Content-Type: application/http 標頭開頭。如果已在要求中提供標頭，則 Content-ID 標頭會跟在後面。後面接著 HTTP 回應狀態代碼，以及每個子查詢的響應標頭。

如需每個子查詢所傳回之標頭的相關信息，請參閱刪除 Blob 和設定 Blob 層作業的檔。

範例回應

HTTP/1.1 202 Accepted 
Transfer-Encoding: chunked 
Content-Type: multipart/mixed; boundary=batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
x-ms-request-id: 778fdc83-801e-0000-62ff-033467000000 
x-ms-version: 2018-11-09 

409
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 0 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e284f 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 1 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2851 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 2 

HTTP/1.1 404 The specified blob does not exist. 
x-ms-error-code: BlobNotFound 
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2852 
x-ms-version: 2018-11-09 
Content-Length: 216 
Content-Type: application/xml 

<?xml version="1.0" encoding="utf-8"?> 
<Error><Code>BlobNotFound</Code><Message>The specified blob does not exist. 
RequestId:778fdc83-801e-0000-62ff-0334671e2852 
Time:2018-06-14T16:46:54.6040685Z</Message></Error> 
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed-- 
0

狀態碼

如果批次要求格式正確且經過授權，則作業會傳回狀態代碼 202 (已接受) 。每個子查詢都有自己的響應，視作業的結果而定。子查詢狀態會在回應本文中傳回。

如需詳細資訊，請參閱狀態和錯誤碼。

回應標頭

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

授權

省略時 restype=container ，您必須使用共用密鑰來授權父批次要求。您可以使用帳戶存取密鑰、帳戶共用存取簽章或 Azure Active Directory。特定授權機制的詳細數據，如下所示。

當 restype=container 包含在要求時，您可以透過共用密鑰或 Azure Active Directory 授權父批次要求。您也可以使用由其中一種授權機制簽署的共用存取簽章進行授權。特定授權機制的詳細數據，如下所示。

每個子查詢都會分別獲得授權。子查詢支援作業不屬於批次作業一部分時所支援的相同授權機制。

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 使用者、群組或服務主體進行Blob Batch父要求所需的 RBAC 動作，以及包含此動作的最低特殊許可權內建 Azure RBAC 角色：

Azure RBAC 動作：Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
最低特殊許可權內建角色：記憶體 Blob 數據參與者

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

(SAS) 共用存取簽章可提供記憶體帳戶中資源的安全委派存取權。透過 SAS，您可以細微控制用戶端如何存取數據。您可以指定用戶端可以存取的資源、這些資源的許可權，以及 SAS 的有效時間。

父 Blob Batch 要求支援下列案例的共用存取簽章：

省略時機restype=container：支持帳戶 SAS
要求包含時restype=container：支援使用者委派 SAS、服務 SAS 和帳戶 SAS

作為安全性最佳做法，我們建議您使用 Microsoft Entra 認證，而不是記憶體帳戶密鑰，這更容易遭到入侵。如果您的應用程式設計需要共用存取簽章，請盡可能使用 Microsoft Entra 認證來建立使用者委派 SAS。

當記憶體帳戶不允許共用密鑰存取時，對 Blob 記憶體的要求不允許服務 SAS 令牌或帳戶 SAS 令牌。若要深入瞭解，請參閱瞭解不允許共用密鑰如何影響 SAS 令牌。

使用者委派 SAS

使用者委派 SAS 受到 Microsoft Entra 認證保護，也受到為 SAS 指定的許可權。

Blob Batch使用委派給容器或 Blob 資源的 SAS 令牌的父要求需要寫入 (w) 許可權作為使用者委派 SAS 令牌的一部分。

若要深入瞭解使用者委派 SAS，請參閱建立使用者委派 SAS。

服務 SAS

服務 SAS 會使用儲存體帳戶金鑰加以保護。服務 SAS 會將存取權委派給單一 Azure 記憶體服務中的資源，例如 Blob 記憶體。

Blob Batch使用委派給容器或 Blob 資源的 SAS 令牌的父要求需要寫入 (w) 許可權作為服務 SAS 令牌的一部分。

若要深入瞭解服務 SAS，請參閱建立服務 SAS。

帳戶 SAS

帳戶 SAS 會使用儲存體帳戶金鑰加以保護。帳戶 SAS 則將存取權限委派給一或多個儲存體服務的資源。所有作業皆可透過服務 SAS 或使用者委派 SAS 取得，也可透過帳戶 SAS 取得。

下表指出委派存取權時所要指定的已簽署資源類型和已簽署許可權：

作業	已簽署的服務	已簽署的資源類型	已簽署的許可權
Blob Batch (父要求)	Blob (b)	物件 (o)	寫入 (w)

若要深入了解帳戶 SAS，請參閱建立帳戶 SAS。

計費

Blob Batch REST 要求會計算為一筆交易，而每個個別子查詢也會計算為一筆交易。若要深入瞭解個別子查詢的計費，請參閱刪除 Blob 和設定 Blob 層作業的檔。

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

作業	儲存體帳戶類型	計費類別
Blob Batch (設定 Blob 層)	進階區塊 Blob 標準一般用途 v2	其他作業

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

備註

使用批次要求的主要優點之一是客戶端必須開啟的連線數目減少。請注意下列限制：

批次中支援的子查詢會 Set Blob Tier 針對區塊 Blob) 和 Delete Blob (。
在單一批次中最多支援 256 個子查詢。批次要求的本文大小不能超過 4 MB。
空的批次要求失敗，代碼為 400 (不正確的要求) 。
批次子查詢的執行順序沒有保證。
Batch 子查詢執行不是不可部分完成的。每個子查詢都會獨立執行。
每個子查詢都必須針對相同記憶體帳戶內的資源。單一批次要求不支援從不同的記憶體帳戶執行要求。
不支援巢狀要求本文。
如果伺服器無法剖析要求本文，整個批次就會失敗，而且不會執行任何要求。
請注意，當批次未使用 restype=container時，帳戶 SAS 是唯一支援的Blob Batch共用存取簽章類型。

將所有子查詢範圍限定為特定容器

從 REST 2020-04-08 版開始， Blob Batch API 支援將子要求範圍界定為指定的容器。當要求 URI 包含容器名稱和 restype=container 參數時，每個子查詢都必須套用至相同的容器。如果針對子查詢指定的容器名稱不符合 URI 中提供的容器名稱，服務會傳回錯誤碼 400 (不正確的要求) 。

容器支援的所有授權機制對於範圍設定為容器的作業都有效 Blob Batch 。每個子要求都會將授權標頭傳送至服務。

另請參閱

授權對 Azure 記憶體狀態的要求和錯誤碼 Blob 記憶體錯誤碼設定 Blob 記憶體作業的逾時