Append Block

  • Artículo

La Append Block operación confirma un nuevo bloque de datos al final de un blob en anexos existente.

La Append Block operación solo se permite si el blob se creó con x-ms-blob-type establecido en AppendBlob. Append Block solo se admite en la versión 2015-02-21 o posterior.

Solicitud

Puede construir la solicitud de la Append Block siguiente manera. Se recomienda HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento.

URI de solicitud de método PUT Versión de HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock HTTP/1.1

Cuando realice una solicitud en el servicio de almacenamiento emulado, especifique el nombre de host del emulador y Azure Blob Storage puerto como 127.0.0.1:10000, seguido del nombre de la cuenta de almacenamiento emulada.

URI de solicitud de método PUT Versión de HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock HTTP/1.1

Para más información, consulte Uso del emulador de Azurite para desarrollo y pruebas locales de Azure Storage.

Parámetros del identificador URI

Parámetro Descripción
timeout Opcional. El parámetro timeout se expresa en segundos. Para obtener más información, consulte Configuración de tiempos de espera para Azure Blob Storage operaciones.

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 cuenta y la firma. Consulte Autorización de solicitudes a Azure Storage para más información.
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 Necesario para todas las solicitudes autorizadas. Especifica la versión de la operación que se utiliza para esta solicitud. Para obtener más información, vea Versiones de los servicios de Azure Storage.
Content-Length Necesario. La longitud del contenido del bloque, en bytes. El tamaño del bloque debe ser menor o igual que 100 MiB (versión preliminar) en tamaño para la versión 2022-11-02 y posteriores. Consulte la sección Comentarios para ver los límites en versiones anteriores.

Si no se proporciona la longitud, la operación producirá un error con el código de estado 411 (Longitud necesaria).
Content-MD5 Opcional. Hash MD5 del contenido del bloque. Este hash se utiliza para comprobar la integridad del bloque durante el transporte. Cuando se especifica este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado con este valor de encabezado.

Tenga en cuenta que este hash MD5 no se almacena con el blob.

Si los dos hash no coinciden, se producirá un error en la operación con el código de error 400 (solicitud incorrecta).
x-ms-content-crc64 Opcional. Hash CRC64 del contenido del bloque append. Este hash se usa para comprobar la integridad del bloque append durante el transporte. Cuando se especifica este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado con este valor de encabezado.

Tenga en cuenta que este hash CRC64 no se almacena con el blob.

Si los dos hash no coinciden, se producirá un error en la operación con el código de error 400 (solicitud incorrecta).

Si los encabezados y están Content-MD5x-ms-content-crc64 presentes, se producirá un error en la solicitud con el código de error 400.

Este encabezado es compatible con las versiones 2019-02-02 o posteriores.
x-ms-encryption-scope Opcional. Indica el ámbito de cifrado que se va a usar para cifrar el contenido de la solicitud. Este encabezado es compatible con las versiones 2019-02-02 o posteriores.
x-ms-lease-id:<ID> Obligatorio si el blob tiene una concesión activa. Para realizar esta operación en un blob con una concesión activa, especifique el identificador de concesión válido de este encabezado.
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, consulte Supervisión de Azure Blob Storage.
x-ms-blob-condition-maxsize Encabezado condicional opcional. Especifica la longitud máxima en bytes permitida para el blob en anexos. Si la Append Block operación hace que el blob supere ese límite o si el tamaño del blob ya es mayor que el valor especificado en este encabezado, se produce un error en la solicitud con el código de error 412 (error de condición previa).
x-ms-blob-condition-appendpos Encabezado condicional opcional, que solo se usa para la Append Block operación. Un número indica el desplazamiento de bytes que se va a comparar. Append Block solo se realiza correctamente si la posición de anexión es igual a este número. Si no es así, se produce un error en la solicitud con el código de error 412 (error de condición previa).

Esta operación admite el uso de encabezados condicionales adicionales para asegurarse de que la API se realiza correctamente solo si se cumple una condición especificada. Para obtener más información, consulte Especificación de encabezados condicionales para Azure Blob Storage operaciones.

Encabezados de solicitud (claves de cifrado proporcionadas por el cliente)

