Blob Batch

Article
11/28/2023

The Blob Batch operation allows multiple API calls to be embedded into a single HTTP request. This API supports two types of subrequests: Set Blob Tier for block blobs and Delete Blob. The response returned by the server for a batch request contains the results for each subrequest in the batch. The batch request and response uses the syntax of the OData batch processing specification, with modifications to semantics. This API is available starting in version 2018-11-09.

Request

You can construct the Blob Batch request as follows. HTTPS is recommended. Replace myaccount with the name of your storage account.

Method	Request URI	HTTP version
`POST`	`https://myaccount.blob.core.windows.net/?comp=batch` `https://myaccount.blob.core.windows.net/containername?restype=container&comp=batch`	HTTP/1.1

URI parameters

You can specify the following additional parameters on the request URI.

Parameter	Description
`timeout`	Optional. The timeout parameter is expressed in seconds, with a maximum value of 120 seconds. For more information, see Setting timeouts for Blob Storage operations.
`restype`	Optional, version 2020-04-08 and later. The only value supported for the `restype` parameter is `container`. When this parameter is specified, the URI must include the container name. Any subrequests must be scoped to the same container.

Request headers

The following table describes required and optional request headers.

Request header	Description
`Authorization`	Required. Specifies the authorization scheme, storage account name, and signature. For more information, see Authorize requests to Azure Storage.
`Date` or `x-ms-date`	Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.
`x-ms-version`	Required for all authorized requests. Specifies the version of the operation to use for this request. This version will be used for all subrequests. For more information, see Versioning for the Azure Storage services.
`Content-Length`	Required. The length of the request.
`Content-Type`	Required. The value of this header must be `multipart/mixed`, with a batch boundary. Example header value: `multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252`.
`x-ms-client-request-id`	Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Blob Storage.

Request body

The request body for a blob batch contains a list of all subrequests. The format uses the syntax of the OData batch specification, with modifications to semantics.

The request body starts with a batch boundary, followed by two mandatory headers: the Content-Type header with the value application/http, and the Content-Transfer-Encoding header with the value binary. This is followed by an optional Content-ID header, with a string value to track each of the subrequests. The response contains the Content-ID header for each corresponding subrequest response to use for tracking.

These request headers are followed by a mandatory empty line, and then the definition for each subrequest. The body of each subrequest is a complete HTTP request with a verb, URL, headers, and body needed for the request. Note the following caveats:

The subrequests should not have the x-ms-version header. All subrequests are run with the top-level batch request version.
The subrequest URL should only have the path of the URL (without the host).
Each batch request supports a maximum of 256 subrequests.
All subrequests must be of the same request type.
Each subrequest is authorized separately, with the provided information in the subrequest.
Each line in the request body should end with \r\n characters.

Sample request

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--

Response

The response includes an HTTP status code and a set of response headers for the top level batch request. The response also includes response information for all of its subrequests.

Response body

The batch response is a multipart/mixed response, which contains the response for each subrequest. The response is chunked. Each subresponse starts with the Content-Type: application/http header. The Content-ID header follows, if it was provided in the request. This is followed by the HTTP response status code, and response headers for each subrequest.

For information about the headers returned by each subrequest, see the documentation for the Delete Blob and Set Blob Tier operations.

Sample response

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

Status code

If the batch request is well-formed and authorized, then the operation returns status code 202 (Accepted). Each subrequest has its own response, depending on the outcome of the operation. The subrequest status is returned in the response body.

For more information, see Status and error codes.

Response headers

The response for this operation includes the following headers. The response can also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Authorization

When restype=container is omitted, you must authorize the parent batch request by using a shared key. You can use the account access key, an account shared access signature, or Azure Active Directory. Details for specific authorization mechanisms shown below.

When restype=container is included on the request, you can authorize the parent batch request through a shared key or Azure Active Directory. You can also authorize with a shared access signature that is signed by either of those authorization mechanisms. Details for specific authorization mechanisms shown below.

Each subrequest is authorized separately. A subrequest supports the same authorization mechanisms that the operation supports when it isn't part of a batch operation.

Azure Storage supports using Microsoft Entra ID to authorize requests to blob data. With Microsoft Entra ID, you can use Azure role-based access control (Azure RBAC) to grant permissions to a security principal. The security principal may be a user, group, application service principal, or Azure managed identity. The security principal is authenticated by Microsoft Entra ID to return an OAuth 2.0 token. The token can then be used to authorize a request against the Blob service.

