Partager via

Put Block From URL

  • Article

L’opération Put Block From URL crée un nouveau bloc à commiter 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 Put Block From URL 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 l'encodage, la taille de la chaîne doit être inférieure ou égale à 64 octets.

Pour un objet blob spécifié, la longueur de la valeur spécifiée pour le 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 requêtes auprès du 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. Pour Put Block From URL, la version doit être 28-03-2018 ou ultérieure.
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 0. Lorsque la longueur n’est pas 0, l’opération échoue avec status code 400 (requête 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 Kibibytes (Kio) qui spécifie un objet blob. La valeur doit être encodée dans l’URL, comme elle apparaît dans un URI de 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> 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 un schéma de porteur est pris en charge pour Microsoft Entra.
Cet en-tête est pris en charge dans les versions 2020-10-02 et ultérieures.
x-ms-source-range facultatif. 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é, le contenu de l’objet blob source entier est chargé sous la forme d’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 facultatif. Hachage MD5 du contenu de bloc de l’URI. Ce hachage est utilisé pour vérifier l’intégrité du bloc pendant le 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é à partir 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 facultatif. Hachage CRC64 du contenu de bloc de l’URI. Ce hachage est utilisé pour vérifier l’intégrité du bloc pendant le 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é à partir 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 demande échoue avec une valeur 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 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 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

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

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. Elle 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 est retourné uniquement lorsque la requête contient cet en-tête.
x-ms-content-crc64 Pour les versions 2019-02-02 et ultérieures. 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. Elle n’est pas nécessairement identique à la valeur spécifiée dans les en-têtes de requête.

Retourné lorsque x-ms-source-content-md5 l’en-tête n’est pas présent dans la requête.
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 Version de Stockage Blob utilisée pour exécuter la demande.
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 si le contenu du bloc est correctement chiffré à true l’aide de l’algorithme spécifié. Sinon, la valeur est false.
x-ms-encryption-key-sha256 Version 2019-02-02 et ultérieures. 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. 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 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

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

Important

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

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, une identité managée ou un principal de service Microsoft Entra appelle l’opérationPut Block From URL, ainsi que 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

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

Dans les versions 2020-10-02 et ultérieures, 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 retourne status code 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 du bloc (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 tebibytes (Tio) (4 000 Mio × 50 000 blocs) 5 000 Mio
Versions antérieures à 2020-04-08 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 dans 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 From URL 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 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 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 collect.

Un bloc qui a été correctement chargé 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. Avant Put Block List d’être appelé pour valider l’objet blob nouveau ou mis à jour, tous les appels à Obtenir un 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é validée, le dernier bloc chargé avec cet ID est validée lors de l’opération réussie Put Block List suivante.

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 si aucun appel au Put Block From URL même objet blob ou Put Block List sur celui-ci n’a réussi 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 collecté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 qu’il spécifie un ID de bail non valide, 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, 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 chargé avec un ID de bloc d’une longueur différente de celle des ID de bloc pour tous les blocs non validés existants, le service retourne le code de réponse d’erreur 400 (demande incorrecte).

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

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

L’appel Put Block From URL d’un objet blob « archive » renvoie une erreur et l’appeler sur un hot objet blob ou cool ne modifie pas le niveau d’objet blob.

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 Put Block From URL les demandes en fonction du type de compte de stockage :

Opération Type de compte de stockage Catégorie de facturation
Put Block From URL (compte de destination1) Objet blob de blocs Premium
Usage général v2 Standard
Usage général v1 standard		 Opérations d’écriture
Put Block From 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 à 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 en sortie. Les sorties entre les comptes au sein de la même région sont gratuits.

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

Voir aussi