Compartilhar via


Get Page Ranges

A operação Obter Intervalos de Páginas retorna a lista de intervalos de página válidos para um blob de páginas ou instantâneo de um blob de páginas.

Solicitação

A solicitação Obter Intervalos de Páginas pode ser construída da seguinte maneira. Recomendamos que você use HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento:

URI de solicitação de método GET Versão 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 do serviço de armazenamento emulado

Ao fazer uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e Armazenamento de Blobs do Azure porta como 127.0.0.1:10000, seguido pelo nome da conta de armazenamento emulada:

URI de solicitação de método GET Versão HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist HTTP/1.1

Para saber mais, confira Usar o Emulador de Armazenamento do Azure para desenvolvimento e teste.

Parâmetros do URI

Os seguintes parâmetros adicionais podem ser especificados no URI de solicitação:

Parâmetro Descrição
marker Opcional, versão 2020-10-02 e posterior. Identifica a parte dos intervalos a serem retornados com a próxima operação GetPageRanges. A operação retornará um valor de marcador dentro do corpo da resposta se os intervalos retornados estiverem incompletos. Em seguida, o valor do marcador pode ser usado em uma chamada subsequente para solicitar o próximo conjunto de intervalos.

O valor do marcador é opaco ao cliente.
maxresults Opcional, versão 2020-10-02 e posterior. Especifica o número máximo de intervalos de páginas a serem retornados. Se a solicitação especificar um valor maior que 10.000, o servidor retornará até 10.000 itens. Se houver resultados adicionais a serem retornados, o serviço retornará um token de continuação no elemento de resposta NextMarker.

Definir maxresults como um valor menor ou igual a zero resulta em código de resposta de erro 400 (Solicitação Incorreta).
snapshot Opcional. Um valor datetime opaco que, quando presente, especifica o instantâneo de blob do qual recuperar informações. Para obter mais informações sobre como trabalhar com instantâneos de blob, consulte Create um instantâneo de um blob.
timeout Opcional. Expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações de Armazenamento de Blobs.
prevsnapshot Opcional, versão 2015-07-08 e posterior. Um valor DateTime que especifica que a resposta conterá apenas páginas que foram alteradas entre o blob de destino e o instantâneo anterior. As páginas alteradas incluem páginas atualizadas e desmarcadas. O blob de destino pode ser um instantâneo, desde que o instantâneo especificado por prevsnapshot seja o mais antigo dos dois.

Observação: atualmente, há suporte para instantâneos incrementais apenas para blobs que foram criados em ou após 1º de janeiro de 2016.

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho da solicitação Descrição
Authorization Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
Date ou x-ms-date Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
x-ms-version Necessário para todas as solicitações autorizadas, opcional para solicitações anônimas. Especifica a versão da operação a ser usada para esta solicitação. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure.
Range Opcional. Especifica o intervalo de bytes no qual listar intervalos, inclusive. Se Range for omitido, todos os intervalos para o blob serão retornados.
x-ms-range Opcional. Especifica o intervalo de bytes no qual listar intervalos, inclusive. Se Range e x-ms-range forem especificados, o serviço usará o valor de x-ms-range. Consulte Especificar o cabeçalho de intervalo para operações de Armazenamento de Blobs para obter mais informações.
x-ms-lease-id:<ID> Opcional. Se esse cabeçalho for especificado, a operação será executada somente se ambas as seguintes condições forem atendidas:

- A concessão do blob está ativa no momento.

- A ID de concessão especificada na solicitação corresponde à ID de concessão do blob.

Se esse cabeçalho for especificado e qualquer uma das condições não for atendida, a solicitação falhará e a operação falhará com status código 412 (Falha na pré-condição).
x-ms-previous-snapshot-url Opcional, versão 2019-07-07 e posterior. O previous-snapshot-url especifica que a resposta conterá apenas páginas que foram alteradas entre o blob de destino e instantâneo localizados no URI especificado. As páginas alteradas incluem páginas atualizadas e desmarcadas. O blob de destino pode ser um instantâneo, desde que o instantâneo especificado por esse cabeçalho seja o mais antigo dos dois.

