Append Block

  • Article

L’opération Append Block valide un nouveau bloc de données à la fin d’un objet blob d’ajout existant.

L’opération Append Block est autorisée uniquement si l’objet blob a été créé avec x-ms-blob-type défini sur AppendBlob. Append Block est pris en charge uniquement sur la version 2015-02-21 ou ultérieure.

Requête

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

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

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 comme 127.0.0.1:10000, suivis du nom du compte de stockage émulé.

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

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

Paramètres URI

Paramètre Description
timeout facultatif. Le paramètre timeout est exprimé en secondes. Pour plus d’informations, consultez Définition de délais d’expiration pour les opérations de Stockage Blob Azure.

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 demandes adressées au 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. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure.
Content-Length Obligatoire. La longueur du contenu du bloc, en octets. La taille du bloc doit être inférieure ou égale à 100 Mio (préversion) pour la version 2022-11-02 et ultérieure. Consultez la section Remarques pour connaître les limites dans les versions antérieures.

Lorsque la longueur n'est pas spécifiée, l'opération échoue avec le code d'état 411 (Longueur requise).
Content-MD5 facultatif. Un hachage MD5 du contenu du bloc. Ce hachage est utilisé pour vérifier l'intégrité du bloc pendant le transport. Lorsque cet en-tête est spécifié, le service de stockage compare le hachage du contenu qui est arrivé à cette valeur d'en-tête.

Notez que ce hachage MD5 n’est pas stocké avec l’objet blob.

Si les deux hachages ne correspondent pas, l’opération échoue avec le code d’erreur 400 (Demande incorrecte).
x-ms-content-crc64 facultatif. Hachage CRC64 du contenu du bloc d’ajout. Ce hachage est utilisé pour vérifier l’intégrité du bloc d’ajout pendant le transport. Lorsque cet en-tête est spécifié, le service de stockage compare le hachage du contenu qui est arrivé à cette valeur d'en-tête.

Notez que ce hachage CRC64 n’est pas stocké avec l’objet blob.

Si les deux hachages ne correspondent pas, l’opération échoue avec le code d’erreur 400 (Demande incorrecte).

Si les en-têtes Content-MD5 et x-ms-content-crc64 sont présents, la demande échoue avec le code d’erreur 400.

Cet en-tête est pris en charge dans les versions 2019-02-02 ou ultérieures.
x-ms-encryption-scope facultatif. Indique l’étendue de chiffrement à utiliser pour chiffrer le contenu de la demande. Cet en-tête est pris en charge dans les versions 2019-02-02 ou ultérieures.
x-ms-lease-id:<ID> Obligatoire si l'objet blob a un bail actif. Pour effectuer cette opération sur un objet blob avec un bail actif, spécifiez l'ID de bail valide pour cet en-tête.
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.
x-ms-blob-condition-maxsize En-tête conditionnel facultatif. Spécifie la longueur maximale en octets autorisée pour l’objet blob d’ajout. Si l’opération Append Block entraîne le dépassement de cette limite ou si la taille de l’objet blob est déjà supérieure à la valeur spécifiée dans cet en-tête, la demande échoue avec le code d’erreur 412 (échec de la condition préalable).
x-ms-blob-condition-appendpos En-tête conditionnel facultatif, utilisé uniquement pour l’opération Append Block . Un nombre indique le décalage d’octets à comparer. Append Block réussit uniquement si la position d’ajout est égale à ce nombre. Si ce n’est pas le cas, la demande échoue avec le code d’erreur 412 (Échec de la condition préalable).

Cette opération prend en charge l’utilisation d’en-têtes conditionnels supplémentaires pour garantir que l’API réussit uniquement si une condition spécifiée est remplie. Pour plus d’informations, consultez Spécification d’en-têtes conditionnels pour les opérations de Stockage Blob Azure.

En-têtes de requête (clés de chiffrement fournies par le client)

À compter de la version 2019-02-02, vous pouvez spécifier les en-têtes suivants sur la demande de chiffrement d’un objet blob avec une clé fournie par le client. Le chiffrement avec une clé fournie par le client (et l’ensemble d’en-têtes correspondant) est facultatif.

