Listar intervalos

A operação List Ranges retorna a lista de intervalos válidos para um arquivo. Essa operação tem suporte na versão 2025-05-05 e posterior para Compartilhamentos de Arquivos com o protocolo NFS habilitado. A partir da versão 2026-10-06, esta operação suporta tokens de continuação via os marker parâmetros e.maxresults

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado Disponível
SMB Sim
NFS Sim

Pedir

A solicitação List Ranges é construída da seguinte maneira. Recomendamos que você use HTTPS.

Método URI de solicitação Versão HTTP
OBTER https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist HTTP/1.1
OBTER https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&maxresults=<int> HTTP/1.1
OBTER https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string>&maxresults=<int> HTTP/1.1
OBTER https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string> HTTP/1.1
OBTER https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist HTTP/1.1
OBTER https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime> HTTP/1.1
OBTER https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime> HTTP/1.1

Substitua os componentes de caminho mostrados no URI da solicitação por seus próprios, da seguinte maneira:

Componente path Descrição
myaccount O nome da sua conta de armazenamento.
myshare O nome do compartilhamento de arquivos.
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 a compartilhamentos, diretórios, arquivos e metadados.

Parâmetros de URI

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

Parâmetro Descrição
sharesnapshot Opcional. Versão 2017-04-17 e posterior. O parâmetro sharesnapshot é um valor opaco DateTime que, quando presente, especifica o instantâneo de compartilhamento a ser consultado para o arquivo.
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações de Arquivos do Azure.
prevsharesnapshot Opcional na versão 2020-02-10 e posterior. O parâmetro prevsharesnapshot é 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áginas 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 ao vivo.

As páginas alteradas incluem páginas atualizadas e desmarcadas.
maxresults Opcional. Versão 2026-10-06 e posteriores. Especifica o número máximo de intervalos a serem retornados em uma página de resposta. Se maxresults não for especificado, o serviço tenta retornar todos os intervalos restantes em uma única resposta, o que pode resultar em um timeout para arquivos muito grandes.

Se maxresults for maior que 10.000, o serviço o considera como 10.000. Definir maxresults como um valor menor ou igual a zero resulta em código de resposta de erro 400 (Solicitação Incorreta).
marker Opcional. Versão 2026-10-06 e posteriores. Um valor de string que identifica a parte da lista a ser retornada na próxima List Ranges operação. Quando uma resposta inclui NextMarker, use esse valor como marker em uma chamada subsequente para continuar a enumeração.

Se marker for especificado sem maxresults, o serviço ainda inicia a enumeração a partir da posição do marcador, mas não emite outro NextMarker.

O valor do marcador é opaco para o cliente.

Cabeçalhos de solicitação

Os cabeçalhos de solicitação obrigatórios e opcionais são descritos nas seguintes tabelas:

Cabeçalhos de solicitação comuns

Cabeçalho de solicitação Descrição
Authorization Necessário. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
Date ou x-ms-date Necessário. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para obter mais informações, consulte 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 essa solicitação. Essa operação tem suporte na versão 2025-05-05 e posterior para Compartilhamentos de Arquivos com o protocolo NFS habilitado. Parâmetros do token de continuação (marker e maxresults) estão disponíveis para a versão 2026-10-06 e posteriores.

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 sobre o qual listar intervalos, inclusive. Se omitido, todos os intervalos do arquivo serão retornados.
x-ms-range Opcional. Especifica o intervalo de bytes sobre o qual listar intervalos, inclusive.

Se os cabeçalhos Range e x-ms-range forem especificados, o serviço usará 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 o código de status 412 (Falha na pré-condição).

Esse cabeçalho será ignorado se o arquivo estiver localizado em um Compartilhamento de Arquivos com o protocolo NFS habilitado, que não dá suporte a concessões de arquivo.
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 Necessário se Authorization cabeçalho especificar um token OAuth. O valor aceitável é backup. Esse cabeçalho especifica que os Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action devem ser concedidos se forem incluídos na política RBAC atribuída à identidade autorizada usando o cabeçalho Authorization. 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 da solicitação deve ser cortado ou não.

Esse cabeçalho será ignorado se o destino estiver localizado em um Compartilhamento de Arquivos com o protocolo NFS habilitado, o que dá suporte ao ponto à direita por padrão.

