Lot d’objets blob

  • Article

L’opération Blob Batch permet d’incorporer plusieurs appels d’API dans une seule requête HTTP. Cette API prend en charge deux types de sous-requêtes : Définir le niveau d’objet blob pour les objets blob de blocs et Supprimer l’objet blob. La réponse retournée par le serveur pour une demande de lot contient les résultats de chaque sous-requête dans le lot. La requête et la réponse par lot utilisent la syntaxe de la OData spécification de traitement par lots, avec des modifications de sémantique. Cette API est disponible à partir de la version 2018-11-09.

Requête

Vous pouvez construire la Blob Batch requête comme suit. HTTPS est recommandé. Remplacez myaccount par le nom de votre compte de stockage.

Méthode URI de demande Version HTTP
POST https://myaccount.blob.core.windows.net/?comp=batch

https://myaccount.blob.core.windows.net/containername?restype=container&comp=batch		 HTTP/1.1

Paramètres URI

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

Paramètre Description
timeout facultatif. Le paramètre de délai d’expiration est exprimé en secondes, avec une valeur maximale de 120 secondes. Pour plus d’informations, consultez Définition des délais d’expiration pour les opérations de stockage Blob.
restype Facultatif, version 2020-04-08 et ultérieures. La seule valeur prise en charge pour le restype paramètre est container. Lorsque ce paramètre est spécifié, l’URI doit inclure le nom du conteneur. Toutes les sous-requêtes doivent être limitées au même conteneur.

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 de stockage 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. Spécifie la version de l'opération à utiliser pour cette demande. Cette version sera utilisée pour toutes les sous-requêtes. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure.
Content-Length Obligatoire. La longueur de la demande.
Content-Type Obligatoire. La valeur de cet en-tête doit être multipart/mixed, avec une limite de lot. Exemple de valeur d’en-tête : multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252.
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.

Corps de la demande

Le corps de la demande d’un lot d’objets blob contient une liste de toutes les sous-requêtes. Le format utilise la syntaxe de la OData spécification de lot, avec des modifications de sémantique.

Le corps de la demande commence par une limite de lot, suivie de deux en-têtes obligatoires : l’en-tête Content-Type avec la valeur application/httpet l’en-tête Content-Transfer-Encoding avec la valeur binary. Elle est suivie d’un en-tête facultatif Content-ID , avec une valeur de chaîne pour suivre chacune des sous-requêtes. La réponse contient l’en-tête Content-ID de chaque réponse de sous-demande correspondante à utiliser pour le suivi.

Ces en-têtes de requête sont suivis d’une ligne vide obligatoire, puis de la définition de chaque sous-requête. Le corps de chaque sous-requête est une requête HTTP complète avec un verbe, une URL, des en-têtes et un corps nécessaires pour la requête. Notez les mises en garde suivantes :

  • Les sous-requêtes ne doivent pas avoir le x-ms-version header. Toutes les sous-requêtes sont exécutées avec la version de requête par lot de niveau supérieur.
  • L’URL de sous-requête doit avoir uniquement le chemin d’accès de l’URL (sans l’hôte).
  • Chaque demande de lot prend en charge un maximum de 256 sous-requêtes.
  • Toutes les sous-requêtes doivent être du même type de requête.
  • Chaque sous-demande est autorisée séparément, avec les informations fournies dans la sous-demande.
  • Chaque ligne du corps de la demande doit se terminer par \r\n caractères.

Exemple de requête

POST http://account.blob.core.windows.net/?comp=batch HTTP/1.1 
Content-Type: multipart/mixed; boundary=batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
x-ms-version: 2018-11-09 
Authorization: SharedKey account:QvaoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI=
Host: 127.0.0.1:10000 
Content-Length: 1569 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 0 

DELETE /container0/blob0 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:G4jjBXA7LI/RnWKIOQ8i9xH4p76pAQ+4Fs4R1VxasaE= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 1 

DELETE /container1/blob1 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:IvCoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 2 

DELETE /container2/blob2 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:S37N2JTjcmOQVLHLbDmp2johz+KpTJvKhbVc4M7+UqI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525--

response

La réponse inclut un code de status HTTP et un ensemble d’en-têtes de réponse pour la demande de traitement par lots de niveau supérieur. La réponse inclut également des informations de réponse pour toutes ses sous-requêtes.

Response body

La réponse par lot est une multipart/mixed réponse, qui contient la réponse pour chaque sous-demande. La réponse est segmentée. Chaque sous-réponse commence par l’en-tête Content-Type: application/http . L’en-tête Content-ID suit, s’il a été fourni dans la demande. Ceci est suivi de la réponse HTTP status code et des en-têtes de réponse pour chaque sous-requête.

Pour plus d’informations sur les en-têtes retournés par chaque sous-requête, consultez la documentation relative aux opérations Supprimer un objet blob et Définir le niveau de l’objet blob .

