Blob Batch

  • Artículo

La Blob Batch operación permite insertar varias llamadas API en una única solicitud HTTP. Esta API admite dos tipos de subrequests: Establecer el nivel de blob para blobs en bloques y Eliminar blob. La respuesta devuelta por el servidor para una solicitud por lotes contiene los resultados de cada subbrequest del lote. La solicitud y respuesta por lotes usan la sintaxis de la OData especificación de procesamiento por lotes, con modificaciones en la semántica. Esta API está disponible a partir de la versión 2018-11-09.

Solicitud

Puede construir la Blob Batch solicitud como se indica a continuación. Se recomienda HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento.

Método URI de solicitud Versión de HTTP
POST https://myaccount.blob.core.windows.net/?comp=batch

https://myaccount.blob.core.windows.net/containername?restype=container&comp=batch		 HTTP/1.1

Parámetros del identificador URI

Puede especificar los siguientes parámetros adicionales en el URI de solicitud.

Parámetro Descripción
timeout Opcional. El parámetro de tiempo de espera se expresa en segundos, con un valor máximo de 120 segundos. Para más información, consulte Configuración de tiempos de espera para las operaciones de Blob Storage.
restype Opcional, versión 2020-04-08 y posteriores. El único valor admitido para el restype parámetro es container. Cuando se especifica este parámetro, el URI debe incluir el nombre del contenedor. Todos los subrequests deben tener como ámbito el mismo contenedor.

Encabezados de solicitud

En la tabla siguiente se describen los encabezados de solicitud requeridos y opcionales.

Encabezado de solicitud Descripción
Authorization Necesario. Especifica el esquema de autorización, el nombre de la cuenta de almacenamiento y la firma. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
Date o x-ms-date Necesario. Especifica la hora universal coordinada (UTC) de la solicitud. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
x-ms-version Obligatorio para todas las solicitudes autorizadas. Especifica la versión de la operación que se utiliza para esta solicitud. Esta versión se usará para todos los subrequests. Para obtener más información, vea Versiones de los servicios de Azure Storage.
Content-Length Necesario. La longitud de la solicitud.
Content-Type Necesario. El valor de este encabezado debe ser multipart/mixed, con un límite de lote. Valor de encabezado de ejemplo: multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252.
x-ms-client-request-id Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 kibibyte (KiB) que se registra en los registros cuando se configura el registro. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes que recibe el servidor. Para obtener más información, vea Supervisar Azure Blob Storage.

Cuerpo de la solicitud

El cuerpo de la solicitud de un lote de blobs contiene una lista de todos los subrequests. El formato usa la sintaxis de la OData especificación por lotes, con modificaciones en la semántica.

El cuerpo de la solicitud comienza con un límite de lote, seguido de dos encabezados obligatorios: el Content-Type encabezado con el valor application/httpy el Content-Transfer-Encoding encabezado con el valor binary. Esto va seguido de un encabezado opcional Content-ID , con un valor de cadena para realizar un seguimiento de cada uno de los subrequests. La respuesta contiene el Content-ID encabezado de cada respuesta de subrequest correspondiente que se usará para el seguimiento.

Estos encabezados de solicitud van seguidos de una línea vacía obligatoria y, a continuación, la definición de cada subbrequest. El cuerpo de cada subbrequest es una solicitud HTTP completa con un verbo, una dirección URL, encabezados y un cuerpo necesarios para la solicitud. Tenga en cuenta las siguientes advertencias:

  • Los subrequests no deben tener .x-ms-version header Todas las subrequests se ejecutan con la versión de solicitud por lotes de nivel superior.
  • La dirección URL del subrequest solo debe tener la ruta de acceso de la dirección URL (sin el host).
  • Cada solicitud por lotes admite un máximo de 256 subrequests.
  • Todos los subrequests deben ser del mismo tipo de solicitud.
  • Cada subbrequest se autoriza por separado, con la información proporcionada en la subbrequest.
  • Cada línea del cuerpo de la solicitud debe terminar con \r\n caracteres.

Solicitud de ejemplo

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

La respuesta incluye un código de estado HTTP y un conjunto de encabezados de respuesta para la solicitud por lotes de nivel superior. La respuesta también incluye información de respuesta para todos sus subrequests.

Response body

La respuesta por lotes es una multipart/mixed respuesta, que contiene la respuesta de cada subbrequest. La respuesta está fragmentada. Cada subresponse comienza con el Content-Type: application/http encabezado . El Content-ID encabezado sigue, si se proporcionó en la solicitud. Esto va seguido del código de estado de respuesta HTTP y los encabezados de respuesta para cada subbrequest.

Para obtener información sobre los encabezados devueltos por cada subbrequest, consulte la documentación de las operaciones Eliminar blob y Establecer nivel de blob .

Respuesta de muestra

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

Si la solicitud por lotes tiene un formato correcto y está autorizado, la operación devuelve el código de estado 202 (aceptado). Cada subbrequest tiene su propia respuesta, dependiendo del resultado de la operación. El estado del subrequest se devuelve en el cuerpo de la respuesta.

Para obtener más información, vea Códigos de estado y error.

Encabezados de respuesta

