Condividi tramite

Get Page Ranges

  • Articolo

L'operazione Get Page Range restituisce l'elenco di intervalli di pagine validi per un BLOB di pagine o uno snapshot di un BLOB di pagine.

Richiesta

La richiesta Get Page Range può essere costruita come indicato di seguito. È consigliabile usare HTTPS. Sostituire myaccount con il nome dell'account di archiviazione:

URI della richiesta del metodo GET Versione HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>&prevsnapshot=<DateTime>		 HTTP/1.1

URI del servizio di archiviazione emulato

Quando si effettua una richiesta nel servizio di archiviazione emulato, specificare il nome host dell'emulatore e Archiviazione BLOB di Azure porta come 127.0.0.1:10000, seguito dal nome dell'account di archiviazione emulato:

URI della richiesta del metodo GET Versione HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist HTTP/1.1

Per altre informazioni, vedere Usare l'emulatore di archiviazione di Azure per sviluppo e test.

Parametri URI

I parametri aggiuntivi seguenti possono essere specificati nell'URI della richiesta:

Parametro Descrizione
marker Facoltativo, versione 2020-10-02 e versioni successive. Identifica la parte degli intervalli da restituire con l'operazione GetPageRanges successiva. L'operazione restituisce un valore marcatore all'interno del corpo della risposta se gli intervalli restituiti sono incompleti. Il valore del marcatore può quindi essere usato in una chiamata successiva per richiedere il set successivo di intervalli.

Il valore marcatore risulta opaco al client.
maxresults Facoltativo, versione 2020-10-02 e versioni successive. Specifica il numero massimo di intervalli di pagine da restituire. Se la richiesta specifica un valore maggiore di 10.000, il server restituisce fino a 10.000 elementi. Se sono presenti risultati aggiuntivi da restituire, il servizio restituisce un token di continuazione nell'elemento di risposta NextMarker.

L'impostazione maxresults su un valore minore o uguale a zero genera il codice di risposta di errore 400 (richiesta non valida).
snapshot facoltativo. Valore DateTime opaco che, quando presente, specifica lo snapshot BLOB da cui recuperare le informazioni. Per altre informazioni sull'uso di snapshot BLOB, vedere Create uno snapshot di un BLOB.
timeout facoltativo. Espresso in secondi. Per altre informazioni, vedere Impostare timeout per le operazioni di archiviazione BLOB.
prevsnapshot Facoltativo, versione 2015-07-08 e versioni successive. Valore DateTime che specifica che la risposta conterrà solo pagine modificate tra il BLOB di destinazione e lo snapshot precedente. Le pagine modificate includono pagine aggiornate e cancellate. Il BLOB di destinazione può essere uno snapshot, purché lo snapshot specificato da prevsnapshot sia il valore precedente dei due.

Nota: gli snapshot incrementali sono attualmente supportati solo per i BLOB creati o dopo il 1° gennaio 2016.

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, facoltativo per le richieste anonime. 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 facoltativo. Specifica l'intervallo di byte su cui elencare gli intervalli, in modo inclusivo. Se Range viene omesso, vengono restituiti tutti gli intervalli per il BLOB.
x-ms-range facoltativo. Specifica l'intervallo di byte su cui elencare gli intervalli, in modo inclusivo. Se Range e x-ms-range sono entrambi specificati, il servizio usa il valore di x-ms-range. Per altre informazioni, vedere Specificare l'intestazione di intervallo per le operazioni di archiviazione BLOB .
x-ms-lease-id:<ID> facoltativo. Se questa intestazione è specificata, l'operazione viene eseguita solo se vengono soddisfatte entrambe le condizioni seguenti:

- Il lease del BLOB è attualmente attivo.

- ID lease specificato nella richiesta corrisponde all'ID lease del BLOB.

Se questa intestazione è specificata e la condizione non viene soddisfatta, la richiesta ha esito negativo e l'operazione non riesce con il codice di stato 412 (Precondizione non riuscita).
x-ms-previous-snapshot-url Facoltativo, versione 2019-07-07 e versioni successive. Specifica previous-snapshot-url che la risposta conterrà solo pagine modificate tra il BLOB di destinazione e lo snapshot che si trovano nell'URI specificato. Le pagine modificate includono pagine aggiornate e cancellate. Il BLOB di destinazione può essere uno snapshot, purché lo snapshot specificato da questa intestazione sia il precedente dei due.

