Append Block From 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 est autorisée uniquement si l’objet blob a été créé avec x-ms-blob-type défini sur AppendBlob. Append Block From URL est pris en charge uniquement sur la version 2018-11-09 ou ultérieure.
Requête
Vous pouvez construire la Append Block From URL 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 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 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. Indique le nombre d'octets transmis dans le corps de demande. La valeur de cet en-tête doit être définie sur zéro. Lorsque la longueur n’est pas égale à zéro, l’opération échoue avec le code d’erreur 400 (Demande incorrecte). |
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, comme elle apparaît dans un URI de requête. L’objet blob source doit être public ou doit être 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/myblobhttps://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> |
facultatif. Spécifie le schéma d’autorisation et la signature pour la source de copie. Pour plus d’informations, consultez Autoriser les requêtes auprès du 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 |
facultatif. 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 |
facultatif. Hachage MD5 du contenu du 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 qui est arrivé à partir de la source de copie 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 (Demande incorrecte). |
x-ms-source-content-crc64 |
facultatif. Un hachage CRC64 du contenu du 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 qui est arrivé à partir de la source de copie 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 (Demande incorrecte). 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 (requête incorrecte).Cet en-tête est pris en charge dans la version 2019-02-02 ou ultérieure. |
x-ms-encryption-scope |
facultatif. 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 |
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. 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, ou si la taille de l’objet blob est déjà supérieure à la valeur spécifiée dans cet en-tête, la requête échoue avec un 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’octets à comparer. Append Block from URL réussit uniquement si la position d’ajout est égale à ce nombre. Si ce n’est pas le cas, la demande échoue avec un 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.
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: 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"
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 utilise la valeur pour effectuer des opérations conditionnelles PUT à l’aide de l’en-tête de If-Match requête. |
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 des 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. Stockage Blob calcule la valeur de cet en-tête. Il ne s’agit pas nécessairement de la même valeur spécifiée dans les en-têtes de requête. Pour la version 2019-02-02 ou ultérieure, cet en-tête est retourné uniquement lorsque la requête contient cet en-tête. |
x-ms-content-crc64 |
Pour la version 2019-02-02 ou ultérieure. Cet en-tête est renvoyé afin que le client puisse vérifier l'intégrité du contenu du message. Stockage Blob calcule la valeur de cet en-tête. 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 x-ms-source-content-md5 n’est pas présent dans la requête. |
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 la résolution des problèmes de la demande. |
x-ms-version |
Indique la version de Stockage Blob utilisée pour exécuter la requête. Cet en-tête est renvoyé pour les demandes effectuées avec la version 2009-09-19 ou une version ultérieure. |
Date |
Une valeur de date/heure UTC générée par le service qui indique le moment auquel la réponse a été initié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 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 true sur si le contenu de la requête 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. |
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 From URL comme décrit ci-dessous.
Les détails de l’autorisation de cette section s’appliquent à la destination de copie. Pour plus d’informations sur l’autorisation de copie de la source, consultez les détails de l’en-tête x-ms-copy-sourcede requête .
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érationAppend Block From URL, 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/add/action ou Microsoft.Storage/storageAccounts/blobServices/containers/blobs/blobs/write
- Rôle intégré avec privilèges minimum :Contributeur aux 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.
Remarques
Append Block From URL 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, où. 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 From URL) |
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) |
Dans les versions 2020-10-02 et ultérieures, Microsoft Entra ID autorisation est prise en charge pour la source de l’opération de copie.
Append Block From URL réussit uniquement si l’objet blob existe déjà.
Les objets blob chargés à l’aide Append Block From URL de n’exposent pas d’ID de bloc. Vous ne pouvez donc 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 seul enregistreur peuvent utiliser cet en-tête pour déterminer si une
Append Block From URLopé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 HTTP 413 (Requête d’entité 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, le service retourne le code d’erreur 412.
Si vous appelez Append Block From URL sur un objet blob de blocs ou un objet blob de pages existant, le service retourne le code d’erreur 409 (Conflit). Si vous appelez Append Block From URL sur un objet blob inexistant, le service retourne le code d’erreur 404 (introuvable).
É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. 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 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 Stockage Blob Azure Tarification.
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 From URL les demandes en fonction du type de compte de stockage :
| Opération | Type de compte de stockage | Catégorie de facturation |
|---|---|---|
| Ajouter un bloc à partir de l’URL (comptede destination 1) | Objet blob de blocs Premium Usage général v2 Standard Usage général v1 standard |
Opérations d’écriture |
| Ajouter un bloc à partir de l’URL (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 pour lancer l’écriture.
2Le compte source entraîne une transaction pour chaque demande de lecture adressée à la source.