Exemple de réponse

HTTP/1.1 202 Accepted 
Transfer-Encoding: chunked 
Content-Type: multipart/mixed; boundary=batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
x-ms-request-id: 778fdc83-801e-0000-62ff-033467000000 
x-ms-version: 2018-11-09 

409
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 0 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e284f 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 1 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2851 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 2 

HTTP/1.1 404 The specified blob does not exist. 
x-ms-error-code: BlobNotFound 
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2852 
x-ms-version: 2018-11-09 
Content-Length: 216 
Content-Type: application/xml 

<?xml version="1.0" encoding="utf-8"?> 
<Error><Code>BlobNotFound</Code><Message>The specified blob does not exist. 
RequestId:778fdc83-801e-0000-62ff-0334671e2852 
Time:2018-06-14T16:46:54.6040685Z</Message></Error> 
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed-- 
0

Code d’état

Si la demande de lot est bien formée et autorisée, l’opération retourne status code 202 (Accepté). Chaque sous-requête a sa propre réponse, en fonction du résultat de l’opération. La sous-requête status est retournée dans le corps de la réponse.

Pour plus d’informations, consultez État et codes 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.

Autorisation

Quand restype=container est omis, vous devez autoriser la demande de lot parente à l’aide d’une clé partagée. Vous pouvez utiliser la clé d’accès au compte, une signature d’accès partagé de compte ou Azure Active Directory. Détails pour les mécanismes d’autorisation spécifiques indiqués ci-dessous.

Quand restype=container est inclus dans la demande, vous pouvez autoriser la requête par lots parente via une clé partagée ou Azure Active Directory. Vous pouvez également autoriser avec une signature d’accès partagé signée par l’un de ces mécanismes d’autorisation. Détails pour les mécanismes d’autorisation spécifiques indiqués ci-dessous.

Chaque sous-demande est autorisée séparément. Une sous-demande prend en charge les mêmes mécanismes d’autorisation que l’opération prend en charge lorsqu’elle ne fait pas partie d’une opération de traitement par lots.

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 effectue une Blob Batch demande parente, 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.

Facturation

La Blob Batch requête REST est comptée comme une transaction, et chaque sous-requête individuelle est également comptée comme une transaction. Pour en savoir plus sur la facturation des sous-requêtes individuelles, consultez la documentation relative aux opérations Supprimer des objets blob et Définir le niveau d’objets blob .

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 d’une Blob Batch requête parente en fonction du type de compte de stockage :

Opération Type de compte de stockage Catégorie de facturation
Lot d’objets blob (Définir le niveau Blob) Objet blob de blocs Premium
Usage général v2 Standard		 Autres opérations

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

Remarques

L’un des main avantages de l’utilisation d’une demande par lots est la réduction du nombre de connexions qu’un client doit ouvrir. Notez que les restrictions suivantes s’appliquent :

  • Les sous-requêtes prises en charge dans le lot sont Set Blob Tier (pour les objets blob de blocs) et Delete Blob.
  • Prend uniquement en charge jusqu’à 256 sous-requêtes dans un seul lot. La taille du corps d’une demande par lot ne peut pas dépasser 4 Mo.
  • Une demande de lot vide échoue avec le code 400 (requête incorrecte).
  • Il n’existe aucune garantie sur l’ordre d’exécution des sous-requêtes de lot.
  • L’exécution de la sous-demande par lot n’est pas atomique. Chaque sous-requête s’exécute indépendamment.
  • Chaque sous-requête doit concerner une ressource au sein du même compte de stockage. Une requête par lot unique ne prend pas en charge l’exécution de requêtes provenant de différents comptes de stockage.
  • Un corps de requête imbriqué n’est pas pris en charge.
  • Si le serveur ne parvient pas à analyser le corps de la demande, l’intégralité du lot échoue et aucune requête n’est exécutée.
  • Notez que account SAS est le seul type de signature d’accès partagé pris en charge par Blob Batch, lorsque le lot n’utilise restype=containerpas .

Étendre toutes les sous-requêtes à un conteneur spécifique

À compter de la version REST 2020-04-08, l’API Blob Batch prend en charge les sous-requêtes d’étendue pour un conteneur spécifié. Lorsque l’URI de requête inclut le nom du conteneur et le restype=container paramètre, chaque sous-requête doit s’appliquer au même conteneur. Si le nom de conteneur spécifié pour une sous-requête ne correspond pas au nom du conteneur fourni dans l’URI, le service retourne le code d’erreur 400 (requête incorrecte).

Tous les mécanismes d’autorisation pris en charge pour un conteneur sont valides pour une Blob Batch opération limitée au conteneur. Chaque sous-requête envoie un en-tête d’autorisation au service.

Voir aussi

Autoriser les demandes adressées à Stockage AzureÉtat et codes d’erreur Codes d’erreurStockage BlobDéfinition des délais d’expiration pour les opérations de stockage Blob