Put Block

L'opération Put Block crée un nouveau bloc à valider dans le cadre d'un objet blob.

Requête

La demande Put Block peut être construite comme indiqué ci-dessous. HTTPS est recommandé. Remplacez moncompte par le nom de votre compte de stockage :

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

URI du service de stockage émulé

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 demande de la méthode PUT Version HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

pour plus d’informations, consultez utilisation du Emulator stockage Azure pour le développement et le test.

Paramètres URI

Paramètre Description
blockid Obligatoire. Une valeur de chaîne Base64 valide qui identifie le bloc. Avant l'encodage, la taille de la chaîne doit être inférieure ou égale à 64 octets.

Pour un objet blob donné, la longueur de la valeur spécifiée pour le paramètre blockid doit être identique pour chaque bloc.

Notez que la chaîne Base64 doit être encodée dans l'URL.
timeout Facultatif. Le paramètre timeout est exprimé en secondes. Pour plus d’informations, consultez définition de délais d’attente pour les opérations de service 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 de compte et la signature. pour plus d’informations, consultez autoriser les demandes à 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 demandes à 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 contrôle de version pour les Services stockage Azure.
Content-Length Obligatoire. La longueur du contenu du bloc, en octets. La taille du bloc doit être inférieure ou égale à 4000 MiB pour la version 2019-12-12 et les versions ultérieures. Consultez les notes pour connaître les limites des 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. 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 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 un 400 (demande incorrecte).

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 1 Kio de caractères qui est enregistrée dans les journaux d’analyse lorsque la journalisation de l’analyse de stockage est activée. L’utilisation de cet en-tête est fortement recommandée pour la mise en corrélation des activités côté client avec les requêtes reçues par le serveur. pour plus d’informations, consultez à propos de la journalisation des Storage Analytics et de la journalisation Azure : utilisation des journaux pour suivre les demandes de Stockage.

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

