Get Block List

  • Article

L'opération Get Block List extrait la liste des blocs qui ont été téléchargés dans le cadre d'un objet blob de blocs.

Deux listes de blocage sont conservées pour un objet blob :

  • Liste de blocs validée : liste des blocs qui ont été correctement validés dans un objet blob spécifié à l’aide de La liste de blocs put.

  • Liste de blocs non validée : liste des blocs qui ont été chargés pour un objet blob à l’aide de Put Block, mais qui n’ont pas encore été validés. Ces blocs sont stockés dans Azure en association avec un objet blob, mais ne font pas encore partie de l’objet blob.

Vous pouvez appeler Get Block List pour retourner la liste de blocage validée, la liste de blocage non validée ou les deux listes. Vous pouvez également appeler cette opération pour récupérer la liste de blocage validée pour une instantané.

Requête

La demande Get Block List peut être construite comme indiqué ci-dessous. Nous vous recommandons d’utiliser HTTPS. Remplacez moncompte par le nom de votre compte de stockage :

URI de requête de méthode GET Version HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist

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

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

Demande de service de stockage émulée

Lorsque vous élaborez une demande pour le service de stockage émulé, spécifiez le nom d'hôte de l'émulateur et le port de service BLOB sous la forme 127.0.0.1:10000, suivi du nom de compte de stockage émulé :

URI de requête de méthode GET Version HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=blocklist HTTP/1.1

Pour plus d’informations, consultez Utiliser l’émulateur Azurite à des fins de développement local pour Stockage Azure.

Paramètres URI

Vous pouvez spécifier les paramètres supplémentaires suivants dans l’URI de requête :

Paramètre d’URI Description
snapshot facultatif. Le paramètre d'instantané est une valeur DateTime opaque qui, lorsqu'elle est présente, spécifie la liste d'objets blob à récupérer. Pour plus d’informations sur l’utilisation des instantanés d’objets blob, consultez Créer un instantané d’un objet blob.
versionid Facultatif pour les versions 2019-12-12 et ultérieures. Le versionid paramètre est une valeur opaque DateTime qui, lorsqu’elle est présente, spécifie la version de l’objet blob à récupérer.
blocklisttype Indique quelle liste retourner : liste des blocs validés, liste des blocs non validés ou ces deux listes. Les valeurs valides sont committed, uncommitted ou all. Si ce paramètre est omis, Get Block List retourne la liste des blocs validés.
timeout facultatif. Le paramètre timeout est exprimé en secondes. Pour plus d’informations, consultez Définir des délais d’attente pour les opérations de stockage Blob.

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 demandes 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.
x-ms-lease-id:<ID> facultatif. Si cet en-tête est spécifié, l'opération sera exécutée uniquement 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 à celui de l’objet blob.

Si cet en-tête est spécifié et que l’une ou l’autre des conditions n’est pas remplie, la demande échoue et l’opération échoue avec status code 412 (échec de la condition préalable).
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) enregistrée dans les journaux lors de la configuration de la journalisation. Nous vous recommandons vivement d’utiliser cet en-tête pour mettre en corrélation les activités côté client avec les demandes que le serveur reçoit. Pour plus d’informations, consultez Surveiller Stockage Blob Azure.

Cette opération prend également en charge l'utilisation d'en-têtes conditionnels pour exécuter l'opération 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.

Exemple de requête

L’exemple d’URI de requête suivant retourne la liste de blocage validée pour un objet blob nommé MOV1.avi :

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=committed HTTP/1.1

L’exemple d’URI de requête suivant retourne à la fois la liste de blocage validée et la liste de blocage non validée :

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=all HTTP/1.1

L’exemple d’URI de requête suivant retourne la liste de blocage validée pour un instantané. Une instantané se compose uniquement de blocs validés. Par conséquent, aucun bloc non validé n’est associé.

GET http://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=2009-09-30T20%3a11%3a15.2735974Z

response

La réponse inclut un code status HTTP, un ensemble d’en-têtes de réponse et un corps de réponse qui contient la liste des blocs.

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 également 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.

En-tête de réponse Description
Last-Modified Date/heure de la dernière modification de l’objet blob. Le format de date est conforme à la RFC 1123. Pour plus d’informations, consultez Représenter des valeurs de date/heure dans les en-têtes. Retourné uniquement si l’objet blob a validé des blocs.

Une opération qui modifie l'objet blob, y compris les mises à jour des métadonnées ou des propriétés de l'objet blob, change l'heure de la dernière modification de l'objet blob.
ETag ETag pour l'objet blob. Retourné uniquement si l’objet blob a validé des blocs.
Content-Type Le type de contenu MIME de l'objet blob. La valeur par défaut est application/xml.
x-ms-blob-content-length Taille de l’objet blob en octets.
x-ms-request-id Cet en-tête identifie de manière unique la requête qui a été effectuée et peut être utilisé 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 du service qui a été utilisée pour exécuter la demande. Cet en-tête est renvoyé pour les demandes effectuées avec la version 2009-09-19 ou une version 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. Remarque : Seule la liste de blocage validée peut être retournée par le biais d’une demande anonyme.
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 n’est pas présent dans la réponse.

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