Nota: gli snapshot incrementali sono attualmente supportati solo per i BLOB creati o dopo il 1° gennaio 2016 e che questa intestazione deve essere usata solo negli scenari dei dischi gestiti. In caso contrario, usare il prevsnapshot parametro .
x-ms-client-request-id facoltativo. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB), registrato nei log di analisi quando è abilitata la registrazione di Azure Analisi archiviazione. È consigliabile usare questa intestazione quando si correlano le attività lato client con le richieste ricevute dal server. Per altre informazioni, vedere Informazioni sulla registrazione di Analisi archiviazione e registrazione di Azure: usare i log per tenere traccia delle richieste di archiviazione di Azure.

Questa operazione supporta anche l'utilizzo delle intestazioni condizionali per ottenere intervalli di pagine solo se viene soddisfatta una determinata condizione. Per altre informazioni, vedere Specificare intestazioni condizionali per le operazioni di archiviazione BLOB.

Testo della richiesta

Nessuno.

Risposta

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

Codice stato

Un'operazione completata correttamente restituisce 200 (OK).

Per altre 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; inoltre, possono essere incluse intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Sintassi Descrizione
Last-Modified Data e ora dell'ultima modifica del Blob. Il formato data è conforme a RFC 1123.

Qualsiasi operazione che comporta la modifica del Blob, incluso un aggiornamento dei metadati o delle proprietà del Blob, comporta la modifica dell'ora dell'ultima modifica del Blob.
ETag Contiene un valore che il client può usare per eseguire l'operazione in modo condizionale. Se la versione della richiesta è 2011-08-18 o successiva, il valore ETag è racchiuso tra virgolette.
x-ms-blob-content-length La dimensione del BLOB in byte.
x-ms-request-id Identifica in modo univoco la richiesta effettuata e può essere usata per risolvere la richiesta. Per altre informazioni, vedere Risolvere i problemi relativi alle operazioni api.
x-ms-version Indica la versione di archiviazione BLOB usata per eseguire la richiesta. Questa intestazione viene restituita per le richieste effettuate rispetto alla versione 2009-09-19 e successive.

Questa intestazione viene restituita anche per le richieste anonime senza una versione specificata se il contenitore è stato contrassegnato per l'accesso pubblico usando l'archiviazione BLOB versione 2009-09-19.
Date Valore di data/ora UTC generato dal servizio, che indica l'ora in cui è stata avviata la risposta.
x-ms-client-request-id Può essere usato per risolvere le richieste e le risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione x-ms-client-request-id se presente nella richiesta e il valore non contiene più di 1.024 caratteri ASCII visibili. Se l'intestazione x-ms-client-request-id non è presente nella richiesta, non sarà presente nella risposta.

Corpo della risposta

Il corpo della risposta include un elenco di intervalli di pagine non sovrapposti, validi, ordinati aumentando l'intervallo di pagine degli indirizzi. Il formato del corpo della risposta è il seguente:

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

Se l'intero set di pagine del BLOB è stato cancellato, il corpo della risposta non include intervalli di pagine.

Se il parametro è stato specificato, la prevsnapshot risposta include solo le pagine che differiscono tra lo snapshot di destinazione o il BLOB e lo snapshot precedente. Le pagine restituite includono entrambe le pagine aggiornate o cancellate. Il formato di questo corpo della risposta è il seguente:

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

Se l'intero set di pagine del BLOB è stato cancellato e il parametro non è stato specificato, il prevsnapshot corpo della risposta non include intervalli di pagine.

Se il parametro è stato specificato, la maxresults risposta include solo il numero specificato di intervalli con un token di continuazione nel NextMarker tag. Il token di continuazione è vuoto se non sono presenti più intervalli in sospeso oppure contiene un valore opaco che deve essere inviato come marker parametro nella richiesta successiva. Il formato di questo corpo della risposta è il seguente:

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>
   <NextMarker/>
