Intervalos de Lista

Artigo
03/29/2023

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

Disponibilidade do protocolo

Protocolo de partilha de ficheiros ativado	Disponível
SMB
NFS

Pedir

Pode construir o pedido da List Ranges seguinte forma. É recomendado HTTPS.

Método	URI do pedido	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 de caminho mostrados no URI do pedido pelo seu, da seguinte forma:

Componente caminho	Description
`myaccount`	O nome da sua conta de armazenamento.
`myshare`	O nome da partilha de ficheiros.
`mydirectorypath`	Opcional. O caminho para o diretório principal.
`myfile`	O nome do ficheiro.

Para obter detalhes sobre as restrições de nomenclatura de caminhos, veja Naming and referencing shares, directories, files, and metadata (Atribuir nomes e referenciar partilhas, diretórios, ficheiros e metadados).

Parâmetros do URI

Pode especificar os seguintes parâmetros adicionais no URI do pedido.

Parâmetro	Description
`sharesnapshot`	Opcional. Versão 2017-04-17 e posterior. O `sharesnapshot` parâmetro é um valor opaco `DateTime` que, quando presente, especifica o instantâneo de partilha a consultar para o ficheiro.
`timeout`	Opcional. O `timeout` parâmetro é expresso em segundos. Para obter mais informações, veja Setting timeouts for Ficheiros do Azure operations (Definir tempos limite para operações de Ficheiros 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 este parâmetro e `sharesnapshot` estão presentes, a resposta conterá apenas intervalos de páginas que foram alterados entre os dois instantâneos. Quando apenas `prevsharesnapshot` está presente, a resposta conterá apenas intervalos de páginas que foram alterados entre este instantâneo e a partilha em direto. As páginas alteradas incluem páginas atualizadas e desmarcadas.

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Cabeçalho do pedido	Description
`Authorization`	Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
`x-ms-version`	Necessário para todos os pedidos autorizados. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.
`Range`	Opcional. Especifica o intervalo de bytes sobre o qual pretende listar intervalos, inclusive. Se for omitido, todos os intervalos do ficheiro serão devolvidos.
`x-ms-range`	Opcional. Especifica o intervalo de bytes sobre o qual pretende listar intervalos, inclusive. Se os `Range` cabeçalhos e `x-ms-range` forem especificados, o serviço utiliza o valor de `x-ms-range`. Veja Especificar o cabeçalho do intervalo para operações de Ficheiros 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 só será efetuada se a concessão do ficheiro estiver atualmente ativa e o ID de concessão especificado no pedido corresponder ao do ficheiro. Caso contrário, a operação falha com o código de estado 412 (Falha na Pré-condição).
`x-ms-client-request-id`	Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar Ficheiros do Azure.
`x-ms-file-request-intent`	Necessário se o `Authorization` cabeçalho especificar um token OAuth. O valor aceitável é `backup`. Este cabeçalho especifica que o `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` ou `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` deve ser concedido se estiver incluído na política RBAC atribuída à identidade autorizada com 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 Booleano especifica se um ponto à direita presente no URL do pedido deve ser cortado ou não. Para obter mais informações, veja Naming and referencing shares, directories, files, and metadata (Atribuir nomes e referenciar partilhas, diretórios, ficheiros e metadados).

Corpo do pedido

Nenhum.

Resposta

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

Código de estado

Uma operação bem-sucedida devolve o código de estado 200 (OK). Para obter informações sobre códigos de estado, veja Códigos de estado e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os seguintes cabeçalhos. 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 em que o ficheiro foi modificado pela última vez. Qualquer operação que modifique o ficheiro, incluindo uma atualização dos metadados ou propriedades do ficheiro, altera a hora da última modificação do ficheiro.
`ETag`	Contém `ETag` um valor que representa a versão do ficheiro, em aspas.
`x-ms-content-length`	O tamanho do ficheiro em bytes. Quando `prevsharesnapshot` estiver presente, o valor descreve o tamanho do ficheiro no `sharesnapshot` (se o `sharesnapshot` parâmetro de consulta estiver presente). Caso contrário, descreve o tamanho do ficheiro em direto.
`x-ms-request-id`	Este cabeçalho identifica exclusivamente o pedido que foi feito e pode ser utilizado para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API.
`x-ms-version`	Indica a versão do Ficheiros do Azure utilizada para executar o pedido.
`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 este valor.
`x-ms-client-request-id`	Pode utilizar este cabeçalho para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do `x-ms-client-request-id` cabeçalho, se estiver presente no pedido. O valor é, no máximo, 1024 carateres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente no pedido, este cabeçalho não estará presente na resposta.

Corpo da resposta

O corpo da resposta inclui uma lista de intervalos válidos não sobrepostos, ordenados 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 ficheiro tiver sido limpo, o corpo da resposta não incluirá intervalos.

Se prevsharesnapshot for especificada, a resposta inclui apenas as páginas que diferem entre o instantâneo de destino (ou o ficheiro em direto) e o instantâneo anterior. Os intervalos devolvidos incluem ambos os intervalos que foram atualizados ou que foram limpos. O formato desta 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 ficheiro tiver sido limpo e o prevsharesnapshot parâmetro não for especificado, o corpo da resposta não incluirá intervalos.

Autorização

Apenas o proprietário da conta pode chamar esta operação.

Observações

Os desvios de bytes de início e de fim para cada intervalo são inclusivos. Veja os exemplos de Operações de Atualização de Intervalos e Operações Desmarcadas do Intervalo para Colocar Intervalo. Estes exemplos mostram que intervalos são devolvidos se escrever ou limpar um intervalo de bytes de 512 não alinhados do ficheiro.

Num ficheiro altamente fragmentado com um grande número de escritas, um List Ranges pedido pode falhar devido a um tempo limite interno do servidor. As aplicações que obtêm intervalos de um ficheiro com um grande número de operações de escrita devem obter um subconjunto de intervalos de cada vez.

A partir da versão 2020-02-10, pode chamar List Ranges com um prevsharesnapshot parâmetro. Isto devolve os intervalos que diferem entre o ficheiro em direto e um instantâneo ou entre dois instantâneos do ficheiro em instantâneos. Ao utilizar estas diferenças de intervalo, pode obter um instantâneo incremental de um ficheiro. Os instantâneos incrementais são uma forma económica de criar cópias de segurança de ficheiros se quiser implementar a sua própria solução de cópia de segurança.

Determinadas operações num ficheiro fazem List Ranges com que falhe quando é chamado para obter um instantâneo incremental. O serviço devolve:

404 (Não Encontrado) se chamar um ficheiro que não existe num dos instantâneos (ou em direto, se sharesnapshot não for especificado).
409 (Conflito) se chamar um ficheiro que foi o alvo de uma Cópia de substituição após o instantâneo, especificado por prevsharesnapshot.
409 (Conflito) se chamar um ficheiro que foi eliminado e recriado com o mesmo nome e localização, depois de o instantâneo especificado por prevsharesnapshot ter sido tirado.

Ver também

Operações em ficheiros