List Ranges

Articolo
03/29/2023

L'operazione List Ranges restituisce l'elenco degli intervalli validi per un file.

Disponibilità del protocollo

Protocollo di condivisione file abilitato	Disponibile
SMB
NFS

Richiesta

È possibile costruire la List Ranges richiesta come indicato di seguito. È consigliato il protocollo HTTPS.

Metodo	URI richiesta	Versione 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

Sostituire i componenti del percorso mostrati nell'URI di richiesta con valori personalizzati, come illustrato di seguito:

Componente percorso	Descrizione
`myaccount`	nome dell'account di archiviazione.
`myshare`	Nome della condivisione file.
`mydirectorypath`	Facoltativa. Percorso della directory padre.
`myfile`	Nome del file.

Per informazioni dettagliate sulle restrizioni di denominazione del percorso, vedere Denominazione e riferimento a condivisioni, directory, file e metadati.

Parametri URI

È possibile specificare i parametri aggiuntivi seguenti nell'URI della richiesta.

Parametro	Descrizione
`sharesnapshot`	Facoltativa. Versione 2017-04-17 e successiva. Il `sharesnapshot` parametro è un valore opaco `DateTime` che, quando presente, specifica lo snapshot di condivisione da eseguire per la query per il file.
`timeout`	Facoltativa. Il parametro `timeout` viene espresso in secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di File di Azure.
`prevsharesnapshot`	Facoltativo nella versione 2020-02-10 e versioni successive. Il `prevsharesnapshot` parametro è un valore opaco `DateTime` che, quando presente, specifica lo snapshot precedente. Quando entrambi questi parametri e `sharesnapshot` sono presenti, la risposta conterrà solo intervalli di pagine modificati tra i due snapshot. Quando è presente solo `prevsharesnapshot` la risposta conterrà solo intervalli di pagine modificati tra questo snapshot e la condivisione live. Le pagine modificate includono pagine aggiornate e cancellate.

Intestazioni della richiesta

Nella seguente tabella vengono descritte le intestazioni di richiesta obbligatorie e facoltative.

Intestazione della richiesta	Descrizione
`Authorization`	Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`Date` o `x-ms-date`	Obbligatorio. Specifica la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`x-ms-version`	Obbligatorio per tutte le richieste autorizzate. Specifica la versione dell'operazione da usare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
`Range`	Facoltativa. Specifica l'intervallo di byte su cui elencare gli intervalli, in modo inclusivo. Se omesso, verranno restituiti tutti gli intervalli per il file.
`x-ms-range`	Facoltativa. Specifica l'intervallo di byte su cui elencare gli intervalli, in modo inclusivo. Se le intestazioni `Range` e `x-ms-range` sono entrambe specificate, il servizio usa il valore di `x-ms-range`. Per altre informazioni, vedere Specifica dell'intestazione dell'intervallo per le operazioni di File di Azure.
`x-ms-lease-id:<ID>`	Facoltativa. Versione 2019-02-02 e successiva. Se l'intestazione è specificata, l'operazione verrà eseguita solo se il lease del file è attualmente attivo e l'ID lease specificato nella richiesta corrisponde a quello del file. In caso contrario, l'operazione non riesce con il codice di stato 412 (Precondizione non riuscita).
`x-ms-client-request-id`	Facoltativa. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log quando la registrazione è configurata. È consigliabile usare questa intestazione per correlare le attività lato client con le richieste ricevute dal server. Per altre informazioni, vedere Monitorare File di Azure.
`x-ms-file-request-intent`	Obbligatorio se `Authorization` l'intestazione specifica un token OAuth. Il valore accettabile è `backup`. Questa intestazione specifica che l'oggetto `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` o `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` deve essere concesso se sono inclusi nei criteri di controllo degli accessi in base al ruolo assegnati all'identità autorizzata usando l'intestazione `Authorization` . Disponibile per la versione 2022-11-02 e versioni successive.
`x-ms-allow-trailing-dot: { <Boolean> }`	Facoltativa. Versione 2022-11-02 e versioni successive. Il valore booleano specifica se un punto finale presente nell'URL della richiesta deve essere tagliato o meno. Per altre informazioni, vedere Denominazione e riferimenti a condivisioni, directory, file e metadati.

Testo della richiesta

Nessuno.

Risposta

Nella risposta sono inclusi un codice di stato HTTP, un set di intestazioni di risposta e il corpo della risposta nel formato XML.