Observação: atualmente, há suporte para instantâneos incrementais somente para blobs criados em ou após 1º de janeiro de 2016 e que esse cabeçalho só deve ser usado em cenários de disco gerenciado. Caso contrário, use o prevsnapshot parâmetro .
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres KiB (1 kibibyte), que é registrado nos logs de análise quando o log de Análise de Armazenamento do Azure está habilitado. É altamente recomendável que você use esse cabeçalho ao correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Sobre Análise de Armazenamento registro em log e registro em log do Azure: use logs para acompanhar solicitações do Armazenamento do Azure.

Essa operação também dará suporte ao uso de cabeçalhos condicionais para obter intervalos de página somente se uma determinada condição for atendida. Para obter mais informações, consulte Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs.

Corpo da solicitação

Nenhum.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e o corpo de resposta.

Código de status

Uma operação bem-sucedida retorna o código de status 200 (OK).

Para obter mais informações sobre códigos de status, consulte Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também pode incluir cabeçalhos padrão HTTP adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Sintaxe Descrição
Last-Modified A data e a hora da última modificação feita no blob. O formato da data segue RFC 1123.

Qualquer operação que modificar o blob, incluindo uma atualização dos metadados ou das propriedades do blob, alterará a hora da última modificação do blob.
ETag Contém um valor que o cliente pode usar para executar a operação condicionalmente. Se a versão da solicitação for 2011-08-18 ou posterior, o valor ETag será colocado entre aspas.
x-ms-blob-content-length O tamanho do blob em bytes.
x-ms-request-id Identifica exclusivamente a solicitação que foi feita e pode ser usada para solucionar problemas da solicitação. Para obter mais informações, consulte Solucionar problemas de operações de API.
x-ms-version Indica a versão do Armazenamento de Blobs que foi usada para executar a solicitação. Esse cabeçalho é retornado para solicitações que foram feitas na versão 2009-09-19 e posterior.

Esse cabeçalho também será retornado para solicitações anônimas sem uma versão especificada se o contêiner tiver sido marcado para acesso público usando o Armazenamento de Blobs versão 2009-09-19.
Date Um valor de data/hora UTC gerado pelo serviço, que indica a hora em que a resposta foi iniciada.
x-ms-client-request-id Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho será igual ao valor do x-ms-client-request-id cabeçalho se ele estiver presente na solicitação e o valor não contiver mais de 1.024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente na solicitação, ele não estará presente na resposta.

Corpo da resposta

O corpo da resposta inclui uma lista de intervalos de páginas válidos e não sobrepostos, classificados pelo aumento do intervalo de páginas de endereços. Formato do corpo da resposta:

<?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>  

Se todo o conjunto de páginas do blob tiver sido limpo, o corpo da resposta não incluirá nenhum intervalo de páginas.

Se o prevsnapshot parâmetro tiver sido especificado, a resposta incluirá apenas as páginas que diferem entre o instantâneo de destino ou o blob e o instantâneo anterior. As páginas retornadas incluem ambas as páginas que foram atualizadas ou desmarcadas. O formato desse corpo de resposta é o seguinte:

<?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>  
  

Se todo o conjunto de páginas do blob tiver sido limpo e o prevsnapshot parâmetro não tiver sido especificado, o corpo da resposta não incluirá nenhum intervalo de páginas.

Se o maxresults parâmetro tiver sido especificado, a resposta incluirá apenas o número especificado de intervalos com um token de continuação na NextMarker marca. O token de continuação estará vazio se não houver mais intervalos pendentes ou se ele contiver um valor opaco que precisa ser enviado como um marker parâmetro na próxima solicitação. O formato desse corpo de resposta é o seguinte:

<?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>  
  

Autorização