En-tête de requête Description
x-ms-encryption-key Obligatoire. Clé de chiffrement AES-256 encodée en Base64.
x-ms-encryption-key-sha256 Obligatoire. Hachage SHA256 codé en Base64 de la clé de chiffrement.
x-ms-encryption-algorithm: AES256 Obligatoire. Spécifie l’algorithme à utiliser pour le chiffrement. La valeur de cet en-tête doit être définie AES256.

Corps de la demande

Le corps de la demande contient le contenu du bloc.

Exemple de requête

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048  
If-Match: "0x8CB172A360EC34B"

response

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

Code d’état

Une opération réussie renvoie le code d'état 201 (Créé).

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
ETag contient ETag une valeur entre guillemets. Le client peut utiliser la valeur pour effectuer des opérations conditionnelles PUT à l’aide de l’en-tête de requête If-Match .
Last-Modified Date et heure de la dernière modification apportée à l’objet blob. Le format de date est conforme à la RFC 1123. Pour plus d’informations, consultez Représentation de valeurs date-heure dans les en-têtes.

Toute opération d’écriture sur l’objet blob (y compris les mises à jour sur les métadonnées ou propriétés de l’objet blob) modifie l’heure de la dernière modification de l’objet blob.
Content-MD5 Cet en-tête est renvoyé afin que le client puisse vérifier l'intégrité du contenu du message. La valeur de cet en-tête est calculée par Stockage Blob. Il ne s’agit pas nécessairement de la même valeur spécifiée dans les en-têtes de requête. Pour les versions 2019-02-02 ou ultérieures, cet en-tête est retourné uniquement lorsque la demande a cet en-tête.
x-ms-content-crc64 Pour les versions 2019-02-02 ou ultérieures, cet en-tête est retourné afin que le client puisse case activée pour l’intégrité du contenu du message. La valeur de cet en-tête est calculée par Stockage Blob. Il ne s’agit pas nécessairement de la même valeur spécifiée dans les en-têtes de requête.

Cet en-tête est retourné lorsque l’en-tête Content-md5 n’est pas présent dans la demande.
x-ms-request-id Cet en-tête identifie de manière unique la demande qui a été effectuée et peut être utilisé pour la résolution des problèmes de la demande.
x-ms-version Indique la version du stockage Blob 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.
Date Valeur de date/heure UTC qui indique l’heure à laquelle la réponse a été lancée. Le service génère cette valeur.
x-ms-blob-append-offset Cet en-tête de réponse est retourné uniquement pour les opérations d’ajout. Il retourne le décalage auquel le bloc a été validé, en octets.
x-ms-blob-committed-block-count Nombre de blocs validés présents dans l’objet blob. Vous pouvez l’utiliser pour contrôler le nombre d’ajouts supplémentaires qui peuvent être effectués.
x-ms-request-server-encrypted: true/false Version 2015-12-11 ou ultérieure. La valeur de cet en-tête est définie sur true si le contenu de la demande est correctement chiffré à l’aide de l’algorithme spécifié. Sinon, la valeur est false.
x-ms-encryption-key-sha256 Version 2019-02-02 ou ultérieure. Cet en-tête est retourné si la demande a utilisé une clé fournie par le client pour le chiffrement. Le client peut ensuite s’assurer que le contenu de la demande est correctement chiffré à l’aide de la clé fournie.
x-ms-encryption-scope Version 2019-02-02 ou ultérieure. Cet en-tête est retourné si la demande a utilisé une étendue de chiffrement. Le client peut ensuite s’assurer que le contenu de la demande est correctement chiffré à l’aide de l’étendue de chiffrement.
x-ms-client-request-id Vous pouvez utiliser cet en-tête pour résoudre les demandes et les 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 demande. La valeur est au maximum 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, cet en-tête n’est pas présent dans la réponse.

Exemple de réponse

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000

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 Append Block 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érationAppend Block, 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

