Get Page Ranges

Articolo
04/14/2023

L'operazione Get Page Ranges 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 Ranges può essere costruita nel modo seguente. È 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 per il 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

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

Parametro	Descrizione
`marker`	Facoltativo, versione 2020-10-02 e 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 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. Se si imposta `maxresults` su un valore minore o uguale a zero, viene restituito il codice di risposta di errore 400 (richiesta non valida).
`snapshot`	facoltativo. Valore DateTime opaco da cui, quando presente, specifica lo snapshot del BLOB da cui recuperare le informazioni. Per altre informazioni sull'uso degli snapshot BLOB, vedere Creare uno snapshot di un BLOB.
`timeout`	facoltativo. Espresso in secondi. Per altre informazioni, vedere Impostare i timeout per le operazioni di archiviazione BLOB.
`prevsnapshot`	Facoltativa, versione 2015-07-08 e successive. Valore DateTime che specifica che la risposta conterrà solo le 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 precedente dei due. Nota: gli snapshot incrementali sono attualmente supportati solo per i BLOB creati 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 dell'intervallo per le operazioni di archiviazione BLOB .
`x-ms-lease-id:<ID>`	facoltativo. Se questa intestazione viene specificata, l'operazione viene eseguita solo se vengono soddisfatte entrambe le condizioni seguenti: - Il lease del BLOB è attualmente attivo. - L'ID lease specificato nella richiesta corrisponde all'ID lease del BLOB. Se questa intestazione viene specificata e una delle due condizioni non viene soddisfatta, la richiesta ha esito negativo e l'operazione ha esito negativo con codice di stato 412 (Precondizione non riuscita).
`x-ms-previous-snapshot-url`	Facoltativo, versione 2019-07-07 e successive. `previous-snapshot-url` Specifica che la risposta conterrà solo le 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 il 1° gennaio 2016 e che questa intestazione deve essere usata solo negli scenari di 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 viene 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 i problemi della 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.

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, un gruppo o un'entità servizio di Microsoft Entra 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:

Azione controllo degli accessi in base al ruolo di Azure:Microsoft.Storage/storageAccounts/BLOBServices/containers/BLOBs/read
Ruolo predefinito con privilegi minimi:Lettore dati BLOB di archiviazione

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.

Una firma di accesso condiviso (SAS) offre accesso delegato sicuro alle risorse in un account di archiviazione. Con una firma di accesso condiviso è disponibile un controllo granulare sul modo in cui un client può accedere ai dati. È possibile specificare la risorsa a cui può accedere il client, le autorizzazioni necessarie per tali risorse e il tempo di validità della firma di accesso condiviso.

L'operazione Get Page Ranges supporta tre tipi di firme di accesso condiviso: firma di accesso condiviso con delega utente, firma di accesso condiviso e firma di accesso condiviso.

Come procedura consigliata per la sicurezza, è consigliabile usare le credenziali Microsoft Entra anziché la chiave dell'account di archiviazione, che può essere più facilmente compromessa. Se la progettazione dell'applicazione richiede firme di accesso condiviso, usare Microsoft Entra credenziali per creare una firma di accesso condiviso di delega utente, quando possibile.

Quando l'accesso a chiave condivisa non è consentito per l'account di archiviazione, un token di firma di accesso condiviso del servizio o un token di firma di accesso condiviso dell'account non sarà consentito in una richiesta di archiviazione BLOB. Per altre informazioni, vedere Informazioni su come impedire la condivisione della chiave condivisa influisce sui token di firma di accesso condiviso.

Firma di accesso condiviso di delega utente

Una firma di accesso condiviso di delega utente è protetta con le credenziali di Microsoft Entra e anche dalle autorizzazioni specificate per la firma di accesso condiviso.

La chiamata all'operazione Get Page Ranges tramite un token di firma di accesso condiviso delegata a una risorsa contenitore o BLOB richiede l'autorizzazione Read (r) come parte del token di firma di accesso condiviso della delega utente.

Per altre informazioni sulla firma di accesso condiviso di delega utente, vedere Creare una firma di accesso condiviso di delega utente.

Firma di accesso condiviso del servizio

Una firma di accesso condiviso del servizio è protetta con la chiave dell'account di archiviazione. Una firma di accesso condiviso del servizio delega l'accesso a una risorsa in un singolo servizio di archiviazione di Azure, ad esempio l'archiviazione BLOB.

Per altre informazioni sulla firma di accesso condiviso del servizio, vedere Creare una firma di accesso condiviso del servizio.

Firma di accesso condiviso dell'account

Una firma di accesso condiviso dell'account è protetta con la chiave dell'account di archiviazione. Una firma di accesso condiviso dell'account delega l'accesso alle risorse in uno o più servizi di archiviazione. Tutte le operazioni disponibili tramite una firma di accesso condiviso del servizio o di delega utente sono disponibili anche tramite una firma di accesso condiviso dell'account.

La tabella seguente indica il tipo di risorsa firmato e le autorizzazioni firmate per specificare quando delega l'accesso:

Operazione	Servizio firmato	Tipo di risorsa firmato	Autorizzazione firmata
Get Page Ranges	BLOB (b)	Oggetto (o)	Lettura (r)

Per altre informazioni sulla firma di accesso condiviso dell'account, vedere Creare una firma di accesso condiviso dell'account.

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