</PageList>

Autorizzazione

L'autorizzazione è necessaria quando si chiama qualsiasi operazione di accesso ai dati in Archiviazione di Azure. È possibile autorizzare l'operazione Get Page Ranges come descritto di seguito.

Importante

Microsoft consiglia di usare Microsoft Entra ID con identità gestite per autorizzare le richieste ad Archiviazione di Azure. Microsoft Entra ID offre una maggiore sicurezza e facilità d'uso rispetto all'autorizzazione di chiave condivisa.

Archiviazione di Azure supporta l'uso di Microsoft Entra ID per autorizzare le richieste ai dati BLOB. Con Microsoft Entra ID è possibile usare il controllo degli accessi in base al ruolo di Azure per concedere le autorizzazioni a un'entità di sicurezza. L'entità di sicurezza può essere un utente, un gruppo, un'entità servizio applicazione o un'identità gestita di Azure. L'entità di sicurezza viene autenticata da Microsoft Entra ID per restituire un token OAuth 2.0. Il token può quindi essere usato per autorizzare una richiesta relativa al servizio BLOB.

Per altre informazioni sull'autorizzazione usando Microsoft Entra ID, vedere Autorizzare l'accesso ai BLOB usando Microsoft Entra ID.

Autorizzazioni

Di seguito è riportata l'azione RBAC necessaria per un utente Microsoft Entra, un gruppo, un gruppo, un'identità gestita o un'entità servizio per chiamare l'operazione Get Page Ranges e il ruolo di controllo degli accessi in base al ruolo predefinito di Azure con privilegi minimi che include questa azione:

Per altre informazioni sull'assegnazione dei ruoli tramite controllo degli accessi in base al ruolo di Azure, vedere Assegnare un ruolo di Azure per l'accesso ai dati BLOB.

Commenti

Gli offset di byte di inizio e fine per ogni intervallo di pagine sono inclusivi.

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

A partire dalla versione 2015-07-08, è possibile chiamare Get Page Ranges con il parametro per restituire le pagine che differiscono tra il prevsnapshot BLOB di base e uno snapshot o tra due snapshot del BLOB. Usando queste differenze di pagina, è possibile salvare uno snapshot incrementale di un BLOB di pagine. Gli snapshot incrementali sono un modo conveniente per eseguire il backup dei dischi delle macchine virtuali se si vuole implementare una soluzione di backup personalizzata.

La chiamata Get Page Ranges con il prevsnapshot parametro restituisce pagine aggiornate o cancellate dopo l'acquisizione dello snapshot specificato da prevsnapshot . È quindi possibile copiare le pagine restituite in un BLOB di pagine di backup in un altro account di archiviazione usando Put Page.

A partire dalla versione 2019-07-07, è possibile usare l'intestazione x-ms-previous-snapshot-url per specificare gli snapshot negli account del disco gestito per gli snapshot incrementali. Se non si usano dischi gestiti, usare il prevsnapshot parametro di query.

Alcune operazioni in un BLOB causano Get Page Ranges un errore quando viene chiamato per restituire uno snapshot incrementale. Get Pages Ranges ha esito negativo con il codice di errore 409 (Conflitto) se viene chiamato in un BLOB di destinazione di una richiesta Put BLOB o Copy BLOB dopo l'acquisizione dello snapshot specificato dall'utente prevsnapshot . Se la destinazione dell'operazione Get Page Ranges è uno snapshot, la chiamata ha esito positivo finché lo snapshot specificato da prevsnapshot è precedente e nessuna Put Blob operazione o Copy Blob è stata chiamata nell'intervallo tra i due snapshot.

Nota

Gli snapshot incrementali sono attualmente supportati solo per i BLOB creati o dopo il 1° gennaio 2016. I tentativi di usare questa funzionalità in un BLOB meno recente generano l'errore, ovvero il BlobOverwritten codice di errore HTTP 409 (Conflitto).

Vedi anche

Autorizzare le richieste ad Archiviazione di Azure
Stato e codici errore
Impostare i timeout per le operazioni di archiviazione BLOB