Elenca intervalli

L'operazione List Ranges restituisce l'elenco degli intervalli validi per un file. Questa operazione è supportata nella versione 2025-05-05 e successive per condivisioni file con protocollo NFS abilitato. A partire dalla versione 2026-10-06, questa operazione supporta i token di continuazione tramite i marker parametri e.maxresults

Disponibilità del protocollo

Protocollo di condivisione file abilitato Disponibile
SMB Sì
NFS Sì

Richiedi

La richiesta di List Ranges viene costruita nel modo seguente. È consigliabile usare HTTPS.

metodo URI della 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?comp=rangelist&maxresults=<int> HTTP/1.1
GET https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string>&maxresults=<int> HTTP/1.1
GET https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string> 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 visualizzati nell'URI della richiesta con i propri, come indicato di seguito:

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

Per dettagli sulle restrizioni sulla denominazione dei percorsi, vedi Denominazione e riferimento di condivisioni, directory, file e metadati.

Parametri URI

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

Parametro Description
sharesnapshot Optional. Versione 2017-04-17 e successive. Il sharesnapshot parametro è un valore opaco DateTime che, quando presente, specifica lo snapshot della condivisione da interrogare per il file.
timeout Optional. Il parametro timeout è espresso in secondi. Per maggiori informazioni, vedi Impostare timeout per operazioni File di Azure.
prevsharesnapshot Opzionale nella versione 2020-02-10 e successive. Il prevsharesnapshot parametro è un valore opaco DateTime che, quando presente, specifica lo snapshot precedente.

Quando sia questo parametro che sharesnapshot sono presenti, la risposta conterrà solo gli intervalli di pagine che sono stati modificati tra i due snapshot. Quando è presente solo prevsharesnapshot una sola cosa, la risposta conterrà solo gli intervalli di pagina che sono stati modificati tra questo snapshot e la condivisione in tempo reale.

Le pagine modificate includono pagine aggiornate e cancellate.
maxresults Optional. Versione 2026-10-06 e successive. Specifica il numero massimo di intervalli da restituire in una pagina di risposta. Se maxresults non viene specificato, il servizio tenta di restituire tutti i range rimanenti in un'unica risposta, il che può comportare un timeout per file molto grandi.

Se maxresults è superiore a 10.000, il servizio lo considera 10.000. Se si imposta maxresults su un valore minore o uguale a zero, viene restituito il codice di risposta di errore 400 (richiesta non valida).
marker Optional. Versione 2026-10-06 e successive. Un valore di stringa che identifica la parte della lista da restituire con la prossima List Ranges operazione. Quando una risposta include NextMarker, usa quel valore come marker in una chiamata successiva per continuare l'enumerazione.

Se marker è specificato senza maxresults, il servizio inizia comunque l'enumerazione dalla posizione del marcatore, ma non emette un altro NextMarker.

Il valore dell'indicatore è opaco per il client.

Header di richiesta

Le intestazioni di richiesta obbligatorie e facoltative sono descritte nelle tabelle seguenti:

Intestazioni di richiesta comuni

Intestazione della richiesta Description
Authorization Required. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
Date oppure x-ms-date Required. Specifica l'ora UTC (Coordinated Universal Time) per la richiesta. 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 utilizzare per questa richiesta. Questa operazione è supportata nella versione 2025-05-05 e successive per condivisioni file con protocollo NFS abilitato. I parametri del token di continuazione (marker e maxresults) sono disponibili per la versione 2026-10-06 e successive.

Per ulteriori informazioni, consultare Controllo delle versioni per i servizi di Archiviazione di Azure.
Range Optional. Specifica l'intervallo di byte su cui elencare gli intervalli, inclusi. Se omesso, tutti gli intervalli del file vengono restituiti.
x-ms-range Optional. Specifica l'intervallo di byte su cui elencare gli intervalli, inclusi.

Se sono specificati entrambi gli Range intestatori e x-ms-range , il servizio utilizza il valore di x-ms-range. Vedi Specificare l'intestazione range per operazioni File di Azure per maggiori informazioni.
x-ms-lease-id:<ID> Optional. Versione 2019-02-02 e successive. Se l'intestazione è specificata, l'operazione verrà eseguita solo se il lease del file è attualmente attivo e l'ID del lease specificato nella richiesta corrisponde a quello del file. In caso contrario, l'operazione ha esito negativo con codice di stato 412 (precondizione non riuscita).

Questa intestazione viene ignorata se il file si trova in una condivisione file con protocollo NFS abilitato, che non supporta i lease di file.
x-ms-client-request-id Optional. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log quando viene configurata la registrazione. È consigliabile usare questa intestazione per correlare le attività sul lato client alle richieste ricevute dal server. Per altre informazioni, vedere Monitorare File di Azure.
x-ms-file-request-intent Obbligatorio se Authorization intestazione specifica un token OAuth. Il valore accettabile è backup. Questa intestazione specifica che il 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 successive.
x-ms-allow-trailing-dot: { <Boolean> } Optional. Versione 2022-11-02 e successive. Il valore booleano specifica se un punto finale presente nell'URL della richiesta deve essere tagliato o meno.

Questa intestazione viene ignorata se la destinazione si trova in una condivisione file con protocollo NFS abilitato, che supporta il punto finale per impostazione predefinita.