Codice stato

Un'operazione completata correttamente restituisce 200 (OK). Per informazioni sui codici di stato, vedere Codici di stato e di errore.

Intestazioni di risposta

Nella risposta per questa operazione sono incluse le intestazioni riportate di seguito; La risposta può includere anche intestazioni HTTP aggiuntive e standard. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Intestazione risposta	Descrizione
`Last-Modified`	Data e ora dell'ultima modifica del file. Qualsiasi operazione che modifica il file, incluso un aggiornamento dei metadati o delle proprietà del file, modifica l'ora dell'ultima modifica del file.
`ETag`	Contiene `ETag` un valore che rappresenta la versione del file, tra virgolette.
`x-ms-content-length`	Dimensioni del file, in byte. Quando `prevsharesnapshot` è presente, il valore descrive le dimensioni del file in `sharesnapshot` corrispondenza di (se il `sharesnapshot` parametro di query è presente). In caso contrario, descrive le dimensioni del file attivo.
`x-ms-request-id`	Questa intestazione identifica in modo univoco la richiesta effettuata e può essere usata per la risoluzione dei problemi della richiesta. Per altre informazioni, vedere Risoluzione dei problemi relativi alle operazioni api.
`x-ms-version`	Indica la versione di File di Azure utilizzata per eseguire la richiesta.
`Date` o `x-ms-date`	Valore di data/ora UTC che indica l'ora in cui è stata avviata la risposta. Il servizio genera questo valore.
`x-ms-client-request-id`	È possibile usare questa intestazione per risolvere i problemi relativi alle richieste e alle risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione `x-ms-client-request-id` , se presente nella richiesta. Il valore è al massimo 1024 caratteri ASCII visibili. Se l'intestazione `x-ms-client-request-id` non è presente nella richiesta, questa intestazione non sarà presente nella risposta.

Corpo della risposta

Il corpo della risposta include un elenco di intervalli validi non sovrapposti, in ordine crescente in base all'intervallo di indirizzi. Il formato del corpo della risposta è quello indicato di seguito.

<?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 l'intero set di intervalli del file è stato cancellato, il corpo della risposta non includerà intervalli.

Se prevsharesnapshot viene specificato, la risposta include solo le pagine che differiscono tra lo snapshot di destinazione (o il file attivo) e lo snapshot precedente. Gli intervalli restituiti includono entrambi gli intervalli aggiornati o cancellati. Il formato di questa risposta è il seguente:

<?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 l'intero set di pagine del file è stato cancellato e il prevsharesnapshot parametro non viene specificato, il corpo della risposta non includerà intervalli.

Autorizzazione

Solo il proprietario dell'account può chiamare questa operazione.

Commenti

Gli offset di byte di inizio e fine per ogni intervallo sono inclusi. Vedere gli esempi di operazioni di aggiornamento intervallo e operazioni di cancellazione intervallo per Put Range. Questi esempi mostrano gli intervalli restituiti se si scrive o si cancella un intervallo di byte non allineato a 512 dal file.

In un file molto frammentato con un numero elevato di scritture, una richiesta List Ranges può avere esito negativo a causa di un timeout del server interno. Le applicazioni che recuperano gli intervalli di un file con un numero elevato di operazioni di scrittura devono recuperare un sottoinsieme di intervalli alla volta.

A partire dalla versione 2020-02-10, è possibile chiamare List Ranges con un prevsharesnapshot parametro . In questo modo vengono restituiti gli intervalli che differiscono tra il file live e uno snapshot o tra due snapshot del file negli snapshot. Usando queste differenze di intervallo, è possibile recuperare uno snapshot incrementale di un file. Gli snapshot incrementali rappresentano un modo conveniente per eseguire il backup dei file se si vuole implementare una soluzione di backup personalizzata.

Alcune operazioni su un file hanno List Ranges esito negativo quando viene chiamato per recuperare uno snapshot incrementale. Il servizio restituisce:

404 (Non trovato) se si chiama su un file che non esiste in uno degli snapshot (o in tempo reale, se sharesnapshot non è specificato).
409 (Conflitto) se si chiama su un file di destinazione di una copia sovrascrittura dopo lo snapshot, specificato da prevsharesnapshot.
409 (Conflitto) se si chiama su un file eliminato e ricreato con lo stesso nome e percorso, dopo che è stato creato lo snapshot specificato da prevsharesnapshot .

Vedi anche

Operazioni sui file