Partager via

Get Page Ranges

  • Article

L’opération Obtenir des plages de pages retourne la liste des plages de pages valides pour un objet blob de pages ou instantané d’un objet blob de pages.

Requête

La demande Obtenir des plages de pages peut être construite comme suit. Nous vous recommandons d’utiliser HTTPS. Remplacez moncompte par le nom de votre compte de stockage :

URI de demande de méthode GET Version 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 de service de stockage émulé

Lorsque vous effectuez une demande auprès du service de stockage émulé, spécifiez le nom d’hôte de l’émulateur et Stockage Blob Azure port 127.0.0.1 :10000, suivi du nom du compte de stockage émulé :

URI de demande de méthode GET Version HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist HTTP/1.1

Pour plus d’informations, consultez Utiliser l’émulateur de stockage Azure pour le développement et le test.

Paramètres URI

Les paramètres supplémentaires suivants peuvent être spécifiés sur l’URI de demande :

Paramètre Description
marker Facultatif, version 2020-10-02 et ultérieures. Identifie la partie des plages à retourner avec l’opération GetPageRanges suivante. L’opération retourne une valeur de marqueur dans le corps de la réponse si les plages retournées étaient incomplètes. La valeur du marqueur peut ensuite être utilisée dans un appel suivant pour demander l’ensemble suivant de plages.

La valeur de marqueur est opaque au client.
maxresults Facultatif, version 2020-10-02 et ultérieures. Spécifie le nombre maximal de plages de pages à retourner. Si la requête spécifie une valeur supérieure à 10 000, le serveur retourne jusqu’à 10 000 éléments. S’il existe des résultats supplémentaires à retourner, le service retourne un jeton de continuation dans l’élément de réponse NextMarker.

La définition maxresults d’une valeur inférieure ou égale à zéro entraîne le code de réponse d’erreur 400 (requête incorrecte).
snapshot facultatif. Valeur DateTime opaque qui, lorsqu’elle est présente, spécifie le instantané d’objet blob à partir duquel récupérer des informations. Pour plus d’informations sur l’utilisation des instantanés d’objets blob, consultez Create un instantané d’un objet blob.
timeout facultatif. Exprimé en secondes. Pour plus d’informations, consultez Définir des délais d’expiration pour les opérations de stockage Blob.
prevsnapshot Facultatif, version 2015-07-08 et ultérieure. Valeur DateTime qui spécifie que la réponse contiendra uniquement les pages qui ont été modifiées entre l’objet blob cible et le instantané précédent. Les pages modifiées incluent des pages mises à jour et effacées. L’objet blob cible peut être un instantané, tant que le instantané spécifié par prevsnapshot est le plus ancien des deux.

Remarque : Les instantanés incrémentiels sont actuellement pris en charge uniquement pour les objets blob qui ont été créés à partir du 1er janvier 2016.

En-têtes de requête

Le tableau suivant décrit les en-têtes de demande obligatoires ou facultatifs.

En-tête de requête Description
Authorization Obligatoire. Spécifie le schéma d’autorisation, le nom du compte et la signature. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
Date ou x-ms-date Obligatoire. Spécifie la date/heure en temps universel coordonné (UTC) pour la requête. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
x-ms-version Obligatoire pour toutes les demandes autorisées, facultatif pour les requêtes anonymes. Spécifie la version de l'opération à utiliser pour cette demande. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure.
Range facultatif. Spécifie la plage d'octets dans laquelle répertorier les plages (inclusivement). Si Range est omis, toutes les plages de l’objet blob sont retournées.
x-ms-range facultatif. Spécifie la plage d'octets dans laquelle répertorier les plages (inclusivement). Si Range et x-ms-range sont spécifiés, le service utilise la valeur de x-ms-range. Pour plus d’informations, consultez Spécifier l’en-tête de plage pour les opérations de stockage Blob .
x-ms-lease-id:<ID> facultatif. Si cet en-tête est spécifié, l’opération n’est effectuée que si les deux conditions suivantes sont remplies :

- Le bail de l’objet blob est actuellement actif.

- L’ID de bail spécifié dans la demande correspond à l’ID de bail de l’objet blob.

Si cet en-tête est spécifié et que l’une ou l’autre condition n’est pas remplie, la demande échoue et l’opération échoue avec status code 412 (Échec de la condition préalable).
x-ms-previous-snapshot-url Facultatif, version 2019-07-07 et versions ultérieures. Spécifie previous-snapshot-url que la réponse contiendra uniquement les pages qui ont été modifiées entre l’objet blob cible et instantané qui se trouvent à l’URI spécifié. Les pages modifiées incluent des pages mises à jour et effacées. L’objet blob cible peut être un instantané, tant que le instantané spécifié par cet en-tête est le plus ancien des deux.

