Compartir por


Put Page From 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 Put Page From URL solicitud como se indica a continuación. Se recomienda usar 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=page HTTP/1.1

URI 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 de Blob service 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=page 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

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

Parámetro Descripción
timeout Opcional. El parámetro timeout se expresa en segundos. Para más información, consulte Establecimiento de tiempos de espera para las operaciones de Blob Service.

Encabezados de solicitud

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

Encabezado de solicitud Descripción
Authorization Necesario. Especifica el esquema de autorización, el nombre de la cuenta y la firma. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
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.
Range Es obligatorio especificar Range o x-ms-range.

Especifica el intervalo de bytes que se van a escribir como una página. Es necesario especificar tanto el inicio como el final del intervalo. Este encabezado se define mediante la especificación del protocolo HTTP/1.1.

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 alinearse 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 a 1. Algunos ejemplos de intervalos de bytes válidos son 0-511, 512-1023, etc.

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

Si se especifican Range y x-ms-range, el servicio utiliza el valor de x-ms-range. Para más información, consulte Especificación del 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 van a escribir como una página. Es necesario especificar tanto el inicio como el final del intervalo. Este encabezado se define mediante la especificación del protocolo HTTP/1.1.

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

Dado que las páginas deben alinearse 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 a 1. Algunos ejemplos de intervalos de bytes válidos son 0-511, 512-1023, etc.

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

Si se especifican Range y x-ms-range, el servicio utiliza el valor de x-ms-range. Para más información, consulte Especificación del encabezado de intervalo para las operaciones de Blob Service.
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 produce un error en la operación con el código de estado 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 para URL tal y 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 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 del intervalo especificado. Es necesario especificar tanto el inicio como el final del intervalo. Este encabezado se define mediante la especificación del protocolo HTTP/1.1.

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 encabezado x-ms-source-range, y el intervalo de bytes debe especificarse en el formato siguiente: bytes=startByte-endByte.

Consulte Especificación del encabezado de intervalo para las operaciones de Blob Service para obtener más información.
x-ms-source-content-md5 Opcional. Hash MD5 del contenido de la página del URI. Este hash se usa para comprobar 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 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 de la página del URI. Este hash se usa para comprobar 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 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 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 de 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 DateTime. Especifique este encabezado condicional para escribir la página solo si el blob se ha modificado desde la fecha u hora especificada. Si el blob no se ha modificado, Blob service devuelve el código de estado 412 (error de condición previa).
If-Unmodified-Since Opcional. Valor 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, Blob service devuelve el código de estado 412 (Error de condición previa).
If-Match Opcional. 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, Blob service devuelve el código de estado 412 (error de condición previa).
If-None-Match Opcional. Valor ETag.

Especifique un valor ETag para este encabezado condicional para escribir 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 usar para cifrar el contenido de origen. Este encabezado es compatible con 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 obtener más información, consulte Supervisión de Azure Blob Storage.

Esta operación también admite el uso de encabezados condicionales que permiten ejecutar la operación solo si se cumple una condición especificada. Para más información, consulte Especificación de 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.

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

Cuerpo de la solicitud

El cuerpo de la solicitud incluye el contenido 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  
  

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 más 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.

Sintaxis Descripción
ETag La ETag del blob. Si la versión de la solicitud es 2011-08-18 y posteriores, el valor ETag se incluye entre comillas. La ETag se puede utilizar para realizar una operación Put Page From URL condicional especificando su valor para el encabezado de solicitud If-Match o If-None-Match.
Last-Modified Fecha y la hora en que se modificó por última vez el blob. El formato de la fecha sigue las convenciones de RFC 1123. Para obtener más información, vea Representar valores de fecha y hora en encabezados.

