Anexar bloque de URL

2025-05-11

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 un valor .AppendBlob Append Block From URL solo se admite en la versión 2018-11-09 o posterior.

Solicitud

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

URI de solicitud de método PUT	Versión 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 el puerto de Azure Blob Storage como 127.0.0.1:10000, seguido del nombre de la cuenta de almacenamiento emulada.

URI de solicitud de método PUT	Versión 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 el desarrollo local de Azure Storage.

Parámetros de 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 operaciones de Blob Storage.

Cabeceras de solicitud

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

Cabecera de solicitud	Descripción
`Authorization`	Obligatorio. Especifica el esquema de autorización, el nombre de la cuenta y la firma. Consulte Autorizar solicitudes a Azure Storage para más información.
`Date` o `x-ms-date`	Obligatorio. Especifica la hora universal coordinada (UTC) de la solicitud. Para más información, consulte Autorizar solicitudes a Azure Storage.
`x-ms-version`	Necesario para todas las solicitudes autorizadas. Especifica la versión de la operación que se va a usar para esta solicitud. Para más información, consulte Control de versiones de para los servicios de Azure Storage.
`Content-Length`	Obligatorio. 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`	Obligatorio. Especifica la dirección URL del blob de origen. El valor puede ser una dirección URL de hasta 2 KiB de longitud que especifique un blob. El valor debe estar codificado en URL, tal 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 más información, consulte Autorizar solicitudes a Azure Storage. Solo el portador del esquema es compatible con el identificador de Microsoft Entra. 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 en el intervalo especificado. Si no se especifica, todo el contenido del blob de origen se carga como un único bloque de anexos. Para obtener más información, consulte Especificación del encabezado de intervalo para operaciones de Blob Storage .
`x-ms-source-content-md5`	Opcional. Hash MD5 del contenido del bloque de anexión 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 los dos hash no coinciden, se produce un error en la operación con el código de error 400 (solicitud incorrecta).
`x-ms-source-content-crc64`	Opcional. Hash CRC64 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 CRC64 no se almacena con el blob. Si los dos hash no coinciden, se produce un error en la operación con el código de error 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 400 (solicitud incorrecta). Este encabezado es compatible con la versión 2019-02-02 o posterior.
`x-ms-encryption-scope`	Opcional. Indica el ámbito de cifrado que se va a utilizar para cifrar el contenido de origen. Este encabezado es compatible con 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 para 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 más información, consulte Monitor 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, se produce un error en la solicitud con un error 412 (error de condición previa).
`x-ms-blob-condition-appendpos`	Encabezado condicional opcional, utilizado solo 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).
`x-ms-file-request-intent`	Obligatorio si `x-ms-copy-source` el encabezado es una dirección URL de archivo de Azure y `x-ms-copy-source-authorization` el encabezado especifica un token de OAuth. El valor aceptable es `backup`. Este encabezado especifica que se debe conceder el `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` o `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` si se incluyen en la directiva de RBAC asignada a la identidad autorizada mediante el encabezado `x-ms-copy-source-authorization`. Disponible para la versión 2025-07-05 y posteriores.

Esta operación admite el uso de encabezados condicionales adicionales para garantizar que la API solo se realice correctamente si se cumple una condición especificada. Para obtener más información, consulte Especificación de encabezados condicionales para 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 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.

Cabecera de solicitud	Descripción
`x-ms-encryption-key`	Obligatorio. Clave de cifrado AES-256 codificada en Base64.
`x-ms-encryption-key-sha256`	Obligatorio. Hash SHA256 codificado en Base64 de la clave de cifrado.
`x-ms-encryption-algorithm: AES256`	Obligatorio. 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 contiene 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"

Respuesta

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

Código de estado

Una operación correcta devuelve el código de estado 201 (creado). Para obtener información sobre los códigos de estado, vea Códigos de estado y de error.

Encabezados de respuesta

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

Encabezado de respuesta	Descripción
`Etag`	Contiene `ETag` un valor entre comillas. El cliente utiliza el valor para realizar operaciones condicionales `PUT` mediante el encabezado de solicitud `If-Match` .
`Last-Modified`	La fecha y hora en que se modificó por última vez el blob. El formato de fecha sigue a 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 las 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 la 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 la 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 utilizada para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas en la versión 2009-09-19 y posteriores.
`Date`	Valor de fecha y hora UTC generado por el servicio que indica la hora en 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 usar esto para controlar cuántos anexos más se pueden realizar.
`x-ms-request-server-encrypted: true/false`	Versión 2015-12-11 o posterior. El valor de este encabezado se establece en `true` 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 cifra 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 cifra correctamente mediante el ámbito de cifrado.

Respuesta de ejemplo

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

Autorización

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

Los detalles de autorización de esta sección se aplican al destino de la 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 .

Importante

Microsoft recomienda usar el identificador de Entra de Microsoft con identidades administradas para autorizar solicitudes a Azure Storage. Microsoft Entra ID proporciona seguridad y facilidad de uso superiores en comparación con la autorización de clave compartida.

Microsoft Entra ID (recomendado)
firmas de acceso compartido (SAS)
clave compartida

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. Microsoft Entra ID autentica la entidad de seguridad para devolver un token de OAuth 2.0. Después, el token se puede usar para autorizar una solicitud en Blob service.

Para obtener más información sobre la autorización mediante el identificador de Entra de Microsoft, consulte Autorizar el acceso a blobs mediante el identificador de Microsoft Entra.

Permisos

A continuación se enumeran las acciones de RBAC necesarias para que un usuario, grupo, identidad administrada o entidad de servicio de Microsoft Entra llame a la operación de Append Block From URL y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

Acción de 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 Blob storage

Para más información sobre cómo asignar roles mediante Azure RBAC, 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 tener acceso el cliente, a qué permisos tienen esos recursos y cuánto tiempo es válido la SAS.

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

Como procedimiento recomendado de seguridad, se recomienda usar credenciales de Microsoft Entra en lugar de la clave de la cuenta de almacenamiento, que se puede poner en peligro con mayor facilidad. Si el diseño de la aplicación requiere firmas de acceso compartido, use las credenciales de Microsoft Entra 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 obtener 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 las credenciales de Microsoft Entra y también por los permisos especificados para la SAS.

Llamar a la Append Block From URL operación mediante un token de SAS delegado a un recurso de contenedor o blob requiere el permiso Add (a) o Write (w) como parte del token de SAS de delegación de usuarios:

Para obtener 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 llamar a la Append Block From URL operación mediante un token de SAS delegado a un recurso de contenedor o blob, se requiere el permiso Add (a) o Write (w) como parte del token de SAS de servicio.

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

Cuenta SAS

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

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

Operación	Servicio firmado	Tipo de recurso firmado	Permiso firmado
Anexar bloque de URL	Mancha (b)	Objeto (o)	Agregue (a) o escriba (w)

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

La operación de Append Block From URL admite autorización de clave compartida. No se recomienda autorizar con claves de cuenta para la mayoría de los escenarios, ya que es menos seguro.

Microsoft recomienda no permitir la autorización de clave compartida para la cuenta de almacenamiento siempre que sea posible. Para obtener más información, consulte Impedir autorización con clave compartida.

Observaciones

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. Cada bloque puede ser de diferente tamaño.

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 de 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 la autorización de identificador de Microsoft Entra para el origen de la operación de copia.

Append Block From URL Solo se realiza 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 agregar 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 solo escritor pueden usar este encabezado para determinar si una Append Block From URL 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 aumenten 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 que es mayor que el tamaño permitido, el servicio devuelve el código de error HTTP 413 (Entidad de solicitud demasiado grande). El servicio también devuelve información adicional sobre el error en la respuesta, incluido el tamaño de bloque máximo 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 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 un blob en bloques o un blob en páginas existente, el servicio devuelve el código de error 409 (conflicto). Si llama a Append Block From URL un blob inexistente, el servicio devuelve el código de error 404 (no encontrado).

Evite anexos duplicados o retrasados

En un escenario de un solo escritor, el cliente puede evitar anexiones 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 el ETag condicionalmente, mediante el uso de If-Match.

En un escenario de varios escritores, cada cliente puede usar encabezados condicionales. Es posible que esto no sea óptimo para el rendimiento. Para obtener el mayor rendimiento de anexiones simultáneas, las aplicaciones deben controlar los anexados redundantes y los anexados retrasados en su capa de aplicación. Por ejemplo, las aplicaciones pueden agregar épocas o números de secuencia en los datos que se anexan.

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

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 las solicitudes de Append Block From URL en función del tipo de cuenta de almacenamiento:

Operación	Tipo de cuenta de almacenamiento	Categoría de facturación
Anexar bloque de URL (cuenta de destino¹)	Blob en bloques Premium Uso general estándar v2 Uso general estándar v1	Operaciones de escritura
Anexar bloque de URL (cuenta de origen²)	Blob en bloques Premium Uso general estándar v2 Uso general estándar v1	Operaciones de lectura

¹La cuenta de destino se cobra por una transacción para iniciar la escritura.
^{número arábigo}La cuenta de origen incurre en una transacción por cada solicitud de lectura al origen.

Compartir a través de