Append Block From URL

Artículo
02/03/2024

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

La Append Block From URL operación solo se permite si el blob se creó con x-ms-blob-type establecido en AppendBlob. Append Block From URL solo se admite en la versión 2018-11-09 o posterior.

Solicitud

Puede construir la Append Block From URL solicitud como se indica a continuación. 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 de tiempo de espera se expresa en segundos. Para más información, consulte Configuración de tiempos de espera para las operaciones de Blob Storage.

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 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`	Obligatorio 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. Especifica el número de bytes que se transmiten en el cuerpo de la solicitud. El valor de este encabezado debe establecerse en cero. Cuando la longitud no es cero, se producirá un error en la operación con el código de error 400 (solicitud incorrecta).
`x-ms-copy-source:name`	Necesario. Especifica la dirección URL del blob de origen. El valor puede ser una dirección URL de hasta 2 KiB de longitud que especifica un blob. El valor debe estar codificado con dirección URL, como aparecería en un URI de solicitud. El blob de origen debe ser público o debe estar autorizado a través de una firma de acceso compartido. Si el blob de origen es público, no se requiere ninguna autorización para realizar la operación. Estos son algunos ejemplos de direcciones URL de objeto de origen: `https://myaccount.blob.core.windows.net/mycontainer/myblob` `https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>`
`x-ms-copy-source-authorization: <scheme> <signature>`	Opcional. Especifica el esquema de autorización y la firma para el origen de copia. Para obtener más información, vea Autorización de solicitudes a Azure Storage. Solo se admite el portador de esquema para Microsoft Entra ID. Este encabezado se admite en la versión 2020-10-02 y posteriores.
`x-ms-source-range`	Opcional. Carga solo los bytes del blob en la dirección URL de origen del intervalo especificado. Si no se especifica, todo el contenido del blob de origen se carga como un único bloque de anexión. Consulte Especificación del encabezado de intervalo para las operaciones de Blob Storage para obtener más información.
`x-ms-source-content-md5`	Opcional. Hash MD5 del contenido del bloque anexado del URI. Este hash se usa para comprobar la integridad del bloque append durante el transporte de los datos desde el URI. Al especificar este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado del origen de copia con este valor de encabezado. Tenga en cuenta que este hash MD5 no se almacena con el blob. Si ambos valores de hash no coinciden, la operación produce un error con el código de estado 400 (solicitud incorrecta).
`x-ms-source-content-crc64`	Opcional. Hash CRC64 del contenido del bloque append del URI. Este hash se usa para comprobar la integridad del bloque append durante el transporte de los datos desde el URI. Al especificar este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado del origen de copia con este valor de encabezado. Tenga en cuenta que este hash CRC64 no se almacena con el blob. Si ambos valores de hash no coinciden, la operación produce un error con el código de estado 400 (solicitud incorrecta). Si ambos `x-ms-source-content-md5` encabezados y `x-ms-source-content-crc64` están presentes, se produce un error en la solicitud con un error 400 (solicitud incorrecta). Este encabezado se admite en la versión 2019-02-02 o posterior.
`x-ms-encryption-scope`	Opcional. Indica el ámbito de cifrado que se va a usar para cifrar el contenido de origen. Este encabezado se admite en la versión 2019-02-02 o posterior.
`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, vea Supervisar Azure Blob Storage.
`x-ms-blob-condition-maxsize`	Encabezado condicional opcional. Longitud máxima en bytes permitida para el blob en anexos. Si la `Append Block From URL` 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, la solicitud produce un error 412 (error de condición previa).
`x-ms-blob-condition-appendpos`	Encabezado condicional opcional, que solo se usa para la `Append Block from URL` operación. Número que indica el desplazamiento de bytes que se va a comparar. `Append Block from URL` 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 un 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 más información, consulte Especificación de encabezados condicionales para las operaciones de Blob Storage.

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

A partir de la versión 2019-02-02, puede especificar los encabezados siguientes 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. 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: 2018-11-09  
x-ms-date: <date>  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0 
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 usa el valor para realizar operaciones condicionales `PUT` mediante el encabezado de `If-Match` solicitud.
`Last-Modified`	La fecha y la hora en la 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 ú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 la versión 2019-02-02 o posterior, este encabezado solo se devuelve cuando la solicitud tiene este encabezado.
`x-ms-content-crc64`	Para la versión 2019-02-02 o posterior. 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 `x-ms-source-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 generado por el servicio que indica la hora a la que se inició la respuesta.
`x-ms-blob-append-offset`	Este encabezado de respuesta solo se devuelve para las operaciones de anexión. 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 cuántos anexos se pueden realizar.
`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. A continuación, 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. A continuación, el cliente puede asegurarse de que el contenido de la solicitud se cifre correctamente mediante el ámbito de cifrado.

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

La autorización es necesaria al llamar a cualquier operación de acceso a datos en Azure Storage. Puede autorizar la Append Block From URL operación como se describe a continuación.

Los detalles de autorización de esta sección se aplican al destino de copia. Para obtener más información sobre la autorización de origen de copia, consulte los detalles del encabezado x-ms-copy-sourcede solicitud .

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 que un usuario, grupo o entidad de servicio de Microsoft Entra llame a la Append Block From URL operación y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

Acción RBAC de Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action o Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Rol integrado con privilegios mínimos:Colaborador de datos de Storage Blob

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

Una firma de acceso compartido (SAS) proporciona acceso delegado seguro a los recursos de una cuenta de almacenamiento. Con una SAS, tiene un control pormenorizado sobre cómo un cliente puede acceder a los datos. Puede especificar a qué recurso puede acceder el cliente, qué permisos tienen para esos recursos y cuánto tiempo es válido la SAS.

La Append Block From URL operación admite tres tipos de firmas de acceso compartido: SAS de delegación de usuarios, SAS de servicio y SAS de cuenta.

Como procedimiento recomendado de seguridad, se recomienda usar Microsoft Entra credenciales en lugar de la clave de la cuenta de almacenamiento, que se puede poner en peligro más fácilmente. Si el diseño de la aplicación requiere firmas de acceso compartido, use Microsoft Entra credenciales para crear una SAS de delegación de usuarios, siempre que sea posible.

Cuando no se permite el acceso a la clave compartida para la cuenta de almacenamiento, no se permitirá un token de SAS de servicio o un token de SAS de cuenta en una solicitud a Blob Storage. Para más información, consulte Descripción de cómo no permitir la clave compartida afecta a los tokens de SAS.

SAS de delegación de usuarios

Una SAS de delegación de usuarios está protegida con credenciales de Microsoft Entra y también por los permisos especificados para la SAS.

La llamada a la Append Block From URL operación mediante un token de SAS delegado en un recurso de contenedor o blob requiere el permiso Agregar (a) o Escribir (w) como parte del token de SAS de delegación de usuarios:

Para más información sobre la SAS de delegación de usuarios, consulte Creación de una SAS de delegación de usuarios.

SAS de servicio

Una SAS de servicio está protegida con la clave de cuenta de almacenamiento. Una SAS de servicio delega el acceso a un recurso en un único servicio de Azure Storage, como Blob Storage.

Para más información sobre la SAS de servicio, consulte Creación de una SAS de servicio.

SAS de cuenta

Una SAS de cuenta está protegida con la clave de cuenta de almacenamiento. SAS de cuenta delega el acceso a los recursos en uno o varios de los servicios de almacenamiento. Todas las operaciones disponibles con una SAS de servicio o delegación de usuarios están también disponibles con una SAS de cuenta.

En la tabla siguiente se indica el tipo de recurso firmado y los permisos firmados que se especificarán al delegar el acceso:

Operación	Servicio firmado	Tipo de recurso firmado	Permiso firmado
Append Block From URL	Blob (b)	Objeto (o)	Agregar (a) o Escribir (w)

Para más información sobre la SAS de cuenta, consulte Creación de una SAS de cuenta.

Comentarios

Append Block From URL 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, donde. 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 From URL`)	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)

