Put Page From URL

Artículo
09/22/2022
Tiempo de lectura: 17 minutos

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

La solicitud Put Page From URL se puede construir como sigue. Se recomienda HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento:

URI de solicitud del método PUT	Versión HTTP
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page`	HTTP/1.1

URI de servicio de almacenamiento emulado

Al realizar 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 emulado:

URI de solicitud del método PUT	Versión HTTP
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=page`	HTTP/1.1

Para obtener más información, consulte Uso de la Azure Storage Emulator para desarrollo y pruebas.

Parámetros de identificador URI

Se pueden especificar los parámetros adicionales siguientes en el URI de 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

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

Encabezado de solicitud	Descripción
`Authorization`	Necesario. Especifica el esquema de autorización, el nombre de cuenta y la firma. Para obtener más información, consulte Autorización de solicitudes para Azure Storage.
`Date` o `x-ms-date`	Necesario. Especifica la hora universal coordinada (UTC) de la solicitud. Para obtener más información, consulte Autorización de solicitudes para Azure Storage.
`x-ms-version`	Necesario 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, consulte Control de versiones para 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 – 1. 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`. Consulte Especificación del encabezado de intervalo para las operaciones de Blob Service para obtener más información.
`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 – 1. 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`. Consulte Especificación del encabezado de intervalo para las operaciones de Blob Service para obtener más información.
`Content-Length`	Necesario. Especifica el número de bytes que se transmiten en el cuerpo de la solicitud. El valor de este encabezado debe establecerse en cero. Cuando la longitud no es cero, se producirá un error en la operación con el código de 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 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, consulte Autorización de solicitudes para Azure Storage. Solo se admite el portador del esquema para Azure Active Directory. Este encabezado se admite en las versiones 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. 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. Tenga en cuenta que este hash md5 no se almacena con el blob. Si ambos valores de hash no coinciden, la operación producirá 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. Tenga en cuenta que este hash CRC64 no se almacena con el blob. Si ambos valores de hash no coinciden, la operación producirá un error con el código de estado 400 (Solicitud incorrecta). Si los encabezados y están `x-ms-source-content-md5x-ms-source-content-crc64` presentes, se producirá un error en la solicitud con un error 400 (solicitud incorrecta). Este encabezado es compatible con las versiones 2019-02-02 o 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; en caso contrario, produce el 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; en caso contrario, produce el 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 que el valor especificado, la solicitud continúa; en caso contrario, produce el 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 u hora especificada. 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, el servicio Blob 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 las versiones 2019-02-02 o posteriores.
`x-ms-client-request-id`	Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 KiB que se registra en los registros de análisis cuando se habilita el registro de análisis de almacenamiento. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes recibidas por el servidor. Para más información, consulte Acerca del registro de Storage Analytics y el registro de Azure: Uso de registros para realizar un seguimiento de Storage solicitudes.

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 obtener 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.

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 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 o una más reciente, el valor ETag estará 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 Representación de valores de Date-Time 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`	Este encabezado se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. El valor de este encabezado lo calcula el servicio Blob; no es necesariamente el mismo valor que el especificado en los encabezados de solicitud. Para las versiones 2019-02-02 o posteriores, este encabezado solo se devuelve cuando la solicitud tiene este encabezado.
`x-ms-content-crc64`	Para las versiones 2019-02-02 o posteriores, este encabezado se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. El valor de este encabezado lo calcula el servicio Blob; no es necesariamente el mismo valor que el 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`	Este encabezado identifica de forma única la solicitud que se realizó y se puede utilizar para solucionar problemas relacionados con esta. Para más información, consulte Solución de problemas de operaciones de API.
`x-ms-version`	Indica la versión del servicio Blob utilizado para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas en la versión 2009-09-19 y versiones posteriores.
`Date`	Valor de fecha y hora UTC generado por el servicio que indica la hora a la que se inició la respuesta.
`x-ms-request-server-encrypted: true/false`	Versión 2015-12-11 o posterior. El valor de este encabezado se establece `true` en si el contenido de la solicitud se cifra correctamente mediante el algoritmo especificado y `false` , de lo contrario, .
`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, 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 o posterior. Este encabezado 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`	Este encabezado 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 es como máximo 1024 caracteres ASCII visibles. Si el `x-ms-client-request-id` encabezado no está presente en la solicitud, este encabezado no estará presente en la respuesta.

Cuerpo de la 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

Authorization

La llamada a esta operación la puede realizar el propietario de la cuenta y cualquiera que disponga de una firma de acceso compartido con permiso para escribir en el blob o en su contenedor.

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

En la versión 2020-10-02 y versiones posteriores, se admite Azure Active Directory 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 poder escribir una página.

Operaciones de actualización de páginas

La llamada realiza Put Page From URL 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 se agota el tiempo de espera del servidor o se cierra la conexión durante una operación Put Page From URL, es posible que la página no se haya actualizado. 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 de 4 MB, el servicio devuelve el código de estado 413 (Entidad solicitada demasiado grande).

Administrar problemas de simultaneidad

El servicio Blob administra las operaciones de escritura simultáneas en páginas superpuestas de forma secuencial: 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 de Blob service no tiene por qué corresponder necesariamente al orden en que las ejecutó el servicio. 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 en otras escrituras durante un período de un minuto o más tiempo si se renueva la concesión.
Puede utilizar el número de secuencia del blob para garantizar que si se reintenta una solicitud para la que no hubo respuesta no se producirán 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.

Utilizar el número de secuencia del blob 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 ninguna manera de saber con certeza si la solicitud se realizó correctamente. Por lo tanto, es necesario reintentar 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 demorada puede sobrescribir otras actualizaciones y producir un resultado inesperado. La secuencia siguiente muestra cómo puede ocurrir esto:

Una solicitud Put Page From URL para escribir el valor “X” en la página 0 agota el tiempo de espera o no devuelve una respuesta.
Una solicitud reintentada para escribir el valor “X” en la página 0 se realiza correctamente.
Una solicitud para escribir el valor “Y” en la página 0 se realiza correctamente.
La solicitud original se realiza correctamente, escribiendo el valor “X” en la página 0.
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 ocurrir cuando la solicitud original no devuelve un código de estado comprendido entre 100 y 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 utilizar 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. A continuación, puede utilizar los encabezados de número de secuencia condicionales para asegurarse de que la solicitud produce un error si su número de secuencia no coincide con el número de secuencia esperado. La secuencia siguiente muestra este método:

El cliente crea un blob en páginas con Put Blob y establece su número de secuencia en 0.
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.
El cliente llama a Set Blob Properties para actualizar el número de secuencia a 1.
Solicitud de reintento para escribir el valor "X" en la página 0 con if-sequence-number-lt establecido en 2 correcto.
Una solicitud para escribir el valor "Y" en la página 0 con if-sequence-number-lt establecido en 2 correcto.
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).
La lectura de la página 0 devuelve el valor esperado de “Y”.

Consulte también

Autorización de solicitudes a Azure Storage
Códigos de estado y error
Establecer los tiempos de espera para las operaciones del servicio Blob