Put Page

La operación Put Page escribe un intervalo de páginas en un blob en páginas.

Solicitud

Puede construir la Put Page 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

Solicitud de servicio de almacenamiento emulada

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 ser de hasta 4 MiB. Para una operación de borrado de página , el intervalo de páginas puede ser tan grande como el valor del tamaño completo del blob.

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

Blob Storage solo acepta un único intervalo de bytes para el Range encabezado 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.

Para una operación de actualización de página, el intervalo de páginas puede ser tan grande como 4 MiB de tamaño. En una operación de borrado de páginas, el intervalo de páginas puede alcanzar un tamaño máximo igual al del blob.

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. Ejemplos de intervalos de bytes válidos son 0-511, 512-1023, etc.

Blob Storage solo acepta un único intervalo de bytes para el x-ms-range encabezado 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. Cuando el x-ms-page-write encabezado se establece clearen , el valor de este encabezado debe establecerse 0en .
Content-MD5 Opcional. Hash MD5 del contenido de la página. Este hash se utiliza para comprobar la integridad de la página durante el transporte. Cuando se especifica este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado con este valor de encabezado.
<br/ >Note: 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-content-crc64 Opcional. Hash CRC64 del contenido de la página. Este hash se utiliza para comprobar la integridad de la página durante el transporte. Cuando se especifica este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado 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 los Content-MD5 encabezados y x-ms-content-crc64 están presentes, la solicitud produce un error 400 (solicitud incorrecta).

Este encabezado se admite en la versión 2019-02-02 y posteriores.
x-ms-page-write: {update ¦ clear} Necesario. Puede especificar una de las siguientes opciones:

- Update: escribe los bytes especificados por el cuerpo de la solicitud en el intervalo especificado. Los encabezados Range y Content-Length deben coincidir para realizar la actualización.
- Clear: borra el intervalo especificado y libera el espacio que se usa en el almacenamiento de ese intervalo. Para borrar un intervalo, establezca el Content-Length encabezado 0en y establezca el Range encabezado en un valor que indique el intervalo que se va a borrar, hasta el tamaño máximo del blob.
x-ms-encryption-scope Opcional. Indica el ámbito de cifrado que se va a usar para cifrar el contenido de la solicitud. 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 Storage 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 se ha modificado el blob, Blob Storage 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 Storage 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 Storage devuelve el código de estado 412 (error de condición previa).
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, puede especificar los siguientes encabezados en la solicitud para cifrar un blob con una clave proporcionada por el cliente. El cifrado con una clave proporcionada por el cliente (y el conjunto de encabezados correspondiente) es opcional.

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: Actualización del intervalo de bytes

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

Solicitud de ejemplo: Borrar intervalo de bytes

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:  
Range: bytes=1024-2048  
x-ms-page-write: clear  
x-ms-date: Sun, 25 Sep 2011 23:37:35 GMT  
x-ms-version: 2011-08-18  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
  

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 condicional especificando su valor para el encabezado de solicitud If-Match o If-None-Match.
Last-Modified Fecha y 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 Este encabezado se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. Blob Storage calcula el valor de este encabezado. No es necesariamente igual que el valor especificado en los encabezados de solicitud. Para la versión 2019-02-02 y posteriores, este encabezado solo se devuelve cuando la solicitud tiene este encabezado.
x-ms-content-crc64 Para la versión 2019-02-02 o posterior, este encabezado se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. Blob Storage calcula el valor de este encabezado. No es necesariamente igual que el valor especificado en los encabezados de solicitud.

Este encabezado se devuelve cuando 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. 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, 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:  
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 operación como se describe a continuación.

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 que un usuario, grupo o entidad de servicio de Microsoft Entra llame a la Put Page operación 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 RBAC de Azure, consulte Asignación de un rol de Azure para el acceso a datos de blobs.

Comentarios

La operación Put Page 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 a con un nombre de blob que no existe actualmente devuelve el código de estado HTTP 404 (no encontrado).

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

Una llamada a Put Page con la opción Update 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 operación, es posible que la página se haya actualizado o no. Por lo tanto, debe seguir reintentando la actualización hasta que reciba una respuesta que indique que se ha realizado correctamente.

Cada intervalo de páginas que se envía con Put Page 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).

Operaciones de borrado de página

La llamada Put Page con la Clear opción libera el espacio de almacenamiento que usa la página especificada. Las páginas que se han borrado dejan de seguirse de como parte del blob en páginas.

Las páginas que se han borrado ya no incurren en un cargo en la cuenta de almacenamiento, ya que se han liberado sus recursos de almacenamiento. La única excepción a esto es si hay instantáneas existentes del blob en páginas. Las páginas de las instantáneas conllevan un cargo si esas mismas páginas ya no existen como parte del blob de origen.

Administración de problemas de simultaneidad

Blob Storage 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 escrituras en páginas superpuestas mediante 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. El orden de las respuestas devueltas desde Blob Storage 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 enfoque puede ser mejor para los clientes que requieren un alto rendimiento para las escrituras en páginas. Esto 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 agota el tiempo de espera o no devuelve una respuesta, no hay ninguna manera de saber si la solicitud se realizó correctamente. Por lo tanto, debe 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 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 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 de 100 a 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. 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 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 Set Blob Properties a 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