Compartir a través de


Poner página desde URL

La Put Page From URL operación escribe un intervalo de páginas en un blob en páginas donde el contenido se lee desde una dirección URL. Esta API está disponible a partir de la versión 2018-11-09.

Solicitud

Puede construir la solicitud Put Page 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=page HTTP/1.1

URI del 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=page 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

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

Parámetro Descripción
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.
Range Es obligatorio especificar Range o x-ms-range.

Especifica el intervalo de bytes que se escribirán como página. Se deben especificar el inicio y el final del intervalo. Este encabezado se define mediante la especificación del protocolo HTTP/1.1 de .

Para una operación de actualización de página, el intervalo de páginas puede tener un tamaño de hasta 4 MiB.

Dado que las páginas deben estar alineadas con límites de 512 bytes, el desplazamiento inicial debe ser un módulo de 512 y el desplazamiento final debe ser un módulo de 512 – 1. Ejemplos de rangos de bytes válidos son 0-511, 512-1023, etc.

El servicio Blob solo acepta un único intervalo de bytes para el Range encabezado y el intervalo de bytes debe especificarse en el siguiente formato: bytes=startByte-endByte.

Si se especifican Range y x-ms-range, el servicio usa el valor de x-ms-range. Para obtener más información, consulte Especificar el encabezado de intervalo para las operaciones de Blob service.
x-ms-range Es obligatorio especificar Range o x-ms-range.

Especifica el intervalo de bytes que se escribirán como página. Se deben especificar el inicio y el final del intervalo. Este encabezado se define mediante la especificación del protocolo HTTP/1.1 de .

El intervalo de páginas puede tener un tamaño de hasta 4 MiB.

Dado que las páginas deben estar alineadas con límites de 512 bytes, el desplazamiento inicial debe ser un módulo de 512 y el desplazamiento final debe ser un módulo de 512 – 1. Ejemplos de rangos de bytes válidos son 0-511, 512-1023, etc.

El servicio Blob solo acepta un único intervalo de bytes para el x-ms-range encabezado y el intervalo de bytes debe especificarse en el siguiente formato: bytes=startByte-endByte.

Si se especifican Range y x-ms-range, el servicio usa el valor de x-ms-range. Para obtener más información, consulte Especificar el encabezado de intervalo para las operaciones de Blob service.
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 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 KB de longitud que especifique un blob. El valor debe estar codificado con dirección URL, ya que 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 se admite un portador de esquema para Microsoft Entra.
Este encabezado se admite en la versión 2020-10-02 y posteriores.
x-ms-source-range Carga los bytes del blob en la dirección URL de origen en el intervalo especificado. Se deben especificar el inicio y el final del intervalo. Este encabezado se define mediante la especificación del protocolo HTTP/1.1 de .

El intervalo de páginas puede tener un tamaño de hasta 4 MiB.

El servicio Blob solo acepta un único intervalo de bytes para el x-ms-source-range encabezado y el intervalo de bytes debe especificarse en el siguiente formato: bytes=startByte-endByte.

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 de la página desde el URI. Este hash se utiliza para verificar la integridad de la página 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 de la página desde el URI. Este hash se utiliza para verificar la integridad de la página 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 se admite en la versión 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-if-sequence-number-le: <num> Opcional. Si el número de secuencia del blob es menor o igual que el valor especificado, la solicitud continúa. De lo contrario, se produce un error SequenceNumberConditionNotMet (código de estado HTTP 412 – Error de condición previa).
x-ms-if-sequence-number-lt: <num> Opcional. Si el número de secuencia del blob es menor que el valor especificado, la solicitud continúa. De lo contrario, se produce un error SequenceNumberConditionNotMet (código de estado HTTP 412 – Error de condición previa).
x-ms-if-sequence-number-eq: <num> Opcional. Si el número de secuencia del blob es igual al valor especificado, la solicitud continúa. De lo contrario, se produce un error SequenceNumberConditionNotMet (código de estado HTTP 412 – Error de condición previa).
If-Modified-Since Opcional. Valor de DateTime. Especifique este encabezado condicional para escribir la página solo si el blob se ha modificado desde la fecha y hora especificadas. Si el blob no se ha modificado, el servicio Blob devuelve el código de estado 412 (error de condición previa).
If-Unmodified-Since Opcional. Valor de DateTime. Especifique este encabezado condicional para escribir la página solo si el blob no se ha modificado desde la fecha y hora especificadas. Si el blob se ha modificado, el servicio Blob devuelve el código de estado 412 (error de condición previa).
If-Match Opcional. Un valor ETag. Especifique un valor ETag para este encabezado condicional para escribir la página solo si el valor ETag del blob coincide con el valor especificado. Si los valores no coinciden, el servicio Blob devuelve el código de estado 412 (error de condición previa).
If-None-Match Opcional. Un valor ETag.