Response body

Le format du corps de la réponse pour une demande qui retourne uniquement les blocs validés se présente comme suit :

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>base64-encoded-block-id</Name>
      <Size>size-in-bytes</Size>
    </Block>
  <CommittedBlocks>
</BlockList>

Le format du corps de la réponse pour une demande qui retourne les blocs validés et non validés se présente comme suit :


<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
     <Block>
        <Name>base64-encoded-block-id</Name>
        <Size>size-in-bytes</Size>
     </Block>
  </CommittedBlocks>
  <UncommittedBlocks>
    <Block>
      <Name>base64-encoded-block-id</Name>
      <Size>size-in-bytes</Size>
    </Block>
  </UncommittedBlocks>
 </BlockList>

Exemple de réponse

Dans l'exemple suivant, le paramètre blocklisttype a été défini à committed, afin que seuls les blocs validés de l'objet blob soient retournés dans la réponse.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Sun, 25 Sep 2011 00:33:19 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>4194304</Size>
    </Block>
  </CommittedBlocks>
</BlockList>

Dans cet exemple, le paramètre blocklisttype a été défini à all, et les blocs validés et non validés de l'objet blob sont retournés dans la réponse.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Sun, 25 Sep 2011 00:35:56 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>4194304</Size>
    </Block>
  </CommittedBlocks>
  <UncommittedBlocks>
    <Block>
      <Name>BlockId003</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId004</Name>
      <Size>1024000</Size>
    </Block>
  </UncommittedBlocks>
</BlockList>

Dans cet exemple suivant, le blocklisttype paramètre a été défini sur all, mais l’objet blob n’a pas encore été validé, de sorte que l’élément CommittedBlocks est vide.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Wed, 14 Sep 2011 00:40:22 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks />
  <UncommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId003</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId004</Name>
      <Size>1024</Size>
    </Block>
  </UncommittedBlocks>
</BlockList>

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 Block List comme décrit ci-dessous.

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 Block List, 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 l’accès aux données d’objets blob.

Remarques

Appelez Get Block List pour retourner la liste des blocs qui ont été validés sur un objet blob de blocs, la liste des blocs qui n’ont pas encore été validés ou les deux listes. Utilisez le paramètre blocklisttype pour indiquer la liste des blocs à retourner. La liste des blocs approuvés est retournée dans l’ordre de leur validation par l’opération Put Block List .

Vous pouvez utiliser la liste de blocs non validée pour déterminer les blocs manquants dans l’objet blob dans les cas où les appels à Put Block ou Put Block List ont échoué. La liste des blocs non validés est retournée par ordre alphabétique. Si un ID de bloc a été téléchargé plusieurs fois, seul le bloc le plus récent s'affiche dans la liste.

Notes

Lorsqu’un objet blob n’a pas encore été validé, l’appel Get Block List avec blocklisttype=all retourne les blocs non validés et l’élément CommittedBlocks est vide.

Get Block List ne prend pas en charge l’accès concurrentiel lorsqu’il lit la liste des blocs non validés. Les appels à où blocklisttype=uncommitted ou blocklisttype=all ont un taux de requête maximal inférieur à Get Block List celui des autres opérations de lecture. Pour plus d’informations sur le débit cible pour les opérations de lecture, consultez Objectifs de scalabilité et de performances du Stockage Azure.

À partir de la version 2019-12-12, un objet blob de blocs peut contenir des blocs allant jusqu’à 4 000 mebioctets (Mio). Pour protéger les applications qui utilisent un entier 32 bits signé pour représenter la taille du bloc, l’appel Get Block List sur un objet blob de blocs qui contient un bloc supérieur à 100 Mio avec une version REST antérieure au 12-12-2019 entraîne status code 409 (Conflit).

Get Block List s'applique uniquement aux objets blob de blocs. L'appel de Get Block List sur un objet blob de pages produit un code d'état 400 (Demande incorrecte).

Get Block List sur un objet blob de blocs archivé échoue.

Facturation

Les demandes de tarification peuvent provenir de clients qui utilisent des API Stockage Blob, soit directement via l’API REST Stockage Blob, soit à partir d’une bibliothèque cliente stockage Azure. Ces demandes cumulent des frais par transaction. Le type de transaction affecte la façon dont le compte est facturé. Par exemple, les transactions de lecture sont comptabilisées dans une catégorie de facturation différente de celle des transactions en écriture. Le tableau suivant montre la catégorie de facturation pour Get Block List les demandes en fonction du type de compte de stockage :

Opération Type de compte de stockage Catégorie de facturation
Get Block List Objet blob de blocs Premium
Usage général v2 Standard		 Autres opérations
Get Block List Usage général v1 standard Lire les opérations

Pour en savoir plus sur la tarification de la catégorie de facturation spécifiée, consultez Stockage Blob Azure Tarification.

Voir aussi

Autoriser les demandes adressées à Stockage AzureÉtat et codes d’erreur Codesd’erreur Stockage BlobDéfinir des délais d’attente pour les opérations de stockage Blob