Get Page Ranges

Artigo
05/15/2024

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:

Ação RBAC do Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Função interna com privilégios mínimos:Leitor de Dados do Blob de Armazenamento

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.

Uma SAS (assinatura de acesso compartilhado) fornece acesso delegado seguro aos recursos em uma conta de armazenamento. Com uma SAS, você tem controle granular sobre como um cliente pode acessar dados. Você pode especificar qual recurso o cliente pode acessar, quais permissões eles têm para esses recursos e por quanto tempo a SAS é válida.

A Get Page Ranges operação dá suporte a três tipos de assinaturas de acesso compartilhado: SAS de delegação de usuário, SAS de serviço e SAS de conta.

Como prática recomendada de segurança, recomendamos que você use Microsoft Entra credenciais em vez da chave da conta de armazenamento, que pode ser comprometida com mais facilidade. Se o design do aplicativo exigir assinaturas de acesso compartilhado, use Microsoft Entra credenciais para criar uma SAS de delegação de usuário, quando possível.

Quando o acesso à Chave Compartilhada não for permitido para a conta de armazenamento, um token SAS de serviço ou um token SAS de conta não será permitido em uma solicitação para o Armazenamento de Blobs. Para saber mais, confira Entender como a não permissão de Chave Compartilhada afeta tokens SAS.

SAS de delegação do usuário

Uma SAS de delegação de usuário é protegida com Microsoft Entra credenciais e também pelas permissões especificadas para a SAS.

Chamar a Get Page Ranges operação usando um token SAS delegado a um recurso de contêiner ou blob requer a permissão Leitura (r) como parte do token SAS de delegação do usuário.

Para saber mais sobre a SAS de delegação de usuário, consulte Create uma SAS de delegação de usuário.

SAS de serviço

Uma SAS de serviço é protegida com a chave da conta de armazenamento. Uma SAS de serviço delega acesso a um recurso em um único serviço de Armazenamento do Azure, como o armazenamento de blobs.

Chamar a Get Page Ranges operação usando um token SAS delegado a um contêiner ou recurso de blob requer a permissão Leitura (r) como parte do token SAS de serviço.

Para saber mais sobre a SAS de serviço, consulte Create uma SAS de serviço.

SAS de Conta

Uma SAS de conta é protegida com a chave da conta de armazenamento. Uma SAS de conta delega acesso a recursos em um ou mais dos serviços de armazenamento. Todas as operações disponíveis através de uma SAS de serviço ou de delegação do usuário também estão disponíveis por meio de uma SAS de conta.

A tabela a seguir indica o tipo de recurso assinado e as permissões assinadas a serem especificadas ao delegar o acesso:

Operação	Serviço assinado	Tipo de recurso assinado	Permissão assinada
Get Page Ranges	Blob (b)	Objeto (o)	Leitura (r)

Para saber mais sobre a SAS da conta, consulte Create uma SAS de conta.

A Get Page Ranges operação dá suporte à autorização de Chave Compartilhada. A autorização com chaves de conta não é recomendada para a maioria dos cenários, pois é menos segura.

A Microsoft recomenda não permitir a autorização de Chave Compartilhada para a conta de armazenamento quando possível. Para obter mais informações, consulte Impedir autorização com chave compartilhada.

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

Compartilhar via