En la versión 2020-10-02 y posteriores, se admite Microsoft Entra ID autorización para el origen de la operación de copia.

Append Block From URL solo se ejecuta correctamente si el blob ya existe.

Los blobs cargados mediante Append Block From URL no exponen identificadores de bloque, por lo que 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 de condición previa).

Los clientes que usan un único escritor pueden usar este encabezado para determinar si una Append Block From URL operación se realizó correctamente, a pesar de los errores 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 de condición previa).

Si intenta cargar un bloque mayor que el tamaño permitido, el servicio devuelve el código de error HTTP 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, el servicio devuelve el código de error 412.

Si llama a Append Block From URL en un blob en bloques o blob en páginas existente, el servicio devuelve el código de error 409 (conflicto). Si llama a Append Block From URL en un blob inexistente, el servicio devuelve el código de error 404 (no encontrado).

Evitar anexaciones duplicadas o retrasadas

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 escritura múltiple, cada cliente puede usar encabezados condicionales. 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 su capa de aplicación. Por ejemplo, las aplicaciones pueden agregar épocas o números de secuencia en los datos que se van a anexar.

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

Facturación

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 Append Block From URL las solicitudes basadas en el tipo de cuenta de almacenamiento:

Operación	Tipo de cuenta de almacenamiento	Categoría de facturación
Anexar bloque de dirección URL (cuenta^{de destino 1})	Blobs en bloques Premium De uso general, estándar, v2 De uso general, estándar, v1	Operaciones de escritura
Anexar bloque de dirección URL (cuenta^{de origen 2})	Blobs en bloques Premium De uso general, estándar, v2 De uso general, estándar, v1	Lee operaciones.

¹La cuenta de destino se cobra por una transacción para iniciar la escritura.
²La cuenta de origen incurre en una transacción para cada solicitud de lectura en el origen.