Especifique un valor ETag para que este encabezado condicional escriba la página solo si el valor ETag del blob no coincide con el valor especificado. Si los valores son idénticos, Blob service devuelve el código de estado 412 (error de condición previa).
x-ms-encryption-scope Opcional. Indica el ámbito de cifrado que se va a utilizar para cifrar el contenido de origen. Este encabezado se admite en la versión 2019-02-02 y posteriores.
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.

Esta operación también admite el uso de encabezados condicionales para ejecutar la operación solo si se cumple una condición especificada. Para obtener más información, consulte Especificar encabezados condicionales para las operaciones de Blob service.

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 cifrado 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 de la página.

Solicitud de ejemplo

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:   
x-ms-date: Fri, 16 Sep 2011 22:15:50 GMT  
x-ms-version: 2018-11-09  
x-ms-range: bytes=0-65535  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0  
  

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 .

Sintaxis Descripción
ETag ETag para el blob. Si la versión de la solicitud es 2011-08-18 y posterior, el valor ETag se escribe entre comillas. La ETag se puede utilizar para realizar una operación condicional Put Page From URL especificando su valor para el encabezado de solicitud If-Match or If-None-Match .
Last-Modified Fecha y la 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 Representar 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 Se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. El servicio Blob calcula el valor de este encabezado. No es necesariamente el mismo que el 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. Se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. El servicio Blob calcula el valor de este encabezado. No es necesariamente el mismo que el valor especificado en los encabezados de solicitud.

Este encabezado se devuelve cuando x-ms-source-content-md5 el encabezado no está presente en la solicitud.
x-ms-blob-sequence-number Número de secuencia actual del blob en páginas.
x-ms-request-id Identifica de forma única la solicitud que se realizó y se puede usar para solucionar problemas de la solicitud. Para obtener más información, consulte Solución de problemas de operaciones de API.
x-ms-version Indica la versión de Blob service que se usó 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 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 de la solicitud se cifra correctamente mediante el algoritmo especificado y false , de otro modo, si no lo hace.
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.

Cuerpo de respuesta

Ninguno.

Respuesta de ejemplo

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Sun, 25 Sep 2011 12:13:31 GMT  
x-ms-version: 2011-08-18  
x-ms-blob-sequence-number: 0  
Content-Length: 0  
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 Page 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.

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 Page From URL y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

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.

Observaciones

La Put Page From URL operación escribe un intervalo de páginas en un blob en páginas. Solo se puede llamar a esta operación en un blob en páginas existente. No se puede llamar para crear un nuevo blob en páginas, ni se puede llamar en un blob en bloques. Al llamar Put Page From URL con un nombre de blob que no existe actualmente, se devuelve el error BlobNotFound (código de estado HTTP 404 – Not Found).

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.

Para crear un nuevo blob en páginas, llame a Put Blob y especifique el tipo de blob que se va a crear como blob en páginas. Un blob en páginas puede tener un tamaño de hasta 8 TiB.

Si el blob tiene una concesión activa, el cliente debe especificar un identificador de concesión válido en la solicitud para escribir una página.

Operaciones de actualización de página

La llamada Put Page From URL realiza una escritura local en el blob en páginas especificado. Cualquier contenido de la página especificada se sobrescribe con la actualización.

Importante

Si se agota el tiempo de espera del servidor o se cierra la conexión durante un Put Page From URL, es posible que la página se haya actualizado o no. Por lo tanto, debe continuar reintentando la actualización hasta que reciba una respuesta que indique que se ha realizado correctamente.

Cada intervalo de páginas enviadas Put Page From URL para una operación de actualización puede tener un tamaño de hasta 4 MiB. El intervalo de inicio y fin de la página debe estar alineado con límites de 512 bytes. Si intenta cargar un intervalo de páginas superior a 4 MiB, el servicio devuelve el código de estado 413 (Entidad de solicitud demasiado grande).

Administración de problemas de simultaneidad