Per altre informazioni, vedere Denominazione e riferimento a condivisioni, directory, file e metadati.
x-ms-file-support-rename: { <Boolean> } Optional. Supportato dalla versione 2024-05-04 e successiva. Questo header è consentito solo quando prevsharesnapshot è presente il parametro di query. Il valore booleano determina se gli intervalli modificati per un file devono essere elencati quando la posizione del file nello snapshot precedente è diversa da quella nell'URI di richiesta, a seguito di operazioni di rinominazione o spostamento. Se il valore è true, verranno restituiti gli intervalli modificati validi per il file. Se il valore è false, l'operazione genererà un errore con una risposta 409 (Conflitto). Il valore predefinito è false.

Intestazioni di richiesta solo SMB

None.

Intestazioni di richiesta solo NFS

None.

Corpo della richiesta

None.

Risposta

La risposta include un codice di stato HTTP, un set di intestazioni di risposta e un corpo della risposta in formato XML.

Codice di stato

Un'operazione riuscita restituisce il codice di stato 200 (OK). Per informazioni sui codici di stato, vedere Stato e codici di errore.

Intestazioni di risposta

La risposta per questa operazione include le intestazioni nelle tabelle seguenti. La risposta può includere anche intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1 .

Intestazioni di risposta comuni

Intestazione della risposta Description
Last-Modified Data/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 Le dimensioni del file in byte. Quando prevsharesnapshot è presente, allora il valore descrive la dimensione del file in ( sharesnapshot se il sharesnapshot parametro di query è presente). Altrimenti, descrive la dimensione del file live.
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 ulteriori informazioni, consulta Risoluzione dei problemi relativi alle operazioni API.
x-ms-version Indica la versione di File di Azure utilizzata per eseguire la richiesta.
Date oppure 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.

Intestazioni di risposta solo SMB

None.

Intestazioni di risposta solo NFS

None.

Corpo della risposta

Il corpo della risposta include un elenco di intervalli validi non sovrapposti, ordinati per intervallo di indirizzi crescente. Il formato del corpo della risposta è il seguente.

<?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 range del file è stato cancellato, il corpo di risposta non includerà nessun intervallo.

Quando maxresults è specificato nella richiesta e rimangono intervalli aggiuntivi, il corpo di risposta include un NextMarker elemento. Il formato di questa risposta è il seguente:

<?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>

L'elemento NextMarker viene omesso quando non rimangono più intervalli o quando maxresults non è specificato nella richiesta. Per continuare l'enumerazione, fornisci il NextMarker valore come marker parametro nella prossima List Ranges richiesta.

Se prevsharesnapshot è specificato, la risposta include solo le pagine che differiscono tra lo snapshot di destinazione (o il file live) e lo snapshot precedente. I poligoni restituiti includono entrambi quelli aggiornati o liberati. 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 è specificato, il corpo della risposta non includerà nessun intervallo.

Authorization

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

Osservazioni:

Gli offset di inizio e fine dei byte per ogni intervallo sono inclusi. Consulta gli esempi di Operazioni di Aggiornamento Range e Operazioni di Pulizia di Distanza per il Put Range. Questi esempi mostrano quali intervalli vengono restituiti se scrivi o cancelli un intervallo di 512 byte non allineati dal file.

In un file altamente frammentato con un gran numero di scritture, una List Ranges richiesta può fallire a causa di un timeout interno del server. Le applicazioni che recuperano intervalli di un file con un gran numero di operazioni di scrittura dovrebbero recuperare un sottoinsieme di intervalli alla volta.

A partire dalla versione 2020-02-10, puoi chiamare List Ranges con un prevsharesnapshot parametro. Questo restituisce gli intervalli che differiscono tra il file live e uno snapshot, o tra due snapshot del file su snapshot. Utilizzando queste differenze di intervallo, puoi recuperare uno snapshot incrementale di un file. Gli snapshot incrementali sono un modo economico per fare backup dei file se vuoi implementare una soluzione di backup tua.

A partire dalla versione 2026-10-06, puoi chiamare List Ranges con un maxresults parametro per limitare il numero di intervalli restituiti in una singola risposta. Se la risposta non include tutti i restanti intervalli, un NextMarker elemento viene incluso nel corpo della risposta. Puoi quindi usare questo valore come parametro marker in una chiamata successiva List Ranges per continuare l'enumerazione da dove la risposta precedente si era interrotta.

Quando si utilizzano i token di continuazione, si noti quanto segue:

  • Se marker è specificato senza maxresults, il servizio restituisce dalla posizione del marcatore fino alla fine del file senza emettere un altro NextMarker.
  • Se la richiesta originale includeva un'intestazione Range or x-ms-range , le richieste di continuazione successive dovrebbero includere lo stesso header di intervallo. Il marker valore ha significato solo nel contesto dell'intervallo originale.
  • Se marker si fa riferimento a una posizione oltre la fine del file, il servizio restituisce 400 (Richiesta cattiva).

Alcune operazioni su un file causano List Ranges fallimento quando viene chiamato per recuperare uno snapshot incrementale. Il servizio restituisce i seguenti sposi:

  • 404 (Non trovato) se richiami un file che non esiste in uno degli snapshot (o in tempo reale, se sharesnapshot non è specificato).
  • 409 (Conflitto) se si chiama un file che era il bersaglio di una copia di sovrascrittura dopo lo snapshot, specificato da prevsharesnapshot.
  • 409 (Conflitto) se richiami un file che è stato eliminato e ricreato con lo stesso nome e posizione, dopo che l'istantaneo specificato da prevsharesnapshot è stato scattato.

Vedere anche

operazioni di su file

  • Last updated on