Mettre le blocage à partir de l’URL

Article
2025-05-11

L’opération Put Block From URL crée un nouveau bloc à valider dans le cadre d’un objet blob où le contenu est lu à partir d’une URL. Cette API est disponible à partir de la version 2018-03-28.

Requête

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

Demande de service de stockage émulée

Lorsque vous effectuez une demande sur le service de stockage émulé, spécifiez le nom d’hôte de l’émulateur et le port du service d’objets blob 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=block&blockid=id`	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
`blockid`	Obligatoire. Valeur de chaîne Base64 valide qui identifie le bloc. Avant l’encodage, la chaîne doit être inférieure ou égale à 64 octets de taille. Pour un objet blob spécifié, la longueur de la valeur spécifiée pour le `blockid` paramètre doit être la même pour chaque bloc. Remarque : La chaîne Base64 doit être encodée en URL.
`timeout`	Optionnel. 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	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 le 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 Contrôle de version pour les services stockage Azure. Pour `Put Block From URL`, la version doit être 2018-03-28 ou ultérieure.
`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 0. Lorsque la longueur n’est pas 0, l’opération échoue avec le code d’état 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 kibioctets (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. Remarque: seul un schéma de porteur est pris en charge pour Microsoft Entra. Remarque: si votre objet source est accessible publiquement ou si votre objet source se trouve dans un compte de stockage et que vous utilisez un jeton SAP passé dans `x-ms-copy-source:name`, cet en-tête n’est pas nécessaire. Cet en-tête est pris en charge dans les versions 2020-10-02 et ultérieures.
`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 cet en-tête n’est pas spécifié, l’intégralité du contenu de l’objet blob source est chargée en un seul bloc. Pour plus d’informations, consultez Spécifier l’en-tête de plage pour les opérations de service Blob.
`x-ms-source-content-md5`	Optionnel. Hachage MD5 du contenu du bloc à partir de l’URI. Ce hachage est utilisé pour vérifier l’intégrité du bloc lors du transport des données à partir de l’URI. Lorsque cet en-tête est spécifié, le service de stockage compare le hachage du contenu arrivé de la source de copie avec 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 (Demande incorrecte).
`x-ms-source-content-crc64`	Optionnel. Hachage CRC64 du contenu du bloc à partir de l’URI. Ce hachage est utilisé pour vérifier l’intégrité du bloc lors du transport des données à partir de l’URI. Lorsque cet en-tête est spécifié, le service de stockage compare le hachage du contenu arrivé de la source de copie avec 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 `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 les versions 2019-02-02 et ultérieures.
`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 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`	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-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.

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	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 `AES256`.

Corps de la requête

Aucun.

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: 2018-03-28  
x-ms-date: Sat, 31 Mar 2018 14:37:35 GMT    
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-499

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
`Content-MD5`	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 Stockage Blob. Il n’est pas nécessairement identique à la valeur spécifiée dans les en-têtes de requête. Pour les versions 2019-02-02 et ultérieures, cet en-tête n’est renvoyé que lorsque la demande a cet en-tête.
`x-ms-content-crc64`	Pour les versions 2019-02-02 et ultérieures. 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 Stockage Blob. Ce n’est pas nécessairement la même valeur que celle spécifiée dans les en-têtes de la requête. Renvoyé lorsque `x-ms-source-content-md5` l’en-tête 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 d’opérations d’API.
`x-ms-version`	Version de Stockage Blob utilisée pour exécuter la requête.
`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-request-server-encrypted: true/false`	Version 2015-12-11 et ultérieures. La valeur de cet en-tête est définie sur `true` si le contenu du bloc 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 et ultérieure. Renvoyé 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érieure. Renvoyé 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 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 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 requête, il 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: Sat, 31 Mar 2018 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

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

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 Put Block From URL et le rôle RBAC Azure intégré le moins privilégié qui inclut cette action :

action RBAC Azure :Microsoft.Storage/storageAccounts/blobServices/containers/blobs/blobs/write
rôle intégré moins privilégié :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 avez 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 a besoin pour ces ressources et la durée pendant laquelle la SAP est valide.

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

Comme meilleure pratique de sécurité, nous vous recommandons d’utiliser les informations d’identification Microsoft Entra plutôt que la clé de compte de stockage, qui peut être plus facilement compromise. Si la conception de votre 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, le cas échéant.

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 n’est pas autorisé sur une demande adressée au stockage Blob. Pour plus d’informations, consultez Comprendre comment le refus de la clé partagée affecte les jetons SAP.

Délégation d'utilisateur SAS

Une SAP de délégation d’utilisateur est sécurisée avec les informations d’identification Microsoft Entra et également par les autorisations spécifiées pour la SAP.

L’appel de l’opération de Put Block From URL à l’aide d’un jeton SAP délégué à un conteneur ou à une ressource d’objet blob nécessite l’autorisation écriture (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.

Service SAS

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

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

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

Compte SAS

Une SAP de compte est sécurisée avec 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
Mettre le blocage à partir de l’URL	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 de Put Block From URL prend en charge d’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 de refuser l’autorisation de clé partagée pour le compte de stockage si possible. Pour plus d’informations, consultez Empêcher l’autorisation avec lede clé partagée.

Remarques

Put Block From URL Télécharge un bloc pour une inclusion ultérieure dans un blob de blocs. Un objet blob de blocs peut inclure un maximum de 50 000 blocs. Chaque bloc peut être d’une taille différente. La taille maximale d’un bloc chargé avec Put Block From URL est de 100 mébioctets (Mio). Pour télécharger des blocs plus volumineux (jusqu’à 4 000 Mio), consultez Put Block.

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

Un objet blob peut avoir un maximum de 100 000 blocs non validés à tout moment. Si ce maximum est dépassé, le service renvoie le code d’état 409 (RequestEntityTooLargeBlockCountExceedsLimit).

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 `Put Block From URL`)	Taille maximale de l’objet blob (via `Put Block List`)	Taille maximale de l’objet blob via une opération d’écriture unique (via `Put Blob From URL`)
Version 2020-04-08 et ultérieures	4 000 Mio	Environ 190,7 tébioctets (Tio) (4 000 Mio × 50 000 blocs)	5 000 Mio
Versions antérieures au 08/04/2020	100 Mio	Environ 4,75 Tio (100 Mio × 50 000 blocs)	256 Mio

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 au sein de 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 From URL 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 avez téléchargés ne sont pas validés tant que vous n’avez pas appelé Put Block List 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é d’autres blocs ou validé des blocs à l’objet blob au cours de cette période, l’objet blob est nettoyé de la mémoire.

Un bloc qui a été chargé avec succès avec l’opération Put Block From URL ne fait pas partie d’un objet blob tant qu’il n’est pas validé avec Put Block List. Before Put Block List est appelé pour valider l’objet blob nouveau ou mis à jour, tous les appels à Get Blob renvoient 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é validé, le dernier bloc téléchargé avec cet ID est validé lors de la prochaine opération réussie Put Block List .

Une fois Put Block List l’appel effectué, tous les blocs non validés spécifiés dans la liste de blocage 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 blocage de l’objet blob sont des déchets collectés et supprimés du stockage d’objets blob. Tous les blocs non validés sont également récupérés s’il n’y a pas d’appels réussis vers Put Block From URL ou Put Block List sur le même objet blob dans la semaine suivant la dernière opération réussie Put Block From URL . Si Put Blob est appelé sur l’objet blob, tous les blocs non validés sont récupérés de la mémoire de 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 si un ID de bail non valide, le Stockage Blob renvoie le code d’état 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 le code d’état 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 de celle des ID de bloc pour des blocs non validés existants, le service renvoie le code de réponse d’erreur 400 (Bad Request).

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

L’appel Put Block From URL d’un objet blob de pages renvoie une erreur.

L’appel Put Block From URL d’un objet blob « archive » renvoie une erreur, et son appel 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 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 Put Block From URL en fonction du type de compte de stockage :

Opération	Type de compte de stockage	Catégorie de facturation
Placer le blocage de l’URL (compte^{de destination 1})	Objet blob de blocs Premium Standard v2 à usage général Standard v1 à usage général	Opérations d’écriture
Placer le blocage de l’URL (compte source²)	Objet blob de blocs Premium Standard v2 à usage général Standard v1 à usage général	Lire les opérations

¹Le compte de destination est facturé pour une transaction pour lancer l’écriture.
²Le compte source entraîne une transaction pour chaque demande de lecture à l’objet source.

En outre, si les comptes source et de destination résident dans différentes régions (par exemple, USA Nord et USA Sud), la bande passante utilisée pour transférer la demande est facturée au compte de stockage source comme sortie. La sortie entre les comptes au sein de la même région est gratuite.

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

Partager via