A autorização é necessária ao chamar qualquer operação de acesso a dados no Armazenamento do Azure. Você pode autorizar a Get Page Ranges operação, conforme descrito abaixo.

Importante

A Microsoft recomenda usar Microsoft Entra ID com identidades gerenciadas para autorizar solicitações ao Armazenamento do Azure. Microsoft Entra ID fornece segurança superior e facilidade de uso em comparação com a autorização de Chave Compartilhada.

O Armazenamento do Azure dá suporte ao uso de Microsoft Entra ID para autorizar solicitações para dados de blob. Com Microsoft Entra ID, você pode usar o RBAC (controle de acesso baseado em função) do Azure para conceder permissões a uma entidade de segurança. A entidade de segurança pode ser um usuário, grupo, entidade de serviço de aplicativo ou identidade gerenciada do Azure. A entidade de segurança é autenticada por Microsoft Entra ID para retornar um token OAuth 2.0. Em seguida, o token pode ser usado para autorizar uma solicitação no serviço de Blob.

Para saber mais sobre a autorização usando Microsoft Entra ID, consulte Autorizar o acesso a blobs usando Microsoft Entra ID.

Permissões

Veja abaixo a ação RBAC necessária para um usuário Microsoft Entra, grupo, identidade gerenciada ou entidade de serviço para chamar a Get Page Ranges operação e a função RBAC interna do Azure com menos privilégios que inclui esta ação:

Para saber mais sobre como atribuir funções usando o RBAC do Azure, confira Atribuir uma função do Azure para acesso aos dados de blob.

Comentários

Os deslocamentos de bytes de início e de término para cada intervalo de páginas são inclusivos.

Em um blob de página altamente fragmentado com um grande número de gravações, uma solicitação Get Page Ranges poderá falhar devido a um tempo limite interno do servidor. Os aplicativos que recuperam intervalos de um blob de página com um grande número de operações de gravação devem recuperar um subconjunto de intervalos de página por vez.

A partir da versão 2015-07-08, você pode chamar Get Page Ranges com o prevsnapshot parâmetro para retornar as páginas que diferem entre o blob base e um instantâneo ou entre dois instantâneos do blob. Usando essas diferenças de página, você pode salvar um instantâneo incremental de um blob de páginas. Instantâneos incrementais são uma maneira econômica de fazer backup de discos de máquina virtual se você quiser implementar sua própria solução de backup.

Chamar Get Page Ranges com o prevsnapshot parâmetro retorna páginas que foram atualizadas ou desmarcadas desde que o instantâneo especificado por prevsnapshot foi obtido. Em seguida, você pode copiar as páginas retornadas para um blob de páginas de backup em outra conta de armazenamento usando Colocar Página.

A partir da versão 2019-07-07, você pode usar o x-ms-previous-snapshot-url cabeçalho para especificar instantâneos em contas de disco gerenciado para instantâneos incrementais. Se você não estiver usando discos gerenciados, use o prevsnapshot parâmetro de consulta.

Determinadas operações em um blob causam Get Page Ranges falha quando ele é chamado para retornar uma instantâneo incremental. Get Pages Rangesfalhará com o código de erro 409 (Conflito) se ele for chamado em um blob que foi o destino de uma solicitação de Blob Put ou Copiar Blob depois que a instantâneo especificada por prevsnapshot foi tomada. Se o destino da Get Page Ranges operação for um instantâneo, a chamada terá êxito desde que o instantâneo especificado por prevsnapshot seja mais antigo e nenhuma Put Blob operação ou Copy Blob tenha sido chamada no intervalo entre os dois instantâneos.

Observação

Atualmente, há suporte para instantâneos incrementais apenas para blobs que foram criados em ou após 1º de janeiro de 2016. As tentativas de usar esse recurso em um blob mais antigo resultarão no erro, que é o BlobOverwritten código de erro HTTP 409 (Conflito).

Confira também

Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Definir tempos limite para operações de Armazenamento de Blobs