A partir de la versión 2019-02-02, puede especificar los siguientes encabezados en la solicitud para cifrar un blob con una clave proporcionada por el cliente. El cifrado con una clave proporcionada por el cliente (y el conjunto de encabezados correspondiente) es opcional.

Encabezado de solicitud Descripción
x-ms-encryption-key Necesario. La clave de cifrado AES-256 codificada en Base64.
x-ms-encryption-key-sha256 Necesario. Hash SHA256 codificado en Base64 de la clave de cifrado.
x-ms-encryption-algorithm: AES256 Necesario. Especifica el algoritmo que se va a usar para el cifrado. El valor de este encabezado debe ser AES256.

Cuerpo de la solicitud

El cuerpo de la solicitud incluye el contenido del bloque.

Solicitud de ejemplo

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048  
If-Match: "0x8CB172A360EC34B"

Response

La respuesta incluye un código de estado HTTP y un conjunto de encabezados de respuesta.

status code

Una operación correcta devuelve el código de estado 201 (Creado).

Para obtener información sobre los códigos de estado, consulte 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.

Encabezado de respuesta Descripción
ETag ETag contiene un valor entre comillas. El cliente puede usar el valor para realizar operaciones condicionales PUT mediante el encabezado de If-Match solicitud.
Last-Modified Fecha y la hora en que se modificó por última vez el blob. El formato de la fecha sigue las convenciones de RFC 1123. Para obtener más información, vea Representación de valores de fecha y hora en encabezados.

Cualquier operación de escritura en el blob (incluidas las actualizaciones de los metadatos o propiedades del blob) cambia la hora de la última modificación del blob.
Content-MD5 Este encabezado se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. Blob Storage calcula el valor de este encabezado. No es necesariamente el mismo valor especificado en los encabezados de solicitud. Para las versiones 2019-02-02 o posteriores, este encabezado solo se devuelve cuando la solicitud tiene este encabezado.
x-ms-content-crc64 Para las versiones 2019-02-02 o posteriores, este encabezado se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. Blob Storage calcula el valor de este encabezado. No es necesariamente el mismo valor especificado en los encabezados de solicitud.

Este encabezado se devuelve cuando el Content-md5 encabezado no está presente en la solicitud.
x-ms-request-id Este encabezado identifica de forma única la solicitud que se realizó y se puede usar para solucionar problemas de la solicitud.
x-ms-version Indica la versión de Blob Storage usada para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas en la versión 2009-09-19 y versiones posteriores.
Date Valor de fecha y hora UTC que indica la hora a la que se inició la respuesta. El servicio genera este valor.
x-ms-blob-append-offset Este encabezado de respuesta solo se devuelve para las operaciones anexadas. Devuelve el desplazamiento en el que se confirmó el bloque, en bytes.
x-ms-blob-committed-block-count Número de bloques confirmados presentes en el blob. Puede usarlo para controlar el número de anexos que se pueden hacer.
x-ms-request-server-encrypted: true/false Versión 2015-12-11 o posterior. El valor de este encabezado se establece true en si el contenido de la solicitud se cifra correctamente mediante el algoritmo especificado. De lo contrario, el valor se establece en false.
x-ms-encryption-key-sha256 Versión 2019-02-02 o posterior. Este encabezado se devuelve si la solicitud usó una clave proporcionada por el cliente para el cifrado. Después, el cliente puede asegurarse de que el contenido de la solicitud se cifre correctamente mediante la clave proporcionada.
x-ms-encryption-scope Versión 2019-02-02 o posterior. Este encabezado se devuelve si la solicitud usó un ámbito de cifrado. Después, el cliente puede asegurarse de que el contenido de la solicitud se cifre correctamente mediante el ámbito de cifrado.
x-ms-client-request-id Puede usar este encabezado para solucionar problemas de solicitudes y respuestas correspondientes. El valor de este encabezado es igual al valor del x-ms-client-request-id encabezado si está presente en la solicitud. El valor es como máximo 1024 caracteres ASCII visibles. Si el x-ms-client-request-id encabezado no está presente en la solicitud, este encabezado no está presente en la respuesta.

Respuesta de muestra

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000

Authorization

Se requiere autorización al llamar a cualquier operación de acceso a datos en Azure Storage. Puede autorizar la Append Block operación como se describe a continuación.

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 llamar a la Append Block operación 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.