Para obter mais informações, consulte Nomenclatura e referência a compartilhamentos, diretórios, arquivos e metadados.
x-ms-file-support-rename: { <Boolean> } Opcional. Com suporte na versão 2024-05-04 e superior. Esse cabeçalho só é permitido quando prevsharesnapshot parâmetro de consulta está presente. O valor booliano determina se os intervalos alterados para um arquivo devem ser listados quando o local do arquivo no instantâneo anterior é diferente do local no URI de Solicitação, como resultado de operações de renomeação ou movimentação. Se o valor for true, os intervalos alterados válidos para o arquivo serão retornados. Se o valor for falso, a operação resultará em uma falha com a resposta 409 (Conflito). O valor padrão é false.

Cabeçalhos de solicitação somente SMB

Nenhum.

Cabeçalhos de solicitação somente NFS

Nenhum.

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 Status e códigos de erro.

Cabeçalhos de resposta

A resposta dessa operação inclui os cabeçalhos nas tabelas 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 de protocolo HTTP/1.1 .

Cabeçalhos de resposta comuns

Cabeçalho de resposta Descrição
Last-Modified A data/hora em 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 parâmetro de consulta sharesnapshot estiver presente). Caso contrário, ele descreve o tamanho do arquivo ativo.
x-ms-request-id Esse cabeçalho identifica exclusivamente a solicitação 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 dos 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 é igual ao valor do cabeçalho x-ms-client-request-id, se ele estiver presente na solicitação. O valor é, no máximo, 1024 caracteres ASCII visíveis. Se o cabeçalho x-ms-client-request-id não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Cabeçalhos de resposta somente SMB

Nenhum.

Cabeçalhos de resposta somente NFS

Nenhum.

Corpo da resposta

O corpo da resposta inclui uma lista de intervalos válidos não sobrepostos, classificados pelo aumento do intervalo de endereços. 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.

Quando maxresults é especificado na solicitação e restam intervalos adicionais, o corpo da resposta inclui um NextMarker elemento. O formato dessa 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>
  <NextMarker>opaque-string</NextMarker>
</Ranges>

O NextMarker elemento é omitido quando não restam mais intervalos ou quando maxresults não é especificado na solicitação. Para continuar a enumeração, forneça o NextMarker valor como marker parâmetro na próxima List Ranges solicitação.

Se prevsharesnapshot for especificado, a resposta incluirá apenas as páginas que diferem entre o instantâneo de destino (ou o arquivo dinâmico) e o instantâneo anterior. Os intervalos retornados incluem ambos os 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 parâmetro prevsharesnapshot 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.

Observações

Os deslocamentos de bytes de início e término para cada intervalo são inclusivos. Consulte os exemplos de operações de de atualização de intervalo de e de operações de limpeza de intervalo para colocar intervalo. Esses exemplos mostram quais intervalos serão retornados se você gravar ou desmarcar um intervalo de bytes sem sinal de 512 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 interno do servidor. Os aplicativos que recuperam intervalos de um arquivo com um grande número de operações de gravação devem recuperar um subconjunto de intervalos de cada vez.

A partir da versão 2020-02-10, você pode chamar List Ranges com um parâmetro prevsharesnapshot. 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 um 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.

A partir da versão 2026-10-06, você pode chamar List Ranges com um maxresults parâmetro para limitar o número de intervalos retornados em uma única resposta. Se a resposta não incluir todos os intervalos restantes, um NextMarker elemento é incluído no corpo da resposta. Você pode então usar esse valor como marker parâmetro em uma chamada subsequente List Ranges para continuar a enumeração de onde a resposta anterior parou.

Ao usar tokens de continuação, observe o seguinte:

  • Se marker for especificado sem maxresults, o serviço retorna varia da posição do marcador até o final do arquivo sem emitir outro NextMarker.
  • Se a solicitação original incluía um Range cabeçalho de ou, x-ms-range as requisições de continuação subsequentes devem incluir o mesmo cabeçalho de intervalo. O marker valor só é significativo dentro do contexto do intervalo original.
  • Se marker referenciar uma posição além do final do arquivo, o serviço retorna 400 (Solicitação Indevida).

Determinadas operações em um arquivo fazem com que List Ranges falhe quando é chamado para recuperar um instantâneo incremental. O serviço retorna:

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

Consulte também

operações de em arquivos

  • Last updated on