Partager via

Ajouter un bloc à partir de l’URL

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

L’opération Append Block From URL n’est autorisée que si l’objet blob a été créé avec x-ms-blob-type la valeur .AppendBlob Append Block From URL n’est pris en charge que sur la version 2018-11-09 ou ultérieure.

Requête

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

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

Lorsque vous effectuez une demande sur le service de stockage émulé, spécifiez le nom d’hôte de l’émulateur et le port de Stockage Blob Azure sous la forme 127.0.0.1:10000, suivis du nom du compte de stockage émulé.

URI de demande 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 pour le développement Azure Storage local.

Paramètres d’URI

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

En-têtes de requête

Le tableau suivant décrit les en-têtes de requête obligatoires et facultatifs.

En-tête de requête Descriptif
Authorization Obligatoire. Spécifie le schéma d’autorisation, le nom du compte et la signature. Pour plus d’informations, consultez Autoriser les demandes vers stockage Azure.
Date ou x-ms-date Obligatoire. Spécifie le temps universel coordonné (UTC) de la requête. Pour plus d’informations, consultez Autoriser les demandes vers le stockage Azure.
x-ms-version Obligatoire pour toutes les demandes autorisées. Spécifie la version de l’opération à utiliser pour cette requête. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure.
Content-Length Obligatoire. Spécifie le nombre d’octets transmis dans le corps de la requête. La valeur de cet en-tête doit être définie sur zéro. Lorsque la longueur n’est pas nulle, l’opération échoue avec le code d’erreur 400 (Bad Request).
x-ms-copy-source:name Obligatoire. Spécifie l’URL de l’objet blob source. La valeur peut être une URL d’une longueur maximale de 2 Kio qui spécifie un objet blob. La valeur doit être encodée en URL, telle qu’elle apparaîtrait dans l’URI d’une requête. L’objet blob source doit être public ou autorisé via une signature d’accès partagé. Si l’objet blob source est public, aucune autorisation n’est requise pour effectuer l’opération. Voici quelques exemples d’URL d’objet source :

https://myaccount.blob.core.windows.net/mycontainer/myblob
https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> Optionnel. Spécifie le schéma d’autorisation et la signature de la source de copie. Pour plus d’informations, consultez Autoriser les demandes vers le stockage Azure.
Seul le porteur de schéma est pris en charge pour Microsoft Entra ID.
Cet en-tête est pris en charge dans la version 2020-10-02 et ultérieure.
x-ms-source-range Optionnel. Télécharge uniquement les octets de l’objet blob dans l’URL source dans la plage spécifiée. Si ce n’est pas spécifié, l’intégralité du contenu de l’objet blob source est chargée en tant que bloc d’ajout unique. Pour plus d’informations , consultez Spécification de l’en-tête de plage pour les opérations de Stockage Blob .
x-ms-source-content-md5 Optionnel. Hachage MD5 du contenu de bloc d’ajout à partir de l’URI. Ce hachage est utilisé pour vérifier l’intégrité du bloc d’ajout pendant le transport des données à partir de l’URI. Lorsque vous spécifiez cet en-tête, le service de stockage compare le hachage du contenu provenant de copy-source avec 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 (Bad Request).
x-ms-source-content-crc64 Optionnel. Hachage CRC64 du contenu de bloc d’ajout à partir de l’URI. Ce hachage est utilisé pour vérifier l’intégrité du bloc d’ajout pendant le transport des données à partir de l’URI. Lorsque vous spécifiez cet en-tête, le service de stockage compare le hachage du contenu provenant de copy-source avec 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 (Bad Request).

Si les en-têtes x-ms-source-content-md5 et x-ms-source-content-crc64 sont présents, la requête échoue avec un 400 (Bad Request).

