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.
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|
You can specify the following additional parameters on the request URI.
||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.|
||Optional, version 2020-04-08 and later. The only value supported for the
The following table describes required and optional request headers.
||Required. Specifies the authorization scheme, storage account name, and signature. For more information, see Authorize requests to Azure Storage.|
||Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.|
||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.|
||Required. The length of the request.|
||Required. The value of this header must be
||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.|
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.
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--
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.
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.
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
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.
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.
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.
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.
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.
The batch REST request is counted as one transaction, and each individual subrequest is also counted as one transaction.
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
Set Blob Tiersubrequest in the batch is not yet supported for accounts that have a hierarchical namespace.
- 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
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.
Authorize requests to Azure Storage Status and error codes Blob Storage error codes Setting timeouts for Blob Storage operations