To learn more about authorization using Microsoft Entra ID, see Authorize access to blobs using Microsoft Entra ID.

Permissions

Listed below are the RBAC action necessary for a Microsoft Entra user, group, or service principal to make a Blob Batch parent request, and the least privileged built-in Azure RBAC role that includes this action:

Azure RBAC action: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Least privileged built-in role: Storage Blob Data Contributor

To learn more about assigning roles using Azure RBAC, see Assign an Azure role for access to blob data.

A shared access signature (SAS) provides secure delegated access to resources in a storage account. With a SAS, you have granular control over how a client can access data. You can specify what resource the client may access, what permissions they have to those resources, and how long the SAS is valid.

The Blob Batch parent request supports shared access signatures for the following scenarios:

When restype=container is omitted: Account SAS is supported
When restype=container is included on the request: User delegation SAS, service SAS, and account SAS are supported

As a security best practice, we recommend that you use Microsoft Entra credentials rather than the storage account key, which can be more easily compromised. If your application design requires shared access signatures, use Microsoft Entra credentials to create a user delegation SAS, when possible.

When Shared Key access is disallowed for the storage account, a service SAS token or an account SAS token will not be permitted on a request to Blob Storage. To learn more, see Understand how disallowing Shared Key affects SAS tokens.

User delegation SAS

A user delegation SAS is secured with Microsoft Entra credentials and also by the permissions specified for the SAS.

A Blob Batch parent request using a SAS token delegated to a container or blob resource requires the Write (w) permission as part of the user delegation SAS token.

To learn more about the user delegation SAS, see Create a user delegation SAS.

Service SAS

A service SAS is secured with the storage account key. A service SAS delegates access to a resource in a single Azure Storage service, such as blob storage.

A Blob Batch parent request using a SAS token delegated to a container or blob resource requires the Write (w) permission as part of the service SAS token.

To learn more about the service SAS, see Create a service SAS.

Account SAS

An account SAS is secured with the storage account key. An account SAS delegates access to resources in one or more of the storage services. All of the operations available via a service or user delegation SAS are also available via an account SAS.

The following table indicates the signed resource type and signed permissions to specify when delegating access:

Operation	Signed service	Signed resource type	Signed permission
Blob Batch (parent request)	Blob (b)	Object (o)	Write (w)

To learn more about the account SAS, see Create an account SAS.

Billing

The Blob Batch REST request is counted as one transaction, and each individual subrequest is also counted as one transaction. To learn more about billing for the individual subrequests, see the documentation for the Delete Blob and Set Blob Tier operations.

Pricing requests can originate from clients that use Blob Storage APIs, either directly through the Blob Storage REST API, or from an Azure Storage client library. These requests accrue charges per transaction. The type of transaction affects how the account is charged. For example, read transactions accrue to a different billing category than write transactions. The following table shows the billing category for a Blob Batch parent request based on the storage account type:

Operation	Storage account type	Billing category
Blob Batch (Set Blob Tier)	Premium block blob Standard general-purpose v2	Other operations

To learn about pricing for the specified billing category, see Azure Blob Storage Pricing.

Remarks

One of the main benefits of using a batch request is the reduction in the number of connections a client has to open. Note the following restrictions:

Supported subrequests in the batch are Set Blob Tier (for block blobs) and Delete Blob.
Only supports up to 256 subrequests in a single batch. The size of the body for a batch request can't exceed 4 MB.
An empty batch request fails with code 400 (Bad Request).
There are no guarantees on the order of execution of the batch subrequests.
Batch subrequest execution isn't atomic. Each subrequest runs independently.
Each subrequest must be for a resource within the same storage account. A single batch request doesn't support running requests from different storage accounts.
A nested request body isn't supported.
If the server fails to parse the request body, the entire batch fails, and no request will be run.
Note that Account SAS is the only shared access signature type supported by Blob Batch, when the batch isn't using restype=container.

Scope all subrequests to a specific container

Beginning with REST version 2020-04-08, the Blob Batch API supports scoping subrequests to a specified container. When the request URI includes the container name and the restype=container parameter, then each subrequest must apply to the same container. If the container name specified for a subrequest doesn't match the container name provided in URI, the service returns error code 400 (Bad Request).

All authorization mechanisms supported for a container are valid for a Blob Batch operation that is scoped to the container. Each subrequest sends an authorization header to the service.