Put Page
La operación Put Page
escribe un intervalo de páginas en un blob en páginas.
Solicitud
Puede construir la solicitud de la Put Page
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 de HTTP |
---|---|
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page |
HTTP/1.1 |
Solicitud 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 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 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 |
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, 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 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. 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 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 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 clear en , el valor de este encabezado debe establecerse en 0 . |
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 es compatible con 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 0 en y establezca el Range encabezado en un valor que indica 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 es compatible con 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.
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 muestra la acción de RBAC necesaria para que un usuario, grupo, identidad administrada o entidad de servicio Microsoft Entra llame a la Put Page
operación y el rol RBAC integrado con privilegios mínimos que incluya esta acción:
- Acción RBAC de Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- Rol integrado con privilegios mínimos:Colaborador de datos de Storage Blob
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. Esta operación solo se puede llamar en un blob en páginas existente. No se puede llamar a para crear un nuevo blob en páginas, ni se puede llamar a en un blob en bloques. La llamada Put Page
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áginas
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 la conexión se cierra 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 mayores que 4 MiB, el servicio devuelve el código de estado 413 (solicitar entidad demasiado grande).
Operaciones de borrado de página
Al llamar con Put Page
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 en 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 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 enfoques siguientes:
Puede comprobar el valor del encabezado de respuesta
Last-Modified
para cada llamada correcta aPut Page
. El orden de las respuestas devueltas desde Blob Storage no corresponde necesariamente al orden en que el servicio ejecutó. Pero el valor deLast-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
yIf-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 usar el número de secuencia del blob para asegurarse de que reintentar una solicitud para la que no haya respuesta no produzca 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 con 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 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 reintenta 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:
Una
Put Page
solicitud 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 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. 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 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
solicitud para escribir el valor "X" en la página 0 con elif-sequence-number-lt
encabezado establecido en1
agota el tiempo de espera o no devuelve una respuesta.El cliente llama
Set Blob Properties
a para actualizar el número de secuencia a1
.Solicitud de reintento para escribir el valor "X" en la página 0 con
if-sequence-number-lt
establecido en2
correcto.Una solicitud para escribir el valor "Y" en la página 0 con
if-sequence-number-lt
establecido en2
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 en1
). 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
Estado y códigos de error
Establecimiento de tiempos de espera para las operaciones de Blob Service