Get Page Ranges

Artículo
02/03/2024

La operación Obtener intervalos de páginas devuelve la lista de intervalos de páginas válidos para un blob en páginas o una instantánea de un blob en páginas.

Solicitud

La solicitud Obtener intervalos de páginas se puede construir de la siguiente manera. Se recomienda usar HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento:

URI de solicitud de método GET	Versión de HTTP
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>&prevsnapshot=<DateTime>`	HTTP/1.1

URI del servicio de almacenamiento emulado

Al realizar una solicitud en el servicio de almacenamiento emulado, especifique el nombre de host del emulador y Azure Blob Storage puerto como 127.0.0.1:10000, seguido del nombre de la cuenta de almacenamiento emulada:

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

Para más información, consulte Uso del emulador de Azure Storage para desarrollo y pruebas.

Parámetros del identificador URI

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

Parámetro	Descripción
`marker`	Opcional, versión 2020-10-02 y posteriores. Identifica la parte de los intervalos que se van a devolver con la siguiente operación GetPageRanges. La operación devuelve un valor de marcador dentro del cuerpo de la respuesta si los intervalos devueltos estaban incompletos. A continuación, el valor del marcador se puede usar en una llamada posterior para solicitar el siguiente conjunto de intervalos. El valor de marcador es opaco para el cliente.
`maxresults`	Opcional, versión 2020-10-02 y posteriores. Especifica el número máximo de intervalos de páginas que se van a devolver. Si la solicitud especifica un valor mayor que 10 000, el servidor devuelve hasta 10 000 elementos. Si hay resultados adicionales para devolver, el servicio devuelve un token de continuación en el elemento de respuesta NextMarker. Si se establece `maxresults` en un valor menor o igual que cero, el código de respuesta de error 400 (solicitud incorrecta).
`snapshot`	Opcional. Valor DateTime opaco que, cuando está presente, especifica la instantánea de blob de la que se va a recuperar información. Para más información sobre cómo trabajar con instantáneas de blob, consulte Creación de una instantánea de un blob.
`timeout`	Opcional. Expresado en segundos. Para más información, consulte Establecimiento de tiempos de espera para las operaciones de Blob Storage.
`prevsnapshot`	Opcional, versión 2015-07-08 y posteriores. Valor DateTime que especifica que la respuesta contendrá solo las páginas que se cambiaron entre el blob de destino y la instantánea anterior. Las páginas modificadas incluyen páginas actualizadas y desactivadas. El blob de destino puede ser una instantánea, siempre que la instantánea especificada por `prevsnapshot` sea la anterior de las dos. Nota: Actualmente, las instantáneas incrementales solo se admiten para blobs creados el 1 de enero de 2016 o después.

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 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, opcional para las solicitudes anónimas. 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`	Opcional. Especifica el intervalo de bytes (incluidos) cuya lista de intervalos se va a obtener. Si `Range` se omite, se devuelven todos los intervalos del blob.
`x-ms-range`	Opcional. Especifica el intervalo de bytes (incluidos) cuya lista de intervalos se va a obtener. 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 Storage para obtener más información.
`x-ms-lease-id:<ID>`	Opcional. Si se especifica este encabezado, la operación solo se realiza si se cumplen las dos condiciones siguientes: - La concesión del blob está activa actualmente. : el identificador de concesión especificado en la solicitud coincide con el identificador de concesión del blob. Si se especifica este encabezado y no se cumple ninguna condición, se produce un error en la solicitud y se produce un error en la operación con el código de estado 412 (error de condición previa).
`x-ms-previous-snapshot-url`	Opcional, versión 2019-07-07 y posteriores. `previous-snapshot-url` especifica que la respuesta contendrá solo las páginas que se cambiaron entre el blob de destino y la instantánea que se encuentran en el URI especificado. Las páginas modificadas incluyen páginas actualizadas y desactivadas. El blob de destino puede ser una instantánea, siempre que la instantánea especificada por este encabezado sea la anterior de las dos. Nota: Actualmente, las instantáneas incrementales solo se admiten para blobs creados el 1 de enero de 2016 o después, y que este encabezado solo se debe usar en escenarios de disco administrado. De lo contrario, use el `prevsnapshot` parámetro .
`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 de análisis cuando azure Storage Analytics registro está habilitado. Se recomienda encarecidamente usar este encabezado al 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 las solicitudes de Azure Storage.

Esta operación también admite el uso de encabezados condicionales para obtener intervalos de páginas solo si se cumple una condición especificada. Para más información, consulte Especificación de encabezados condicionales para las operaciones de Blob Storage.

Cuerpo de la solicitud

Ninguno.

Response

La respuesta incluye un código de estado HTTP, un conjunto de encabezados de respuesta y el cuerpo de respuesta.

status code

Una operación correcta devuelve el código de estado 200 Correcto.

Para obtener más información sobre los códigos de estado, vea Códigos de estado y de error.

Encabezados de respuesta

La respuesta 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
`Last-Modified`	La fecha y la hora en la que se modificó por última vez el blob. El formato de la fecha sigue las convenciones de RFC 1123. Cualquier operación que modifique el blob, incluida una actualización de los metadatos o las propiedades del blob, cambia la hora de la última modificación del blob.
`ETag`	Contiene un valor que el cliente puede usar para realizar la operación condicionalmente. Si la versión de la solicitud es 2011-08-18 o posterior, el valor ETag se incluye entre comillas.
`x-ms-blob-content-length`	Tamaño del blob en bytes.
`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 Storage que se usó para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas en la versión 2009-09-19 y posteriores. Este encabezado también se devuelve para las solicitudes anónimas sin una versión especificada si el contenedor se marcó para el acceso público mediante la versión 2009-09-19 de Blob Storage.
`Date`	Valor de fecha y hora UTC generado por el servicio, que indica la hora en que se inició la respuesta.
`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

El cuerpo de la respuesta incluye una lista de intervalos de páginas no superpuestos, válidos, ordenados aumentando el intervalo de páginas de direcciones. El formato del cuerpo de respuesta es el siguiente:

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
</PageList>

Si se ha borrado todo el conjunto de páginas del blob, el cuerpo de la respuesta no incluye ningún intervalo de páginas.

Si se especificó el prevsnapshot parámetro , la respuesta incluye solo las páginas que difieren entre la instantánea de destino o el blob y la instantánea anterior. Las páginas devueltas incluyen ambas páginas que se actualizaron o borraron. El formato de este cuerpo de respuesta es el siguiente:

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
</PageList>

Si se ha borrado todo el conjunto de páginas del blob y no se especificó el prevsnapshot parámetro , el cuerpo de la respuesta no incluye ningún intervalo de páginas.

Si se especificó el maxresults parámetro , la respuesta solo incluye el número especificado de intervalos con un token de continuación en la NextMarker etiqueta . El token de continuación está vacío si no hay más intervalos pendientes o, de lo contrario, contiene un valor opaco que debe enviarse como parámetro marker en la siguiente solicitud. El formato de este cuerpo de respuesta es el siguiente:

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>
   <NextMarker/>
</PageList>

Authorization

La autorización es necesaria al llamar a cualquier operación de acceso a datos en Azure Storage. Puede autorizar la Get Page Ranges 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 Get Page Ranges operación y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

Acción RBAC de Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Rol integrado con privilegios mínimos:Lector de datos de Blob de Storage

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.

Una firma de acceso compartido (SAS) proporciona acceso delegado seguro a los recursos de una cuenta de almacenamiento. Con una SAS, tiene un control pormenorizado sobre cómo un cliente puede acceder a los datos. Puede especificar a qué recurso puede acceder el cliente, qué permisos tienen para esos recursos y cuánto tiempo es válido la SAS.

La Get Page Ranges operación admite tres tipos de firmas de acceso compartido: SAS de delegación de usuarios, SAS de servicio y SAS de cuenta.

Como procedimiento recomendado de seguridad, se recomienda usar Microsoft Entra credenciales en lugar de la clave de la cuenta de almacenamiento, que se puede poner en peligro más fácilmente. Si el diseño de la aplicación requiere firmas de acceso compartido, use Microsoft Entra credenciales para crear una SAS de delegación de usuarios, siempre que sea posible.

Cuando no se permite el acceso a la clave compartida para la cuenta de almacenamiento, no se permitirá un token de SAS de servicio o un token de SAS de cuenta en una solicitud a Blob Storage. Para más información, consulte Descripción de cómo no permitir la clave compartida afecta a los tokens de SAS.

SAS de delegación de usuarios

Una SAS de delegación de usuarios está protegida con credenciales de Microsoft Entra y también por los permisos especificados para la SAS.

La llamada a la Get Page Ranges operación mediante un token de SAS delegado en un recurso de contenedor o blob requiere el permiso De lectura (r) como parte del token de SAS de delegación de usuarios.

Para más información sobre la SAS de delegación de usuarios, consulte Creación de una SAS de delegación de usuarios.

SAS de servicio

Una SAS de servicio está protegida con la clave de cuenta de almacenamiento. Una SAS de servicio delega el acceso a un recurso en un único servicio de Azure Storage, como Blob Storage.

La llamada a la Get Page Ranges operación mediante un token de SAS delegado en un recurso de contenedor o blob requiere el permiso De lectura (r) como parte del token de SAS de servicio.

Para más información sobre la SAS de servicio, consulte Creación de una SAS de servicio.

SAS de cuenta

Una SAS de cuenta está protegida con la clave de cuenta de almacenamiento. SAS de cuenta delega el acceso a los recursos en uno o varios de los servicios de almacenamiento. Todas las operaciones disponibles con una SAS de servicio o delegación de usuarios están también disponibles con una SAS de cuenta.

En la tabla siguiente se indica el tipo de recurso firmado y los permisos firmados que se especificarán al delegar el acceso:

Operación	Servicio firmado	Tipo de recurso firmado	Permiso firmado
Get Page Ranges	Blob (b)	Objeto (o)	Lectura (r)

Para más información sobre la SAS de cuenta, consulte Creación de una SAS de cuenta.

Comentarios

Los desplazamientos de byte inicial y final de cada intervalo de páginas están incluidos.

En un blob en páginas muy fragmentado con un gran número de operaciones de escritura, una solicitud Get Page Ranges puede generar errores debido a un tiempo de espera interno del servidor. Las aplicaciones que recuperan intervalos de un blob en páginas con un gran número de operaciones de escritura deben recuperar un subconjunto de intervalos de páginas cada vez.

A partir de la versión 2015-07-08, puede llamar a Get Page Ranges con el prevsnapshot parámetro para devolver las páginas que difieren entre el blob base y una instantánea, o entre dos instantáneas del blob. Con estas diferencias de página, puede guardar una instantánea incremental de un blob en páginas. Las instantáneas incrementales son una manera rentable de realizar copias de seguridad de discos de máquina virtual si desea implementar su propia solución de copia de seguridad.

Al llamar Get Page Ranges con el prevsnapshot parámetro , se devuelven páginas que se han actualizado o borrado desde que se tomó la instantánea especificada por prevsnapshot . Después, puede copiar las páginas que se devuelven a un blob en páginas de copia de seguridad en otra cuenta de almacenamiento mediante Put Page.

A partir de la versión 2019-07-07, puede usar el x-ms-previous-snapshot-url encabezado para especificar instantáneas en cuentas de disco administrado para instantáneas incrementales. Si no usa discos administrados, use el prevsnapshot parámetro de consulta.

Algunas operaciones de un blob producen Get Page Ranges un error cuando se llama para devolver una instantánea incremental. Get Pages Ranges produce un error con el código de error 409 (conflicto) si se llama a en un blob que era el destino de una solicitud Put Blob o Copy Blob después de tomar la instantánea especificada por prevsnapshot . Si el destino de la Get Page Ranges operación es una instantánea, la llamada se realiza correctamente siempre que la instantánea especificada por prevsnapshot sea anterior y no Put Blob se haya llamado a ninguna operación o Copy Blob en el intervalo entre las dos instantáneas.

Nota

Actualmente, las instantáneas incrementales solo se admiten para blobs creados el 1 de enero de 2016 o después. Los intentos de usar esta característica en un blob anterior producirán el BlobOverwritten error , que es el código de error HTTP 409 (Conflicto).

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 Storage