À partir de la version 2019-02-02, les en-têtes suivants peuvent être spécifiés sur la demande pour chiffrer un objet BLOB avec une clé fournie par le client. Le chiffrement avec une clé fournie par le client (et le jeu 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 encodé 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 demande

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048576  

Réponse

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 d’État, 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 aussi 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
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 le service BLOB ; elle n'est pas nécessairement identique à la valeur spécifiée dans les en-têtes de demande. Pour les versions 2019-02-02 ou ultérieures, cet en-tête est retourné uniquement lorsque la requête 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 vérifier l’intégrité du contenu du message. La valeur de cet en-tête est calculée par le service BLOB ; elle n'est pas nécessairement identique à la valeur spécifiée dans les en-têtes de demande.

Cet en-tête est retourné lorsque Content-md5 l’en-tête n’est pas présent dans la demande.
x-ms-request-id Cet en-tête identifie de façon unique la demande qui a été effectuée et peut être utilisé pour résoudre les problèmes de la demande. Pour plus d’informations, consultez Troubleshooting API Operations.
x-ms-version Indique la version du service 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 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-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é et dans le false cas contraire.
x-ms-encryption-key-sha256 Version 2019-02-02 ou ultérieure. Cet en-tête est retourné si la demande utilise une clé fournie par le client pour le chiffrement, afin que le client puisse 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, afin que le client puisse s’assurer que le contenu de la demande est correctement chiffré à l’aide de l’étendue de chiffrement.
x-ms-client-request-id Cet en-tête peut être utilisé pour dépanner les demandes et les réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l' x-ms-client-request-id en-tête si elle est présente dans la demande et que la valeur est supérieure à 1024 caractères ASCII visibles. Si l' x-ms-client-request-id en-tête n’est pas présent dans la demande, cet en-tête ne sera 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: Sun, 25 Sep 2011 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  

Autorisation

Cette opération peut être appelée par le propriétaire du compte ou par toute personne avec une signature d'accès partagé qui dispose des autorisations pour écrire dans cet objet blob ou son conteneur.

Remarques

Put Block télécharge un bloc pour l'inclure ultérieurement dans un objet blob de blocs. Chaque bloc dans un objet blob de blocs peut avoir une taille différente. Un objet blob de blocs peut inclure un maximum de 50 000 blocs validés. Le tableau suivant décrit les tailles maximales de blocs et d’objets BLOB autorisées par la version du service :

Version du service Taille de bloc maximale (via Put Block) Taille de blob maximale (via Put Block List) Taille de blob maximale via une seule opération d’écriture (via Put Blob)
Version 2019-12-12 et ultérieure 4 000 Mio Environ 190,7 Tio (4 000 Mio X 50 000 blocs) 5 000 Mio (préversion)
De la version 2016-05-31 à la version 2019-07-07 100 Mio Environ 4,75 Tio (100 Mio X 50 000 blocs) 256 Mio
Versions antérieures à 2016-05-31 4 Mio Environ 195 Gio (4 Mio X 50 000 blocs) 64 Mio

Le nombre maximal de blocs non validés qui peuvent être associés à un objet blob est de 100 000. Si cette valeur maximale est dépassée, le service retourne le code d’État 409 (RequestEntityTooLargeBlockCountExceedsLimit).

Après avoir téléchargé un ensemble de blocs, vous pouvez créer ou mettre à jour l’objet BLOB sur le serveur à partir de ce jeu en appelant l’opération Put Block List . Chaque bloc dans l'ensemble est identifié par un ID de bloc qui est unique au sein de cet objet blob. Les ID de bloc dépendent d'un objet blob particulier, afin que les différents objets blob puissent avoir des blocs avec les mêmes ID.

Si vous appelez Put Block sur un objet blob qui n'existe pas encore, un nouvel objet blob est créé avec un contenu d'une longueur égale à 0. Cet objet blob est énuméré par l'opération List Blobs si l'option include=uncommittedblobs est spécifiée. Le bloc ou les blocs que vous avez téléchargés ne sont pas validés tant que vous n'appelez pas Put Block List sur le nouvel objet blob. Un objet blob créé de cette manière est conservé sur le serveur pendant une semaine ; si vous n'avez pas ajouté de blocs ou validé des blocs pour l'objet blob pendant cette période, l'objet blob est récupéré par le garbage collector.

Un bloc qui a été correctement téléchargé avec l'opération Put Block ne fait pas partie d'un objet blob tant qu'il n'a pas été validé avec Put Block List. Avant que Put Block List soit appelé pour valider l’objet BLOB nouveau ou mis à jour, tous les appels à obtenir l’objet BLOB renvoient le contenu de l’objet BLOB sans l’inclusion du bloc non validé.

Si vous téléchargez un bloc dont l'ID est identique à un autre ID de bloc qui n'a pas encore été validé, le dernier bloc téléchargé qui porte cet ID sera validé lors de la prochaine opération Put Block List réussie.

Une fois Put Block List appelé, tous les blocs non validés spécifiés dans la liste de blocs sont validés dans le cadre du nouvel objet blob. Tous les blocs non validés qui n'ont pas été spécifiés dans la liste de blocs pour l'objet blob seront récupérés par le garbage collector et supprimés du service BLOB. Tous les blocs non validés seront également récupérés par le garbage collector s'il n'existe aucun appel réussi à Put Block ou à Put Block List sur l'objet blob dans la semaine qui suit la dernière opération Put Block réussie. Si l' objet BLOB put est appelé sur l’objet BLOB, tous les blocs non validés seront récupérés par le garbage collector.

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 un ID de bail ou spécifie un ID de bail incorrect, le service BLOB retourne le code d'état 412 (Échec de la précondition). Si le client spécifie un ID de bail, mais que l'objet blob n'a pas de bail actif, le service BLOB retourne également le code d'état 412 (Échec de la précondition).

Pour un objet blob donné, tous les ID de bloc doivent avoir la même longueur. Si un bloc est téléchargé avec un ID de bloc d'une longueur différente des ID de bloc des blocs non validés existants, le service retourne le code de réponse d'erreur 400 (Demande incorrecte).

Si vous tentez de charger un bloc d’une taille supérieure à 4000 MiB pour la version 2019-12-12 ou ultérieure, supérieure à 100 MiB pour la version 2016-05-31 et ultérieure et supérieure à 4 MiB pour les versions antérieures, le service retourne le code d’État 413 (entité de demande 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.

L'appel de Put Block ne met pas à jour l'heure de la dernière modification d'un objet blob existant.

L'appel de Put Block sur un objet blob de pages retourne une erreur.

Put BlockL’appel de sur un objet BLOB archivé retourne une erreur et, sur un Hot / Cool objet BLOB, ne modifie pas le niveau de l’objet BLOB.

Voir aussi

autoriser les demandes à stockage Azure
Codes d’État et d’erreur
Codes d’erreur du service BLOB
Définition de délais d'expiration pour les opérations du service BLOB