Cet en-tête est pris en charge dans la version 2019-02-02 ou ultérieure.
x-ms-encryption-scope Optionnel. Indique l’étendue de chiffrement à utiliser pour chiffrer le contenu source. Cet en-tête est pris en charge dans la version 2019-02-02 ou ultérieure.
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 Optionnel. Fournit une valeur opaque générée par le client avec une limite de caractères de 1 kibioctet (KiB) 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 reçues par le serveur. Pour plus d’informations, consultez Monitor Stockage Blob Azure.
x-ms-blob-condition-maxsize En-tête conditionnel facultatif. Longueur maximale en octets autorisée pour l’objet blob d’ajout. Si l’opération Append Block From URL entraîne le dépassement de cette limite par l’objet blob, 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 la réponse 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 from URL . Nombre indiquant le décalage d’octet à comparer. Append Block from URL ne réussit que si la position append est égale à ce nombre. Si ce n’est pas le cas, la demande échoue avec un 412 (Precondition Failed).
x-ms-file-request-intent Obligatoire si l’en-tête est une URL de fichier Azure et x-ms-copy-source que x-ms-copy-source-authorization l’en-tête spécifie un jeton OAuth. La valeur acceptable est backup. Cet en-tête spécifie que les Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action doivent être accordés s’ils sont inclus dans la stratégie RBAC affectée à l’identité autorisée à l’aide de l’en-tête x-ms-copy-source-authorization. Disponible pour la version 2025-07-05 et les versions ultérieures.

Cette opération prend en charge l’utilisation d’en-têtes conditionnels supplémentaires, afin de garantir que l’API ne réussit que 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 d’objets blob.

