Listar intervalos

Artigo
03/29/2023

A operação List Ranges retorna a lista de intervalos válidos para um arquivo.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado	Disponível
SMB
NFS

Solicitação

Você pode construir a solicitação da List Ranges seguinte maneira. HTTPS é recomendado.

Método	URI da solicitação	Versão HTTP
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime>`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime>`	HTTP/1.1

Substitua os componentes do caminho mostrados no URI da solicitação pelos seus próprios, como segue:

Componente Demarcador	Descrição
`myaccount`	O nome da sua conta de armazenamento.
`myshare`	O nome do seu compartilhamento de arquivo.
`mydirectorypath`	Opcional. O caminho para o diretório pai.
`myfile`	O nome do arquivo.

Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados.

Parâmetros do URI

Você pode especificar os seguintes parâmetros adicionais no URI de solicitação.

Parâmetro	Descrição
`sharesnapshot`	Opcional. Versão 2017-04-17 e posterior. O `sharesnapshot` parâmetro é um valor opaco `DateTime` que, quando presente, especifica o compartilhamento instantâneo para consultar o arquivo.
`timeout`	Opcional. O parâmetro `timeout` é expresso em segundos. Para obter mais informações, consulte Configurando tempos limite para operações de Arquivos do Azure.
`prevsharesnapshot`	Opcional na versão 2020-02-10 e posterior. O `prevsharesnapshot` parâmetro é um valor opaco `DateTime` que, quando presente, especifica o instantâneo anterior. Quando esse parâmetro e `sharesnapshot` estiverem presentes, a resposta conterá apenas intervalos de página que foram alterados entre os dois instantâneos. Quando apenas `prevsharesnapshot` estiver presente, a resposta conterá apenas intervalos de páginas que foram alterados entre esse instantâneo e o compartilhamento dinâmico. As páginas alteradas incluem páginas atualizadas e desmarcadas.

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. 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 omitido, então todos os intervalos para o arquivo serão retornados.
`x-ms-range`	Opcional. Especifica o intervalo de bytes no qual listar intervalos, inclusive. Se ambos os cabeçalhos `Range` e`x-ms-range` são especificados, o serviço usa o valor de `x-ms-range`. Consulte Especificando o cabeçalho de intervalo para operações de Arquivos do Azure para obter mais informações.
`x-ms-lease-id:<ID>`	Opcional. Versão 2019-02-02 e posterior. Se o cabeçalho for especificado, a operação será executada somente se a concessão do arquivo estiver ativa no momento e a ID de concessão especificada na solicitação corresponder à do arquivo. Caso contrário, a operação falhará com status código 412 (Falha na pré-condição).
`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 quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar Arquivos do Azure.
`x-ms-file-request-intent`	Obrigatório se `Authorization` o cabeçalho especificar um token OAuth. O valor aceitável é `backup`. Esse cabeçalho especifica que o `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` ou `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` deve ser concedido se eles forem incluídos na política RBAC atribuída à identidade autorizada usando o `Authorization` cabeçalho . Disponível para a versão 2022-11-02 e posterior.
`x-ms-allow-trailing-dot: { <Boolean> }`	Opcional. Versão 2022-11-02 e posterior. O valor booliano especifica se um ponto à direita presente na URL de solicitação deve ser cortado ou não. Para obter mais informações, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados.

Corpo da solicitação

Nenhum.

Resposta

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

Código de status

Uma operação bem-sucedida retorna o código de status 200 (OK). Para obter 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 HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de resposta	Descrição
`Last-Modified`	A data/hora que o arquivo foi modificado pela última vez. Qualquer operação que modifique o arquivo, incluindo uma atualização dos metadados ou propriedades do arquivo, altera a hora da última modificação do arquivo.
`ETag`	O `ETag` contém um valor que representa a versão do arquivo, entre aspas.
`x-ms-content-length`	O tamanho do arquivo em bytes. Quando `prevsharesnapshot` estiver presente, o valor descreverá o tamanho do arquivo no `sharesnapshot` (se o `sharesnapshot` parâmetro de consulta estiver presente). Caso contrário, ele descreve o tamanho do arquivo ativo.
`x-ms-request-id`	Esse cabeçalho identifica exclusivamente a solicitação que foi feita e pode ser usado para solucionar problemas da solicitação. Para obter mais informações, consulte Solução de problemas de operações de API.
`x-ms-version`	Indica a versão do Arquivos do Azure usada para executar a solicitação.
`Date` ou `x-ms-date`	Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
`x-ms-client-request-id`	Você pode usar esse cabeçalho 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. O valor é, no máximo, 1024 caracteres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Corpo da resposta

O corpo de resposta inclui uma lista de intervalos não sobreposta, ordenada pelo aumento direcionado ao intervalo. O formato do corpo da resposta é o seguinte.

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

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

Se prevsharesnapshot for especificado, a resposta incluirá apenas as páginas que diferem entre o instantâneo de destino (ou o arquivo ativo) e o instantâneo anterior. Os intervalos retornados incluem os dois intervalos que foram atualizados ou que foram limpos. O formato dessa resposta é o seguinte:

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

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

Autorização

Somente o proprietário da conta pode chamar essa operação.

Comentários

Os deslocamentos de bytes iniciais e finais para cada intervalo são inclusivos. Consulte os exemplos operações de atualização de intervalo e operações de limpeza de intervalo para Colocar intervalo. Esses exemplos mostram quais intervalos serão retornados se você gravar ou limpar um intervalo de bytes de 512 não alinhados do arquivo.

Em um arquivo altamente fragmentado com um grande número de gravações, uma solicitação List Ranges pode falhar devido a um tempo limite de servidor interno. Os intervalos de recuperação de aplicativos de um arquivo com um grande número de operações de gravação devem recuperar um subconjunto de intervalos ao mesmo tempo.

A partir da versão 2020-02-10, você pode chamar List Ranges com um prevsharesnapshot parâmetro . Isso retorna os intervalos que diferem entre o arquivo dinâmico e um instantâneo ou entre dois instantâneos do arquivo em instantâneos. Usando essas diferenças de intervalo, você pode recuperar uma instantâneo incremental de um arquivo. Instantâneos incrementais são uma maneira econômica de fazer backup de arquivos se você quiser implementar sua própria solução de backup.

Determinadas operações em um arquivo causam List Ranges falha quando ele é chamado para recuperar um instantâneo incremental. O serviço retorna:

404 (Não Encontrado) se você chamar em um arquivo que não existe em um dos instantâneos (ou ativo, se sharesnapshot não for especificado).
409 (Conflito) se você chamar em um arquivo que foi o destino de uma Cópia de substituição após o instantâneo, especificado por prevsharesnapshot.
409 (Conflito) se você chamar em um arquivo que foi excluído e recriado com o mesmo nome e local, depois que o instantâneo especificado por prevsharesnapshot foi obtido.

Confira também

Operações em arquivos