Put Block

Article
02/03/2024

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

Requête

Vous pouvez construire la Put Block requête comme suit. Nous vous recommandons d’utiliser HTTPS. Remplacez moncompte 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=block&blockid=id`	HTTP/1.1

Demande de service de stockage émulée

Lorsque vous effectuez une requête auprès du service de stockage émulé, spécifiez le nom d’hôte de l’émulateur et le port du service Blob comme 127.0.0.1:10000, suivi 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=block&blockid=id`	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
`blockid`	Obligatoire. Une valeur de chaîne Base64 valide qui identifie le bloc. Avant d’être encodée, la chaîne doit avoir une taille inférieure ou égale à 64 octets. Pour un objet blob spécifié, la longueur de la valeur du `blockid` paramètre doit être de la même taille pour chaque bloc. Remarque : 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éfinir des délais d’attente pour les opérations de service Blob.

En-têtes de requête

Les en-têtes de requête obligatoires et facultatifs sont décrits dans le tableau suivant :

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 Gestion de version pour les services de stockage Azure.
`Content-Length`	Obligatoire. La longueur du contenu du bloc, en octets. La taille du bloc doit être inférieure ou égale à 4 000 mebibytes (Mio) pour les versions 2019-12-12 et ultérieures. Consultez la section Remarques pour connaître les limites des versions antérieures . Lorsque la longueur n’est pas fournie, l’opération échoue avec le code status 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. Remarque : 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 (requête 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. Remarque : 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 (requête incorrecte). Cet en-tête est pris en charge dans les versions 2019-02-02 et 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 et 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 reçues par le serveur. Pour plus d’informations, consultez Surveiller Stockage Blob Azure.

En-têtes de requête (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 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 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 requête

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

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 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`	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, et ce n’est pas nécessairement la même valeur que celle spécifiée dans les en-têtes de requête. Pour les versions 2019-02-02 et 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 et 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, et elle n’est pas nécessairement la même que celle spécifiée dans les en-têtes de requête. Cet en-tête est retourné quand l’en-tête `Content-md5` n’est pas présent dans la demande.
`x-ms-request-id`	Identifie de manière unique la demande qui a été effectuée et vous pouvez l’utiliser pour résoudre la demande. Pour plus d’informations, consultez Résoudre les problèmes liés aux opérations d’API.
`x-ms-version`	Indique la version de Stockage Blob qui a été utilisée pour exécuter la demande. Cet en-tête est retourné pour les demandes effectuées sur la version 2009-09-19 ou ultérieure.
`Date`	Valeur de date/heure UTC générée par le service, qui indique quand la réponse a été lancée.
`x-ms-request-server-encrypted: true/false`	Version 2015-12-11 et ultérieures. 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 et ultérieures. Cet en-tête est retourné si la demande a utilisé 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 et ultérieures. 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`	Peut être utilisé pour résoudre les problèmes liés aux demandes et aux 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 requête et que la valeur ne contient pas plus 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, il 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: Sun, 25 Sep 2011 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

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 Put Block comme décrit ci-dessous.

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érationPut Block, 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/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.

Une signature d’accès partagé (SAP) fournit un accès délégué sécurisé aux ressources d’un compte de stockage. Avec une SAP, vous disposez d’un contrôle granulaire sur la façon dont un client peut accéder aux données. Vous pouvez spécifier la ressource à laquelle le client peut accéder, les autorisations dont il dispose sur ces ressources et la durée de validité de la signature d’accès partagé.

L’opération Put Block prend en charge trois types de signatures d’accès partagé : SAP de délégation d’utilisateur, SAP de service et SAP de compte.

En guise de meilleure pratique en matière de sécurité, nous vous recommandons d’utiliser des informations d’identification Microsoft Entra plutôt que la clé de compte de stockage, qui peut être plus facilement compromise. Si votre conception d’application nécessite des signatures d’accès partagé, utilisez les informations d’identification Microsoft Entra pour créer une sap de délégation d’utilisateur, si possible.

Lorsque l’accès à la clé partagée n’est pas autorisé pour le compte de stockage, un jeton SAP de service ou un jeton SAP de compte ne sont pas autorisés lors d’une demande adressée au Stockage Blob. Pour en savoir plus, consultez Comprendre comment l’interdiction de la clé partagée affecte les jetons SAP.

SAP de délégation d’utilisateur

Une sap de délégation d’utilisateur est sécurisée avec des informations d’identification Microsoft Entra, ainsi que par les autorisations spécifiées pour la signature d’accès partagé.

L’appel de l’opération à l’aide Put Block d’un jeton SAP délégué à un conteneur ou à une ressource d’objet blob nécessite l’autorisation Write (w) dans le cadre du jeton SAP de délégation d’utilisateur.

Pour en savoir plus sur la SAP de délégation d’utilisateur, consultez Créer une SAP de délégation d’utilisateur.

SAP de service

Une SAP de service est sécurisée à l’aide de la clé de compte de stockage. Une SAP de service délègue l’accès à une ressource dans un seul service de stockage Azure, tel que le stockage d’objets blob.

L’appel de l’opération à l’aide Put Block d’un jeton SAP délégué à un conteneur ou à une ressource d’objet blob nécessite l’autorisation Write (w) dans le cadre du jeton SAS de service.

Pour en savoir plus sur la SAP de service, consultez Créer une SAP de service.

SAP de compte

Une SAP de compte est sécurisée à l’aide de la clé de compte de stockage. Une SAP de compte délègue l’accès aux ressources d’un ou plusieurs des services de stockage. Toutes les opérations disponibles via une SAP de service ou de délégation d’utilisateur sont également disponibles via une SAP de compte.

Le tableau suivant indique le type de ressource signé et les autorisations signées à spécifier lors de la délégation de l’accès :

Opération	Service signé	Type de ressource signé	Autorisation signée
Put Block	Blob (b)	Objet (o)	Écriture (w)

Pour en savoir plus sur la SAP de compte, consultez Créer une SAP de compte.

L’opération Put Block prend en charge l’autorisation de clé partagée. L’autorisation avec des clés de compte n’est pas recommandée pour la plupart des scénarios, car elle est moins sécurisée.

Microsoft recommande d’interdire l’autorisation de clé partagée pour le compte de stockage lorsque cela est possible. Pour plus d’informations, consultez Empêcher l’autorisation avec une clé partagée.

Remarques

Put Block télécharge un bloc pour l'inclure ultérieurement dans un objet blob de blocs. Chaque bloc d’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 autorisées de blocs et d’objets blob, par version de service :

Version du service	Taille maximale du bloc (via `Put Block`)	Taille maximale de l’objet blob (via `Put Block List`)	Taille maximale de l’objet blob via une seule opération d’écriture (via `Put Blob`)
Version 2019-12-12 et ultérieure	4 000 Mio	Environ 190,7 tbioctets (Tio) (4 000 Mio × 50 000 blocs)	5 000 Mio
Versions 2016-05-31 à 2019-07-07	100 Mio	Environ 4,75 Tio (100 Mio × 50 000 blocs)	256 Mio
Versions antérieures à 31/05/2016	4 Mio	Environ 195 gibibytes (Gio) (4 Mio × 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 ce nombre est dépassé, le service retourne status code 409 (RequestEntityTooLargeBlockCountExceedsLimit).

Une fois que vous avez chargé un ensemble de blocs, vous pouvez créer ou mettre à jour l’objet blob sur le serveur à partir de cet ensemble en appelant l’opération Put Block List . Chaque bloc de l’ensemble est identifié par un ID de bloc unique dans cet objet blob. Les ID de bloc sont limités à un objet blob particulier, de sorte que différents objets blob peuvent 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 de blocs est créé avec une longueur de contenu de 0. Cet objet blob est énuméré par l'opération List Blobs si l'option include=uncommittedblobs est spécifiée. Le ou les blocs que vous chargez ne sont pas validés tant que vous n’appelez Put Block List pas sur le nouvel objet blob. Un objet blob créé de cette façon est conservé sur le serveur pendant une semaine. Si vous n’avez pas ajouté de blocs ou de blocs validés à l’objet blob au cours de cette période, l’objet blob est récupéré par le garbage collection.

Un bloc qui a été correctement chargé avec l’opération Put Block ne fait pas partie d’un objet blob tant qu’il n’est pas validé avec Put Block List. Avant Put Block List d’être appelé pour valider l’objet blob nouveau ou mis à jour, tous les appels à Obtenir l’objet blob retournent le contenu de l’objet blob sans inclure le bloc non validé.

Si vous chargez un bloc qui a le même ID de bloc qu’un autre bloc qui n’a pas encore été commité, le dernier bloc chargé avec cet ID sera commité lors de la prochaine opération réussie Put Block List .

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 sont collectés et supprimés du Stockage Blob. Tous les blocs non validés sont également collectés par la mémoire s’il n’y a pas d’appels réussis vers Put Block ou Put Block List sur le même objet blob dans la semaine suivant la dernière opération réussie Put Block . Si Put Blob est appelé sur l’objet blob, tous les blocs non validés sont récupérés par la mémoire.

Si l’objet blob a un bail actif, le client doit spécifier un ID de bail valide sur la demande d’écriture d’un bloc dans l’objet blob. Si le client ne spécifie pas d’ID de bail ou spécifie un ID de bail non valide, le Stockage Blob retourne status code 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 Stockage Blob retourne également status code 412 (échec de la condition préalable).

Pour un objet blob spécifié, 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 supérieur à 4 000 Mio pour la version 2019-12-12 ou ultérieure, supérieur à 100 Mio pour la version 2016-05-31 ou ultérieure, ou supérieur à 4 Mio pour les versions antérieures, le service retourne status code 413 (Entité de requête trop grande). Le service retourne également des informations supplémentaires sur l’erreur dans la réponse, y compris la taille de bloc maximale autorisée, en octets.

L’appel 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.

L’appel Put Block sur un objet blob archivé renvoie une erreur et l’appeler sur un hot objet blob ou cool ne modifie pas le niveau de l’objet blob.

Facturation

Les demandes de tarification peuvent provenir de clients qui utilisent les API Stockage Blob, soit directement via l’API REST Stockage Blob, soit à 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 d’écriture. Le tableau suivant montre la catégorie de facturation pour Put Block les demandes en fonction du type de compte de stockage :

Opération	Type de compte de stockage	Catégorie de facturation
Put 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 tarification Stockage Blob Azure.

Voir aussi

Autoriser les demandes dans le Stockage Azure
Codes d’état et d’erreur
Codes d’erreur du service Blob
Définir des délais d’attente pour les opérations de service Blob