Poner bloque de URL

2025-05-11

La Put Block From URL operación crea un nuevo bloque que se confirmará como parte de un blob en el que el contenido se lee desde una dirección URL. Esta API está disponible a partir de la versión 2018-03-28.

Solicitud

Puede construir la solicitud Put Block From URL de la siguiente manera. Se recomienda usar 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=block&blockid=id`	HTTP/1.1

Solicitud de servicio de almacenamiento emulado

Cuando realice una solicitud en el servicio de almacenamiento emulado, especifique el nombre de host del emulador y el puerto del servicio Blob 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=block&blockid=id`	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
`blockid`	Obligatorio. Valor de cadena Base64 válido que identifica el bloque. Antes de codificar, la cadena debe tener un tamaño menor o igual a 64 bytes. En el caso de un blob especificado, la longitud del valor especificado para el `blockid` parámetro debe tener el mismo tamaño para cada bloque. Nota: La cadena Base64 debe estar codificada como URL.
`timeout`	Opcional. El parámetro `timeout` se expresa en segundos. Para obtener más información, consulte Establecer tiempos de espera para las operaciones de Blob Service.

Cabeceras de solicitud

Los encabezados de solicitud obligatorios y opcionales se describen en la tabla siguiente:

Cabecera de solicitud	Descripción
`Authorization`	Obligatorio. Especifica el esquema de autorización, el nombre de la cuenta y la firma. Para más información, consulte Autorizar solicitudes a Azure Storage.
`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. Para `Put Block From URL`, la versión debe ser 2018-03-28 o posterior.
`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 0. Cuando la longitud no es 0, se produce un error en la operación con el código de estado 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 kibibytes (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 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 del origen de copia. Para más información, consulte Autorizar solicitudes a Azure Storage. Nota: solo se admite un esquema de portador para Microsoft Entra. Nota: si el objeto de origen es accesible públicamente o el objeto de origen está en una cuenta de almacenamiento y usa un token de SAS que se pasa en `x-ms-copy-source:name`, este encabezado no es necesario. Este encabezado se admite en las versiones 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 este encabezado, todo el contenido del blob de origen se carga como un solo bloque. Para obtener más información, consulte Especificar el encabezado de intervalo para las operaciones de Blob service.
`x-ms-source-content-md5`	Opcional. Un hash MD5 del contenido del bloque desde el URI. Este hash se utiliza para verificar la integridad del bloque durante el transporte de los datos desde el URI. Cuando se especifica este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado del origen de copia con este valor de encabezado. Nota: 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. Un hash CRC64 del contenido del bloque del URI. Este hash se utiliza para verificar la integridad del bloque durante el transporte de los datos desde el URI. Cuando se especifica este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado del origen de copia con este valor de encabezado. Nota: 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 las versiones 2019-02-02 y posteriores.
`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 las versiones 2019-02-02 y 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 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-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.

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

A partir de la versión 2019-02-02, se pueden 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

Ninguno.

Solicitud de ejemplo

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2018-03-28  
x-ms-date: Sat, 31 Mar 2018 14:37:35 GMT    
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-499

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 más 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
`Content-MD5`	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 que el valor especificado en los encabezados de solicitud. Para las versiones 2019-02-02 y posteriores, este encabezado solo se devuelve cuando la solicitud tiene este encabezado.
`x-ms-content-crc64`	Para las versiones 2019-02-02 y posteriores. 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 lo mismo que el valor especificado en los encabezados de la solicitud. Se devuelve cuando `x-ms-source-content-md5` el encabezado no está presente en la solicitud.
`x-ms-request-id`	Identifica de forma única la solicitud que se realizó y puede usarla para solucionar problemas de la solicitud. Para obtener más información, consulte Solución de problemas de operaciones de API.
`x-ms-version`	Versión de Blob Storage que se usó para ejecutar la solicitud.
`Date`	Valor de fecha y hora UTC generado por el servicio, que indica la hora en que se inició la respuesta.
`x-ms-request-server-encrypted: true/false`	Versión 2015-12-11 y posteriores. El valor de este encabezado se establece en `true` si el contenido del bloque 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 y posteriores. Se devuelve si la solicitud usó una clave proporcionada por el cliente para el cifrado, de modo que el cliente pueda asegurarse de que el contenido de la solicitud se cifre correctamente mediante la clave proporcionada.
`x-ms-encryption-scope`	Versión 2019-02-02 y posteriores. Se devuelve si la solicitud usó un ámbito de cifrado, para que el cliente pueda asegurarse de que el contenido de la solicitud se cifre correctamente mediante el ámbito de cifrado.
`x-ms-client-request-id`	Se puede usar para solucionar problemas de solicitudes y respuestas correspondientes. El valor de este encabezado es igual al valor del encabezado `x-ms-client-request-id` si está presente en la solicitud y el valor no contiene más de 1024 caracteres ASCII visibles. Si el encabezado `x-ms-client-request-id` no está presente en la solicitud, no estará presente en la respuesta.

Respuesta de ejemplo

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sat, 31 Mar 2018 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

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 Put Block From URL como se describe a continuación.

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 Put Block From URL 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/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 operación de Put Block From URL mediante un token de SAS delegado en un recurso de contenedor o blob requiere el permiso de escritura (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.

Llamar a la operación de mediante un token de SAS delegado en un recurso de contenedor o blob requiere el permiso de escritura (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
Poner bloque de URL	Mancha (b)	Objeto (o)	Escritura (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 Put 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

Put Block From URL Carga un bloque para su futura inclusión en un blob en bloques. Un blob en bloques puede incluir un máximo de 50.000 bloques. Cada bloque puede tener un tamaño diferente. El tamaño máximo de un bloque que se carga es Put Block From URL de 100 mebibytes (MiB). Para cargar bloques más grandes (hasta 4.000 MiB), consulte Put Block.

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

Un blob puede tener un máximo de 100.000 bloques sin confirmar en cualquier momento. Si se supera este máximo, el servicio devuelve el código de estado 409 (RequestEntityTooLargeBlockCountExceedsLimit).

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 `Put Block From URL`)	Tamaño máximo de blob (a través de `Put Block List`)	Tamaño máximo de blob a través de una sola operación de escritura (a través de `Put Blob From URL`)
Versión 2020-04-08 y posteriores	4.000 MiB	Aproximadamente 190,7 tebibytes (TiB) (4.000 MiB × 50.000 bloques)	5.000 MiB
Versiones anteriores a 2020-04-08	100 MiB	Aproximadamente 4,75 TiB (100 MiB × 50.000 bloques)	256 MiB

Una vez que haya cargado un conjunto de bloques, puede crear o actualizar el blob en el servidor a partir de este conjunto llamando a la operación Put Block List . Cada bloque del conjunto se identifica mediante un identificador de bloque que es único dentro de ese blob. Los identificadores de bloque se limitan a un blob determinado, por lo que diferentes blobs pueden tener bloques con los mismos identificadores.

Si llama a Put Block From URL un blob que aún no existe, se crea un nuevo blob en bloques con una longitud de contenido de 0. Este blob se enumera mediante la List Blobs operación si se especifica la include=uncommittedblobs opción. El bloque o los bloques que ha cargado no se confirman hasta que se llama Put Block List al nuevo blob. Un blob creado de esta manera se mantiene en el servidor durante una semana. Si no ha agregado más bloques o ha confirmado bloques al blob en ese período de tiempo, el blob se recolecta como elemento no utilizado.

Un bloque que se ha cargado correctamente con la Put Block From URL operación no se convierte en parte de un blob hasta que se confirma con Put Block List. Se llama a Before Put Block List para confirmar el blob nuevo o actualizado, las llamadas a Get Blob devuelven el contenido del blob sin la inclusión del bloque no confirmado.

Si carga un bloque que tiene el mismo ID de bloque que otro bloque que aún no se ha confirmado, el último bloque cargado con ese ID se confirma en la siguiente operación correcta Put Block List .

After Put Block List , todos los bloques no confirmados especificados en la lista de bloques se confirman como parte del nuevo blob. Los bloques no confirmados que no se especificaron en la lista de bloques del blob se recolectan como elementos no utilizados y se quitan de Blob Storage. Los bloques no confirmados también se recolectan como elementos no utilizados si no hay llamadas correctas al Put Block From URL mismo blob o Put Block List en el mismo blob en el plazo de una semana después de la última operación correcta Put Block From URL . Si se llama a Put Blob en el blob, los bloques no confirmados se recolectan como elementos no utilizados.

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 estado 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 estado 412 (error de condición previa).

Para un blob especificado, todos los identificadores de bloque deben tener la misma longitud. Si se carga un bloque con un ID de bloque de una longitud diferente a la de los ID de bloque para los bloques no confirmados existentes, el servicio devuelve el código de respuesta de error 400 (solicitud incorrecta).

Las llamadas Put Block From URL no actualizan la hora de la última modificación de un blob existente.

Al llamar a Put Block From URL un blob en páginas, se devuelve un error.

Al llamar a Put Block From URL un blob de "archivo", se devuelve un error y al llamarlo en un hot blob or cool no se cambia el nivel del blob.

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

Operación	Tipo de cuenta de almacenamiento	Categoría de facturación
Poner bloque de URL (cuenta de destino¹)	Blob en bloques Premium Uso general estándar v2 Uso general estándar v1	Operaciones de escritura
Put Block From 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.
²La cuenta de origen incurre en una transacción por cada solicitud de lectura al objeto de origen.

Además, si las cuentas de origen y destino residen en regiones diferentes (por ejemplo, Norte de EE. UU. y Sur de EE. UU.), el ancho de banda que se usa para transferir la solicitud se cobra a la cuenta de almacenamiento de origen como salida. La salida entre cuentas dentro de la misma región es gratuita.

Para obtener información sobre los precios de las categorías de facturación especificadas, consulte precios de Azure Blob Storage.

Compartir a través de