En-têtes de demande (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 à l’aide d’une clé fournie par le client (et de l’ensemble d’en-têtes correspondant) est facultatif.

En-tête de requête Descriptif
x-ms-encryption-key Obligatoire. Clé de chiffrement AES-256 codé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 requête

Le corps de la requête 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: 2018-11-09  
x-ms-date: <date>  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0 
If-Match: "0x8CB172A360EC34B"

Réponse

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

Code de statut

Une opération réussie retourne le code d’état 201 (créé). Pour plus d’informations sur les codes d’état, consultez Les codes d’état et d’erreur.

En-têtes de réponse

La réponse de cette 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 de protocole HTTP/1.1.

En-tête de réponse Descriptif
Etag Le ETag contient une valeur entre guillemets. Le client utilise la valeur pour effectuer des opérations conditionnelles PUT à l’aide de l’en-tête de demande If-Match .
Last-Modified Date/heure de la dernière modification de l’objet blob. Le format de date suit RFC 1123. Pour plus d’informations, consultez Représentation des valeurs date-heure dans les en-têtes.

Toute opération d’écriture sur l’objet blob (y compris les mises à 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.
Content-MD5 Cet en-tête est retourné afin que le client puisse vérifier l’intégrité du contenu du message. Le stockage Blob calcule la valeur de cet en-tête. Il ne s’agit pas nécessairement de la même valeur que celle spécifiée dans les en-têtes de la requête. Pour la version 2019-02-02 ou ultérieure, cet en-tête n’est renvoyé que lorsque la demande a cet en-tête.
x-ms-content-crc64 Pour la version 2019-02-02 ou ultérieure. Cet en-tête est retourné afin que le client puisse vérifier l’intégrité du contenu du message. Le stockage Blob calcule la valeur de cet en-tête. Il ne s’agit pas nécessairement de la même valeur que celle spécifiée dans les en-têtes de la requête.

Cet en-tête est renvoyé lorsqu’il x-ms-source-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 résoudre les 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 retourné pour les requêtes effectuées sur la version 2009-09-19 et ultérieures.
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-blob-append-offset Cet en-tête de réponse est retourné uniquement pour les opérations d’ajout. Elle retourne le décalage au niveau duquel 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 requête est correctement chiffré à l’aide de l’algorithme spécifié. Sinon, la valeur est définie sur false.
x-ms-encryption-key-sha256 Version 2019-02-02 ou ultérieure. Cet en-tête est renvoyé 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 renvoyé si la demande a utilisé une portée de chiffrement. Le client peut ensuite s’assurer que le contenu de la demande est correctement chiffré à l’aide de l’étendue de chiffrement.

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

L’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 de Append Block From URL comme décrit ci-dessous.

Les détails d’autorisation de cette section s’appliquent à la destination de la copie. Pour plus d’informations sur l’autorisation de copie de source, consultez les détails de l’en-tête x-ms-copy-sourcede demande .

Important

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

Stockage Azure prend en charge l’utilisation de l’ID Microsoft Entra pour l'autorisation des demandes de données blob. Avec l’ID Microsoft Entra, 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 demande auprès du service Blob.

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

Autorisations

Voici l’action RBAC nécessaire pour un utilisateur, un groupe, une identité managée ou un principal de service Microsoft Entra pour appeler l’opération de Append Block From URL et 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

Append Block From URL Télécharge un bloc à la fin d’un objet blob d’ajout existant. Le bloc de données est immédiatement disponible après la réussite de l’appel 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 des blocs (via Append Block From URL) Taille maximale de l’objet blob
Version 2022-11-02 et ultérieures 100 Mo (préversion) Environ 4,75 Tio (100 Mio × 50 000 blocs)
Versions antérieures au 02/11/2022 4 Mio Environ 195 gigiooctets (Gio) (4 Mio × 50 000 blocs)

Dans la version 2020-10-02 et les versions ultérieures, l’autorisation Microsoft Entra ID est prise en charge pour la source de l’opération de copie.

Append Block From URL ne réussit que si l’objet blob existe déjà.

Les objets blob téléchargés à l’aide de l’option Append Block From URL n’exposent pas les ID de bloc, vous ne pouvez donc pas appeler Get Block List sur un objet blob d’ajout. Cela entraîne une erreur.

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

  • x-ms-blob-condition-appendpos: Vous pouvez définir cet en-tête sur un décalage d’octets auquel le client s’attend à ajouter le bloc. La demande n’aboutit que si l’offset 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 seul enregistreur peuvent utiliser cet en-tête pour déterminer si une Append Block From URL opération a réussi, malgré une défaillance du 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 télécharger un bloc dont la taille est supérieure à la taille autorisée, le service renvoie le code d’erreur HTTP 413 (Request Entity Too Large). Le service renvoie également des informations supplémentaires sur l’erreur dans la réponse, y compris la taille maximale de bloc autorisée en octets. Si vous tentez de télécharger plus de 50 000 blocs, le service renvoie le code d’erreur 409 (Conflit).

Si l’objet blob a un bail actif, le client doit spécifier un ID de bail valide sur la demande afin d’écrire un bloc dans l’objet blob. Si le client ne spécifie pas d’ID de bail ou si un ID de bail non valide, le Stockage Blob renvoie 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, le service retourne le code d’erreur 412.

Si vous appelez Append Block From URL un objet blob de blocs ou de pages existant, le service renvoie le code d’erreur 409 (Conflit). Si vous appelez Append Block From URL un objet blob inexistant, le service renvoie le code d’erreur 404 (introuvable).

Évitez les ajouts en double ou retardés

Dans un scénario à enregistreur unique, le client peut éviter les ajouts en double ou les écritures différées en utilisant l’en-tête x-ms-blob-condition-appendpos conditionnel pour vérifier le décalage actuel. Le client peut également éviter les doublons ou les retards en vérifiant conditionnellement ETag , en utilisant If-Match.

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

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

Facturation

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

Opération Type de compte de stockage Catégorie de facturation
Ajouter l’URL de blocage (compte de destination1) Objet blob de blocs Premium
Usage général v2 Standard
Usage général v1 standard		 Opérations d’écriture
Ajouter l’URL de blocage à partir de (compte source2) Objet blob de blocs Premium
Usage général v2 Standard
Usage général v1 standard		 Lire les opérations

1Le compte de destination est facturé pour une transaction afin de lancer l’écriture.
deuxLe compte source effectue une transaction pour chaque demande de lecture adressée à la source.