Comentarios

Append Block carga un bloque al final de un blob en anexos existente. El bloque de datos está disponible inmediatamente después de que la llamada se realice correctamente en el servidor. Se permite un máximo de 50 000 anexos para cada blob en anexos. Cada bloque puede tener un tamaño diferente.

En la tabla siguiente se describen los tamaños máximos permitidos de bloques y blobs, por versión del servicio:

Versión del servicio Tamaño máximo de bloque (a través de Append Block) Tamaño máximo del blob
Versión 2022-11-02 y posteriores 100 MiB (versión preliminar) Aproximadamente 4,75 TiB (100 MiB × 50 000 bloques)
Versiones anteriores a 2022-11-02 4 MiB Aproximadamente 195 gibibytes (GiB) (4 MiB × 50 000 bloques)

Append Block solo se realiza correctamente si el blob ya existe.

Los blobs cargados mediante Append Block no exponen identificadores de bloque. No se puede llamar a Get Block List en un blob en anexos. Si lo hace, se producirá un error.

Puede especificar los siguientes encabezados condicionales opcionales en la solicitud:

  • x-ms-blob-condition-appendpos: puede establecer este encabezado en un desplazamiento de bytes en el que el cliente espera anexar el bloque. La solicitud solo se realiza correctamente si el desplazamiento actual coincide con el especificado por el cliente. De lo contrario, se produce un error en la solicitud con el código de error 412 (error en la condición previa).

    Los clientes que usan un único escritor pueden usar este encabezado para determinar si una Append Block operación se realizó correctamente, a pesar de un error de red.

  • x-ms-blob-condition-maxsize: los clientes pueden usar este encabezado para asegurarse de que las operaciones de anexión no aumentan el tamaño del blob más allá de un tamaño máximo esperado en bytes. Si se produce un error en la condición, se produce un error en la solicitud con el código de error 412 (error en la condición previa).

Si intenta cargar un bloque mayor que el tamaño permitido, el servicio devuelve el código de error 413 (Solicitar entidad demasiado grande). El servicio Blob también devuelve información adicional sobre el error en la respuesta, incluyendo el tamaño máximo de bloque permitido en bytes. Si intenta cargar más de 50 000 bloques, el servicio devuelve el código de error 409 (Conflicto).

Si el blob tiene una concesión activa, el cliente debe especificar un identificador de concesión válido en la solicitud para poder escribir un bloque en el blob. Si el cliente no especifica un identificador de concesión o especifica un identificador de concesión no válido, Blob Storage devuelve el código de error 412 (error de condición previa). Si el cliente especifica un identificador de concesión, pero el blob no tiene una concesión activa, Blob Storage también devuelve el código de error 412.

Si llama a Append Block en un blob en bloques o blob en páginas existente, el servicio devuelve un error de conflicto. Si llama a Append Block en un blob inexistente, el servicio también devuelve un error.

Evitar anexos duplicados o retrasados

En un único escenario de escritura, el cliente puede evitar anexaciones duplicadas o escrituras retrasadas mediante el *x-ms-blob-condition-appendpos encabezado condicional para comprobar el desplazamiento actual. El cliente también puede evitar duplicados o retrasos comprobando condicionalmente ETag mediante If-Match.

En un escenario de escritor múltiple, cada cliente puede usar encabezados condicionales, pero esto podría no ser óptimo para el rendimiento. Para obtener el mayor rendimiento simultáneo de anexión, las aplicaciones deben controlar los anexos redundantes y los anexos retrasados en el nivel de aplicación. Por ejemplo, la aplicación puede agregar épocas o números de secuencia en los datos que se están anexando.

Facturación

Las solicitudes de precios pueden originarse en clientes que usan API de Blob Storage, ya sea directamente a través de la API REST de Blob Storage o desde 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 a las transacciones de escritura. En la tabla siguiente se muestra la categoría de facturación de Append Block las solicitudes basadas en el tipo de cuenta de almacenamiento:

Operación Tipo de cuenta de almacenamiento Categoría de facturación
Append Block Blobs en bloques Premium
De uso general, estándar, v2
De uso general, estándar, v1		 Operaciones de escritura

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