Remarque : Les instantanés incrémentiels sont actuellement pris en charge uniquement pour les objets blob qui ont été créés le 1er janvier 2016 ou après, et que cet en-tête ne doit être utilisé que dans les scénarios de disque managé. Sinon, utilisez le prevsnapshot paramètre .
x-ms-client-request-id facultatif. Fournit une valeur opaque générée par le client avec une limite de caractères de 1 kibioctet (Kio), qui est enregistrée dans les journaux d’analyse lorsque la journalisation Azure Storage Analytics est activée. Nous vous recommandons vivement d’utiliser cet en-tête lorsque vous associez des activités côté client aux demandes reçues par le serveur. Pour plus d’informations, consultez À propos de la journalisation Storage Analytics et de la journalisation Azure : Utiliser des journaux pour suivre les demandes de stockage Azure.

Cette opération prend également en charge l'utilisation d'en-têtes conditionnels pour obtenir les plages de pages uniquement si une condition est remplie. Pour plus d’informations, consultez Spécifier des en-têtes conditionnels pour les opérations de stockage Blob.

Corps de la demande

Aucun.

response

La réponse inclut un code d'état HTTP, un ensemble d'en-têtes de réponse et le corps de réponse.

Code d’état

Une opération réussie envoie le code d'état 200 (OK).

Pour plus d’informations sur les codes status, consultez Codes d’état et d’erreur.

En-têtes de réponse

La réponse de l'opération inclut les en-têtes suivants. La réponse peut aussi inclure des en-têtes HTTP standard supplémentaires. Tous les en-têtes standard sont conformes à la spécification du protocole HTTP/1.1.

Syntaxe Description
Last-Modified Date et heure de la dernière modification apportée à l'objet blob. Le format de date est conforme à la RFC 1123.

Toute opération qui modifie l'objet blob, notamment une mise à jour des métadonnées ou des propriétés de l'objet blob, modifie l'heure de la dernière modification de l'objet blob.
ETag Contient une valeur que le client peut utiliser pour effectuer l’opération de manière conditionnelle. Si la version de la demande est 2011-08-18 ou version ultérieure, la valeur ETag est placée entre guillemets.
x-ms-blob-content-length Taille de l’objet blob en octets.
x-ms-request-id Identifie de manière unique la demande qui a été effectuée, et elle peut être utilisée pour résoudre les problèmes de la demande. Pour plus d’informations, consultez Résoudre les problèmes liés aux opérations d’API.
x-ms-version Indique la version de Stockage Blob qui a été utilisée pour exécuter la demande. Cet en-tête est retourné pour les demandes effectuées sur la version 2009-09-19 et ultérieure.

Cet en-tête est également retourné pour les requêtes anonymes sans version spécifiée si le conteneur a été marqué pour un accès public à l’aide de la version 2009-09-19 du Stockage Blob.
Date Valeur de date/heure UTC générée par le service, qui indique l’heure à laquelle la réponse a été lancée.
x-ms-client-request-id Peut être utilisé pour résoudre les problèmes liés aux demandes et aux réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l’en-tête x-ms-client-request-id s’il est présent dans la requête et que la valeur ne contient pas plus de 1 024 caractères ASCII visibles. Si l’en-tête x-ms-client-request-id n’est pas présent dans la demande, il ne sera pas présent dans la réponse.

Response body

Le corps de la réponse comprend une liste de plages de pages valides qui ne se chevauchent pas, triées en fonction de l’augmentation de la plage de pages d’adresses. Le corps de la réponse présente le format suivant :

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

Si l’ensemble de pages de l’objet blob a été effacé, le corps de la réponse n’inclut aucune plage de pages.

Si le prevsnapshot paramètre a été spécifié, la réponse inclut uniquement les pages qui diffèrent entre le instantané cible ou l’objet blob et le instantané précédent. Les pages retournées incluent les deux pages qui ont été mises à jour ou effacées. Le format de ce corps de réponse est le suivant :

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

Si l’ensemble des pages de l’objet blob a été effacé et que le prevsnapshot paramètre n’a pas été spécifié, le corps de la réponse n’inclut aucune plage de pages.

Si le maxresults paramètre a été spécifié, la réponse inclut uniquement le nombre spécifié de plages avec un jeton de continuation dans la NextMarker balise. Le jeton de continuation est vide s’il n’y a plus de plages en attente, ou s’il contient une valeur opaque qui doit être envoyée en tant marker que paramètre dans la requête suivante. Le format de ce corps de réponse est le suivant :

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