Cualquier operación de escritura realizada 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. Blob service calcula el valor de este encabezado. No es necesariamente igual 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. Blob service calcula el valor de este encabezado. No es necesariamente igual 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 El 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 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 true en si el contenido de la solicitud se cifra correctamente mediante el algoritmo especificado y false , de lo contrario, .
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, por lo que 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 y posteriores. Se devuelve si la solicitud usó un ámbito de cifrado, por lo que el cliente puede 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 x-ms-client-request-id encabezado si está presente en la solicitud y el valor no contiene más de 1024 caracteres ASCII visibles. Si el x-ms-client-request-id encabezado no está presente en la solicitud, no estará presente en la respuesta.

Response body

Ninguno.

Respuesta de muestra

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  
  

Authorization

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

Importante

Microsoft recomienda usar Microsoft Entra ID con identidades administradas para autorizar solicitudes a Azure Storage. Microsoft Entra ID proporciona una mayor seguridad y facilidad de uso 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. La entidad de seguridad se autentica mediante Microsoft Entra ID para devolver un token de OAuth 2.0. Después, el token se puede usar para autorizar una solicitud en Blob service.

Para más información sobre la autorización mediante Microsoft Entra ID, consulte Autorización del acceso a blobs mediante Microsoft Entra ID.

Permisos

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

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

Comentarios

La operación Put Page From URL 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 a para crear un nuevo blob en páginas, ni se puede llamar en un blob en bloques. La llamada Put Page From URL a con un nombre de blob que no existe actualmente devuelve el error BlobNotFound (código de estado HTTP 404: no encontrado).

En la versión 2020-10-02 y posteriores, se admite Microsoft Entra autorización 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 un 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 en contexto en el blob en páginas especificado. El contenido de la página especificada se sobrescribe con la actualización.

Importante

Si el servidor agota el tiempo de espera o se cierra la conexión durante una 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 con Put Page From URL para una operación de actualización puede tener un tamaño de hasta 4 MiB. El intervalo inicial y final de la página deben alinearse con límites de 512 bytes. Si intenta cargar un intervalo de páginas mayor que 4 MiB, el servicio devuelve el código de estado 413 (solicitar entidad demasiado grande).

Administración de problemas de simultaneidad

Blob service controla las escrituras simultáneas en páginas superpuestas secuencialmente. 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 operaciones de escritura en páginas superpuestas utilizando uno o varios de los métodos siguientes:

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

  • Puede realizar actualizaciones condicionales en función de la ETag del blob o de la hora de última modificación utilizando simultaneidad optimista. Este método funciona bien si el número de operaciones de escritura simultáneas es relativamente bajo. Utilice los encabezados de solicitud condicionales If-Match, If-None-Match, If-Modified-Since y If-Unmodified-Since con este fin.

  • Puede llamar a Lease Blob para bloquear el blob con 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 al reintentar una solicitud para la que no haya respuesta, no se produzcan actualizaciones simultáneas. Este método puede ser más apropiado para los clientes que requieran un alto rendimiento en las operaciones de escritura en páginas. se describe en detalle en la sección siguiente.

Uso del número de secuencia de blobs en páginas para reintentar solicitudes

Cuando una llamada a Put Page From URL agota el tiempo de espera o no devuelve una respuesta, no hay forma de saber 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 de reintento se haya realizado correctamente. La solicitud original demorada puede sobrescribir otras actualizaciones y producir un resultado inesperado. En la secuencia siguiente se muestra cómo puede ocurrir 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 en este momento esperaba 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, podrá saber con certeza si la solicitud se ha realizado correctamente o ha producido un error. Pero si el servicio devuelve un código de estado fuera de este intervalo, no hay ninguna manera de saber 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, al reintentar una solicitud, la solicitud original no se realizará correctamente posteriormente. Para ello, deberá aumentar el número de secuencia antes de volver a intentar la solicitud original. Después, 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 secuencia siguiente muestra este método:

  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 if-sequence-number-lt encabezado establecido en 1 agota el 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. Solicitud reintenta para escribir el valor "X" en la página 0 con if-sequence-number-lt establecido en 2 correcto.

  5. Solicitud para escribir el valor "Y" en la página 0 con if-sequence-number-lt establecido en 2 correcto.

  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 1en ). 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

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