El servicio Blob controla secuencialmente las escrituras simultáneas en páginas superpuestas. Es decir, la última página procesada por el servicio determina el contenido del blob. Por lo tanto, para garantizar la integridad del contenido del blob, el cliente debe controlar las escrituras en páginas superpuestas mediante uno o varios de los siguientes enfoques:

  • Puede comprobar el valor del encabezado de Last-Modified respuesta para cada llamada correcta a Put Page From URL. El orden de las respuestas devueltas por el servicio Blob no se corresponde necesariamente con el orden en el que las ejecutó el servicio. Pero el valor de Last-Modified always indica el orden en el que el servicio procesó las solicitudes.

  • Puede realizar actualizaciones condicionalmente en función de la ETag del blob o de la hora de la última modificación mediante simultaneidad optimista. Este enfoque funciona bien si el número de escrituras simultáneas es relativamente bajo. Utilice los encabezados If-Matchde solicitud condicional , If-None-Match, If-Modified-Since, y If-Unmodified-Since para este propósito.

  • Puede llamar a Lease Blob para bloquear el blob en otras escrituras durante un período de un minuto o más si se renueva la concesión.

  • Puede usar el número de secuencia del blob para asegurarse de que el reintento de una solicitud para la que no hubo respuesta no dé lugar a actualizaciones simultáneas. Este enfoque puede ser el mejor para los clientes que requieren un alto rendimiento para las escrituras de página. Se describe en detalle en la siguiente sección.

Usar el número de secuencia del blob en páginas para reintentar las solicitudes

Cuando se agota el tiempo de espera de una llamada o Put Page From URL no devuelve una respuesta, no hay forma de saber con certeza si la solicitud se realizó correctamente. Por lo tanto, debe volver a intentar la solicitud, pero debido a la naturaleza distribuida de los servicios de almacenamiento de Azure, es posible que la solicitud original se procese después de que la solicitud reintentada se haya realizado correctamente. La solicitud original retrasada puede sobrescribir otras actualizaciones y producir un resultado inesperado. La siguiente secuencia ilustra cómo puede suceder esto:

  1. Una Put Page From URL solicitud para escribir el valor "X" en la página 0 agota el tiempo de espera o no devuelve una respuesta.

  2. Una solicitud reintentada para escribir el valor "X" en la página 0 se realiza correctamente.

  3. Una solicitud para escribir el valor "Y" en la página 0 se realiza correctamente.

  4. La solicitud original se realiza correctamente, escribiendo el valor "X" en la página 0.

  5. La lectura de la página 0 devuelve el valor "X", cuando el cliente esperaba en este punto el valor "Y".

Este tipo de conflicto puede producirse cuando la solicitud original no devuelve un código de estado entre 100-499 o 503 (servidor ocupado). Si se devuelve uno de estos códigos de estado, puede estar seguro de si la solicitud se ha realizado correctamente o no. Pero si el servicio devuelve un código de estado fuera de este intervalo, no hay forma de conocer el estado de la solicitud original.

Para evitar este tipo de conflicto, puede usar el número de secuencia del blob en páginas para asegurarse de que, cuando vuelva a intentar una solicitud, la solicitud original no se realice correctamente. Para ello, debe incrementar el número de secuencia antes de volver a intentar la solicitud original. A continuación, puede usar los encabezados de número de secuencia condicional para asegurarse de que se produce un error en la solicitud si su número de secuencia no coincide con el número de secuencia esperado. La siguiente secuencia ilustra este enfoque:

  1. El cliente crea un blob en páginas con Put Blob y establece su número de secuencia en 0.

  2. Una Put Page From URL solicitud para escribir el valor "X" en la página 0 con el encabezado establecido en if-sequence-number-lt se agota el 1 tiempo de espera o no devuelve una respuesta.

  3. El cliente llama a Set Blob Properties para actualizar el número de secuencia a 1.

  4. Una solicitud reintentada para escribir el valor "X" en la página 0 con if-sequence-number-lt un valor establecido en 2 se realiza correctamente.

  5. Una solicitud para escribir el valor "Y" en la página 0 con if-sequence-number-lt un valor establecido en 2 se realiza correctamente.

  6. La solicitud original se procesa finalmente, pero se produce un error porque especifica la condición de que el número de secuencia debe ser menor que 1 (es decir, el if-sequence-num-lt encabezado se establece en 1). El error es SequenceNumberConditionNotMet (código de estado HTTP 412 – Error de condición previa).

  7. La lectura de la página 0 devuelve el valor esperado de "Y".

Consulte también

Autorizar solicitudes a Azure Storage
Estado y códigos de error
Establecimiento de tiempos de espera para las operaciones de Blob Service