Autorisation

Une autorisation est requise lors de l’appel d’une opération d’accès aux données dans stockage Azure. Vous pouvez autoriser l’opération Get Page Ranges comme décrit ci-dessous.

Important

Microsoft recommande d’utiliser Microsoft Entra ID avec des identités managées pour autoriser les demandes dans le stockage Azure. Microsoft Entra ID offre une sécurité et une facilité d’utilisation supérieures par rapport à l’autorisation de clé partagée.

Le Stockage Azure prend en charge l’utilisation de Microsoft Entra ID pour autoriser les demandes de données blob. Avec Microsoft Entra ID, vous pouvez utiliser le contrôle d’accès en fonction du rôle Azure (Azure RBAC) pour accorder des autorisations à un principal de sécurité. Le principal de sécurité peut être un utilisateur, un groupe, un principal de service d’application ou une identité managée Azure. Le principal de sécurité est authentifié par Microsoft Entra ID pour retourner un jeton OAuth 2.0. Le jeton peut ensuite être utilisé pour autoriser une requête auprès du service BLOB.

Pour en savoir plus sur l’autorisation à l’aide de Microsoft Entra ID, consultez Autoriser l’accès aux objets blob à l’aide de Microsoft Entra ID.

Autorisations

Vous trouverez ci-dessous l’action RBAC nécessaire pour qu’un utilisateur, un groupe, une identité managée ou un principal de service Microsoft Entra appelle l’opérationGet Page Ranges, ainsi que le rôle RBAC Azure intégré le moins privilégié qui inclut cette action :

Pour en savoir plus sur l’attribution de rôles à l’aide d’Azure RBAC, consultez Attribuer un rôle Azure pour accéder aux données blob.

Remarques

Les décalages d'octets de début et de fin pour chaque plage de page sont inclusifs.

Dans un objet blob de pages très fragmenté avec un grand nombre d'écritures, une demande Get Page Ranges peut échouer en raison du délai d'expiration serveur interne. Les applications qui récupèrent les plages d'un objet blob de pages avec un grand nombre d'opérations d'écriture doivent récupérer un sous-ensemble de plages de pages à la fois.

À compter de la version 2015-07-08, vous pouvez appeler Get Page Ranges avec le prevsnapshot paramètre pour retourner les pages qui diffèrent entre l’objet blob de base et un instantané, ou entre deux instantanés de l’objet blob. En utilisant ces différences de page, vous pouvez enregistrer une instantané incrémentielle d’un objet blob de pages. Les instantanés incrémentiels sont un moyen économique de sauvegarder des disques de machine virtuelle si vous souhaitez implémenter votre propre solution de sauvegarde.

L’appel Get Page Ranges avec le paramètre retourne les prevsnapshot pages qui ont été mises à jour ou effacées depuis la instantané spécifiée par prevsnapshot a été prise. Vous pouvez ensuite copier les pages retournées vers un objet blob de pages de sauvegarde dans un autre compte de stockage à l’aide de Put Page.

À compter de la version 2019-07-07, vous pouvez utiliser l’en-tête x-ms-previous-snapshot-url pour spécifier des instantanés dans les comptes de disque managé pour les instantanés incrémentiels. Si vous n’utilisez pas de disques managés, utilisez le paramètre de prevsnapshot requête.

Certaines opérations sur un objet blob provoquent Get Page Ranges l’échec lorsqu’il est appelé pour retourner un instantané incrémentiel. Get Pages Rangeséchoue avec le code d’erreur 409 (Conflit) s’il est appelé sur un objet blob qui était la cible d’une requête Put Blob ou Copy Blob après l’exécution de la instantané spécifiée parprevsnapshot. Si la cible de l’opération Get Page Ranges est elle-même un instantané, l’appel réussit tant que le instantané spécifié par prevsnapshot est plus ancien, et que l’opération no Put Blob ou Copy Blob a été appelée dans l’intervalle entre les deux instantanés.

Notes

Les instantanés incrémentiels sont actuellement pris en charge uniquement pour les objets blob créés à partir du 1er janvier 2016. Les tentatives d’utilisation de cette fonctionnalité sur un objet blob plus ancien entraînent l’erreur, qui est le BlobOverwritten code d’erreur HTTP 409 (conflit).

Voir aussi

Autoriser les demandes dans le Stockage Azure
Codes d’état et d’erreur
Définir des délais d’expiration pour les opérations de stockage Blob