Get Page Ranges

Article
02/03/2024

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 Créer 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.

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 ou un principal de service Microsoft Entra appelle l’opérationGet Page Ranges, ainsi que le rôle RBAC intégré Azure le moins privilégié qui inclut cette action :

Action RBAC Azure :Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Rôle intégré avec privilèges minimum :Lecteur de données Blob de stockage

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.

Une signature d’accès partagé (SAP) fournit un accès délégué sécurisé aux ressources d’un compte de stockage. Avec une SAP, vous disposez d’un contrôle granulaire sur la façon dont un client peut accéder aux données. Vous pouvez spécifier la ressource à laquelle le client peut accéder, les autorisations dont il dispose sur ces ressources et la durée de validité de la signature d’accès partagé.

L’opération Get Page Ranges prend en charge trois types de signatures d’accès partagé : SAP de délégation d’utilisateur, SAP de service et SAP de compte.

En guise de meilleure pratique en matière de sécurité, nous vous recommandons d’utiliser des informations d’identification Microsoft Entra plutôt que la clé de compte de stockage, qui peut être plus facilement compromise. Si votre conception d’application nécessite des signatures d’accès partagé, utilisez les informations d’identification Microsoft Entra pour créer une sap de délégation d’utilisateur, si possible.

Lorsque l’accès à la clé partagée n’est pas autorisé pour le compte de stockage, un jeton SAP de service ou un jeton SAP de compte ne sont pas autorisés lors d’une demande adressée au Stockage Blob. Pour en savoir plus, consultez Comprendre comment l’interdiction de la clé partagée affecte les jetons SAP.

SAP de délégation d’utilisateur

Une sap de délégation d’utilisateur est sécurisée avec des informations d’identification Microsoft Entra, ainsi que par les autorisations spécifiées pour la signature d’accès partagé.

L’appel de l’opération à l’aide Get Page Ranges d’un jeton SAS délégué à un conteneur ou à une ressource d’objet blob nécessite l’autorisation Lecture (r) dans le cadre du jeton SAP de délégation d’utilisateur.

Pour en savoir plus sur la SAP de délégation d’utilisateur, consultez Créer une SAP de délégation d’utilisateur.

SAP de service

Une SAP de service est sécurisée à l’aide de la clé de compte de stockage. Une SAP de service délègue l’accès à une ressource dans un seul service de stockage Azure, tel que le stockage d’objets blob.

L’appel de l’opération à l’aide Get Page Ranges d’un jeton SAP délégué à un conteneur ou à une ressource d’objet blob nécessite l’autorisation Lecture (r) dans le cadre du jeton SAP de service.

Pour en savoir plus sur la SAP de service, consultez Créer une SAP de service.

SAP de compte

Une SAP de compte est sécurisée à l’aide de la clé de compte de stockage. Une SAP de compte délègue l’accès aux ressources d’un ou plusieurs des services de stockage. Toutes les opérations disponibles via une SAP de service ou de délégation d’utilisateur sont également disponibles via une SAP de compte.

Le tableau suivant indique le type de ressource signé et les autorisations signées à spécifier lors de la délégation de l’accès :

Opération	Service signé	Type de ressource signé	Autorisation signée
Get Page Ranges	Blob (b)	Objet (o)	Lecture (r)

Pour en savoir plus sur la SAP de compte, consultez Créer une SAP de compte.

L’opération Get Page Ranges prend en charge l’autorisation de clé partagée. L’autorisation avec des clés de compte n’est pas recommandée pour la plupart des scénarios, car elle est moins sécurisée.

Microsoft recommande d’interdire l’autorisation de clé partagée pour le compte de stockage lorsque cela est possible. Pour plus d’informations, consultez Empêcher l’autorisation avec une clé partagée.

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