La respuesta para esta operación incluye los encabezados siguientes. La respuesta también puede incluir otros encabezados HTTP estándar. Todos los encabezados estándar se ajustan a la especificación del protocolo HTTP/1.1.

Authorization

Cuando restype=container se omite, debe autorizar la solicitud por lotes primaria mediante una clave compartida. Puede usar la clave de acceso de la cuenta, una firma de acceso compartido de cuenta o Azure Active Directory. Detalles de los mecanismos de autorización específicos que se muestran a continuación.

Cuando restype=container se incluye en la solicitud, puede autorizar la solicitud por lotes primaria mediante una clave compartida o Azure Active Directory. También puede autorizar con una firma de acceso compartido firmada por cualquiera de esos mecanismos de autorización. Detalles de los mecanismos de autorización específicos que se muestran a continuación.

Cada subbrequest se autoriza por separado. Una subrequest admite los mismos mecanismos de autorización que admite la operación cuando no forma parte de una operación por lotes.

Azure Storage admite el uso de Microsoft Entra ID para autorizar solicitudes a datos de blobs. Con Microsoft Entra ID, puede usar el control de acceso basado en rol de Azure (RBAC de Azure) para conceder permisos a una entidad de seguridad. La entidad de seguridad puede ser un usuario, un grupo, una entidad de servicio de aplicación o una identidad administrada de Azure. La entidad de seguridad se autentica mediante Microsoft Entra ID para devolver un token de OAuth 2.0. Después, el token se puede usar para autorizar una solicitud en Blob service.

Para más información sobre la autorización mediante Microsoft Entra ID, consulte Autorización del acceso a blobs mediante Microsoft Entra ID.

Permisos

A continuación se enumeran las acciones de RBAC necesarias para un usuario, grupo o entidad de servicio de Microsoft Entra para realizar una Blob Batch solicitud primaria y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

Para más información sobre la asignación de roles mediante RBAC de Azure, consulte Asignación de un rol de Azure para el acceso a datos de blobs.

Facturación

La Blob Batch solicitud REST se cuenta como una transacción y cada subbrequest individual también se cuenta como una transacción. Para más información sobre la facturación de los subrequestos individuales, consulte la documentación de las operaciones Eliminar blob y Establecer nivel de blob .

Las solicitudes de precios se pueden originar en clientes que usan las API de Blob Storage, ya sea directamente a través de la API rest de Blob Storage o de una biblioteca cliente de Azure Storage. Estas solicitudes acumulan cargos por transacción. El tipo de transacción afecta a cómo se cobra la cuenta. Por ejemplo, las transacciones de lectura se acumulan en una categoría de facturación diferente que las transacciones de escritura. En la tabla siguiente se muestra la categoría de facturación de una Blob Batch solicitud primaria basada en el tipo de cuenta de almacenamiento:

Operación Tipo de cuenta de almacenamiento Categoría de facturación
Lote de blobs (establecer el nivel de blob) Blobs en bloques Premium
De uso general, estándar, v2		 Otras operaciones

Para obtener información sobre los precios de la categoría de facturación especificada, consulte precios Azure Blob Storage.

Comentarios

Una de las principales ventajas de usar una solicitud por lotes es la reducción del número de conexiones que tiene que abrir un cliente. Tenga en cuenta las restricciones que se indican a continuación:

  • Los subrequests admitidos en el lote son Set Blob Tier (para blobs en bloques) y Delete Blob.
  • Solo admite hasta 256 subrequests en un solo lote. El tamaño del cuerpo de una solicitud por lotes no puede superar los 4 MB.
  • Se produce un error en una solicitud por lotes vacía con el código 400 (solicitud incorrecta).
  • No hay garantías sobre el orden de ejecución de los subrequests por lotes.
  • La ejecución de la subbrequesta por lotes no es atómica. Cada subbrequest se ejecuta de forma independiente.
  • Cada subrequest debe ser para un recurso dentro de la misma cuenta de almacenamiento. Una única solicitud por lotes no admite la ejecución de solicitudes de diferentes cuentas de almacenamiento.
  • No se admite un cuerpo de solicitud anidado.
  • Si el servidor no puede analizar el cuerpo de la solicitud, se produce un error en todo el lote y no se ejecutará ninguna solicitud.
  • Tenga en cuenta que la SAS de cuenta es el único tipo de firma de acceso compartido admitido por Blob Batch, cuando el lote no usa restype=container.

Ámbito de todos los subrequests a un contenedor específico

A partir de la versión DE REST 2020-04-08, la API admite subrequests para determinar el Blob Batch ámbito de un contenedor especificado. Cuando el URI de solicitud incluye el nombre del contenedor y el restype=container parámetro , cada subbrequest debe aplicarse al mismo contenedor. Si el nombre del contenedor especificado para una subrequest no coincide con el nombre del contenedor proporcionado en el URI, el servicio devuelve el código de error 400 (solicitud incorrecta).

Todos los mecanismos de autorización admitidos para un contenedor son válidos para una Blob Batch operación cuyo ámbito es el contenedor. Cada subbrequest envía un encabezado de autorización al servicio.

Consulte también

Autorización de solicitudes a códigos deerror y estado de Azure Storage: códigos de error de Blob Storage: configuración de tiempos de espera para las operaciones de Blob Storage