Append Block charge un bloc à la fin d’un objet blob d’ajout existant. Le bloc de données est immédiatement disponible une fois l’appel réussi sur le serveur. Un maximum de 50 000 ajouts est autorisé pour chaque objet blob d’ajout. Chaque bloc peut être de taille différente.

Le tableau suivant décrit les tailles maximales autorisées de blocs et d’objets blob, par version de service :

Version du service Taille maximale du bloc (via Append Block) Taille maximale de l’objet blob
Version 2022-11-02 et versions ultérieures 100 Mio (préversion) Environ 4,75 Tio (100 Mio × 50 000 blocs)
Versions antérieures à 2022-11-02 4 Mio Environ 195 gibibytes (Gio) (4 Mio × 50 000 blocs)

Append Block réussit uniquement si l’objet blob existe déjà.

Les objets blob chargés à l’aide Append Block de n’exposent pas d’ID de bloc. Vous ne pouvez pas appeler Get Block List sur un objet blob d’ajout. Cela génère une erreur.

Vous pouvez spécifier les en-têtes facultatifs et conditionnels suivants sur la demande :

  • x-ms-blob-condition-appendpos: vous pouvez définir cet en-tête sur un décalage d’octet auquel le client s’attend à ajouter le bloc. La requête réussit uniquement si le décalage actuel correspond à celui spécifié par le client. Sinon, la demande échoue avec le code d’erreur 412 (Échec de la condition préalable).

    Les clients qui utilisent un enregistreur unique peuvent utiliser cet en-tête pour déterminer si une Append Block opération a réussi, malgré une défaillance réseau.

  • x-ms-blob-condition-maxsize: les clients peuvent utiliser cet en-tête pour s’assurer que les opérations d’ajout n’augmentent pas la taille de l’objet blob au-delà d’une taille maximale attendue en octets. Si la condition échoue, la demande échoue avec le code d’erreur 412 (Échec de la condition préalable).

Si vous tentez de charger un bloc supérieur à la taille autorisée, le service retourne le code d’erreur 413 (Entité de requête trop grande). Le service retourne également des informations supplémentaires sur l'erreur dans la réponse, notamment la taille du bloc maximale autorisée en octets. Si vous tentez de charger plus de 50 000 blocs, le service retourne le code d’erreur 409 (Conflit).

Si l'objet blob a un bail actif, le client doit spécifier un ID de bail valide dans la demande afin d'écrire un bloc dans l'objet blob. Si le client ne spécifie pas d’ID de bail ou qu’il spécifie un ID de bail non valide, Stockage Blob retourne le code d’erreur 412 (Échec de la condition préalable). Si le client spécifie un ID de bail, mais que l’objet blob n’a pas de bail actif, Stockage Blob retourne également le code d’erreur 412.

Si vous appelez Append Block sur un objet blob de blocs ou un objet blob de pages existant, le service retourne une erreur de conflit. Si vous appelez Append Block sur un objet blob inexistant, le service retourne également une erreur.

Éviter les ajouts dupliqués ou retardés

Dans un scénario d’écriture unique, le client peut éviter les ajouts en double ou les écritures différées à l’aide de l’en-tête *x-ms-blob-condition-appendpos conditionnel pour case activée le décalage actuel. Le client peut également éviter les doublons ou les retards en vérifiant le de manière conditionnelle, à l’aide ETagIf-Matchde .

Dans un scénario à plusieurs enregistreurs, chaque client peut utiliser des en-têtes conditionnels, mais cela peut ne pas être optimal pour les performances. Pour le débit d’ajout simultané le plus élevé, les applications doivent gérer les ajouts redondants et les ajouts différés dans la couche application. Par exemple, l’application peut ajouter des époques ou des numéros de séquence dans les données ajoutées.

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 Append Block les demandes en fonction du type de compte de stockage :

Opération Type de compte de stockage Catégorie de facturation
Append Block Objet blob de blocs Premium
Usage général v2 Standard
Usage général v1 standard		 Opérations d’écriture

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