Put Page From URL

L’opération Put Page From URL écrit une plage de pages dans un objet blob de pages où le contenu est lu à partir d’une URL. Cette API est disponible à partir de la version 2018-11-09.

Requête

La demande Put Page From URL 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=page 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=page HTTP/1.1

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

Paramètres URI

Les paramètres supplémentaires suivants peuvent être spécifiés dans l'URI de la demande.

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 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 du 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 des services stockage Azure.
Range Range ou x-ms-range est requis.

Spécifie la plage d'octets à écrire en tant que page. Le début et la fin de la plage doivent être spécifiés. Cet en-tête est défini par la spécification du protocole HTTP/1.1.

Pour une opération de mise à jour de page, la plage de pages peut être jusqu’à 4 MiB en taille.

Étant donné que les pages doivent être alignées avec des limites de 512 octets, le décalage de début doit être un modulo de 512 et la fin doit être un modulo de 512 – 1. Des exemples de plages d'octets valides sont 0-511, 512-1023, etc.

Le service BLOB accepte une seule plage d'octets pour l'en-tête Range, et la plage d'octets doit être spécifiée dans le format suivant : bytes=startByte-endByte.

Si Range et x-ms-range sont spécifiés, le service utilise la valeur de x-ms-range. Pour plus d’informations , consultez Spécification de l’en-tête de plage pour les opérations de service Blob .
x-ms-range Range ou x-ms-range est requis.

Spécifie la plage d'octets à écrire en tant que page. Le début et la fin de la plage doivent être spécifiés. Cet en-tête est défini par la spécification du protocole HTTP/1.1.

La plage de pages peut être jusqu’à 4 MiB en taille.

Étant donné que les pages doivent être alignées avec des limites de 512 octets, le décalage de début doit être un modulo de 512 et la fin doit être un modulo de 512 – 1. Des exemples de plages d'octets valides sont 0-511, 512-1023, etc.

Le service BLOB accepte une seule plage d'octets pour l'en-tête x-ms-range, et la plage d'octets doit être spécifiée dans le format suivant : bytes=startByte-endByte.

Si Range et x-ms-range sont spécifiés, le service utilise la valeur de x-ms-range. Pour plus d’informations , consultez Spécification de l’en-tête de plage pour les opérations de service Blob .
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 zéro, l’opération échoue avec le code d’état 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 de jusqu’à 2 KiB de longueur qui spécifie un objet blob. La valeur doit être encodée sous forme d'URL, comme dans une URI de demande. 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/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 demandes à stockage Azure.
Seul le porteur de schéma est pris en charge pour Azure Active Directory.
Cet en-tête est pris en charge dans les versions 2020-10-02 et ultérieures.
x-ms-source-range Charge les octets de l’objet blob dans l’URL source dans la plage spécifiée. Le début et la fin de la plage doivent être spécifiés. Cet en-tête est défini par la spécification du protocole HTTP/1.1.

La plage de pages peut être jusqu’à 4 MiB en taille.

Le service BLOB accepte une seule plage d'octets pour l'en-tête x-ms-source-range, et la plage d'octets doit être spécifiée dans le format suivant : bytes=startByte-endByte.

Pour plus d’informations , consultez Spécification de l’en-tête de plage pour les opérations de service Blob .
x-ms-source-content-md5 facultatif. Hachage MD5 du contenu de la page à partir de l’URI. Ce hachage est utilisé pour vérifier l’intégrité de la page 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 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. Hachage CRC64 du contenu de la page à partir de l’URI. Ce hachage est utilisé pour vérifier l’intégrité de la page 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 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 et x-ms-source-content-crc64 les deux x-ms-source-content-md5 sont présents, la requête échoue avec une requête 400 (requête incorrecte).

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-if-sequence-number-le: <num> facultatif. Si le numéro de séquence de l'objet blob est inférieur ou égal à la valeur spécifiée, la demande continue ; dans le cas contraire elle échoue avec l'erreur SequenceNumberConditionNotMet (code d'état HTTP 412 – Échec de la précondition).
x-ms-if-sequence-number-lt: <num> facultatif. Si le numéro de séquence de l'objet blob est inférieur à la valeur spécifiée, la demande continue ; dans le cas contraire elle échoue avec l'erreur SequenceNumberConditionNotMet (code d'état HTTP 412 – Échec de la précondition).
x-ms-if-sequence-number-eq: <num> facultatif. Si le numéro de séquence de l'objet blob est égal à la valeur spécifiée, la demande continue ; dans le cas contraire elle échoue avec l'erreur SequenceNumberConditionNotMet (code d'état HTTP 412 – Échec de la précondition).
If-Modified-Since facultatif. Valeur DateTime. Spécifiez cet en-tête conditionnel pour écrire la page uniquement si l'objet blob été modifié depuis la date/l'heure indiquées. Si l'objet blob n'a pas été modifié, le service BLOB retourne le code d'état 412 (Échec de la précondition).
If-Unmodified-Since facultatif. Valeur DateTime. Spécifiez cet en-tête conditionnel pour écrire la page uniquement si l'objet blob n'a pas été modifié depuis la date/l'heure indiquées. Si l'objet blob a été modifié, le service BLOB retourne le code d'état 412 (Échec de la précondition).
If-Match facultatif. Spécifiez une valeur ETag. Spécifiez une valeur d'ETag pour cet en-tête conditionnel pour écrire la page uniquement si la valeur d'ETag de l'objet blob correspond à la valeur spécifiée. Si les valeurs ne correspondent pas, le service BLOB renvoie le code d'état 412 (Échec de la précondition).
If-None-Match facultatif. Spécifiez une valeur ETag.

Spécifiez une valeur d'ETag pour cet en-tête conditionnel pour écrire la page uniquement si la valeur d'ETag de l'objet blob ne correspond pas à la valeur spécifiée. Si les valeurs sont identiques, le service BLOB renvoie le code d'état 412 (Échec de la précondition).
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 ou ultérieures.
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 Kio enregistrée dans les journaux d’analyse lorsque la journalisation d’analytique 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 About Storage Analytics Logging and Azure Logging: Using Logs to Track Stockage Requests.

Cette opération prend également en charge l'utilisation d'en-têtes conditionnels pour exécuter l'opération uniquement si une condition est remplie. Pour plus d’informations, consultez Spécification des en-têtes conditionnels pour les opérations du service Blob.

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

À compter de la version 2019-02-02, les en-têtes suivants peuvent être spécifiés sur la demande pour chiffrer un objet blob chiffré 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 de la page.

Exemple de demande

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:   
x-ms-date: Fri, 16 Sep 2011 22:15:50 GMT  
x-ms-version: 2018-11-09  
x-ms-range: bytes=0-65535  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0  
  

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 d’état, consultez Les 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.

Syntaxe Description
ETag ETag pour l'objet blob. Si la version de la demande est 18/08/2011 ou plus récente, la valeur de l'ETag sera entre guillemets. L'ETag peut être utilisé pour effectuer une opération conditionnelle Put Page From URL en spécifiant sa valeur pour l'en-tête de demande If-Match ou If-None-Match.
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-Time dans les en-têtes.

Toute opération d'écriture dans l'objet blob (notamment les mises à jour des métadonnées ou des 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. 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 x-ms-source-content-md5 l’en-tête n’est pas présent dans la requête.
x-ms-blob-sequence-number Le numéro de séquence actuel pour l'objet blob de pages.
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 Résolution des problèmes liés aux opérations d’API.
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 true si le contenu de la requête est correctement chiffré à l’aide de l’algorithme spécifié, et false sinon.
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, 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 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 si elle est présente dans la requête et que la valeur est au maximum 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, cet en-tête ne sera pas présent dans la réponse.

Corps de la réponse

Aucun.

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 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Sun, 25 Sep 2011 12:13:31 GMT  
x-ms-version: 2011-08-18  
x-ms-blob-sequence-number: 0  
Content-Length: 0  
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

L'opération Put Page From URL écrit une plage de pages dans un objet blob de pages. Cette opération peut être appelée uniquement sur un objet blob de pages existant. Elle ne peut pas être appelée pour créer un nouvel objet blob de pages ou sur un objet blob de blocs. L'appel à Put Page From URL avec un nom d'objet blob qui n'existe pas actuellement retourne une erreur BlobNotFound (code d'état HTTP 404 – Introuvable).

Dans la version 2020-10-02 et les versions ultérieures, Azure Active Directory autorisation est prise en charge pour la source de l’opération de copie.

Pour créer un objet blob de pages, appelez Put Blob et spécifiez le type d’objet blob à créer en tant qu’objet blob de pages. Un objet blob de pages peut avoir une taille maximale de 8 Tio.

Si l'objet blob a un bail actif, le client doit spécifier un ID de bail valide dans la demande afin d'écrire une page.

Opérations de mise à jour de page

L’appel Put Page From URL effectue une écriture sur place sur l’objet blob de pages spécifié. Tout contenu dans la page spécifiée est remplacé par la mise à jour.

Important

Si le serveur dépasse le délai d'expiration ou que votre connexion est fermée pendant Put Page From URL, la page peut ne pas avoir été mise à jour. Par conséquent, réessayez la mise à jour jusqu'à ce que vous receviez une réponse indiquant la réussite.

Chaque plage de pages envoyées Put Page From URL pour une opération de mise à jour peut avoir une taille maximale de 4 Mio. La plage de début et de fin de la page doivent être alignées avec les limites de 512 octets. Si vous essayez de télécharger une plage des pages plus volumineuse que 4 Mo, le service retourne le code d'état 413 (Entité de demande trop grande).

Gestion des problèmes d'accès concurrentiel

Le service BLOB gère les écritures simultanées dans des pages qui se chevauchent de façon séquentielle ; la dernière page traitée par le service détermine le contenu de l'objet blob. Par conséquent, pour garantir l'intégrité du contenu de l'objet blob, le client doit gérer les écritures dans les pages qui se chevauchent en utilisant l'une des approches suivantes :

  • Vous pouvez vérifier la valeur de l'en-tête de réponse Last-Modified pour chaque appel réussi à Put Page From URL. L'ordre des réponses retournées du service BLOB ne correspond pas nécessairement à l'ordre dans lequel elles ont été exécutées par le service. Mais la valeur de Last-Modified indique toujours l'ordre dans lequel le service a traité les demandes.

  • Vous pouvez effectuer des mises à jour conditionnellement en fonction de l'ETag de l'objet blob ou de l'heure de la dernière modification en utilisant l'accès concurrentiel optimiste. Cette approche fonctionne correctement si le nombre d'écritures simultanées est relativement faible. Utilisez les en-têtes de demande conditionnels If-Match, If-None-Match, If-Modified-Since et If-Unmodified-Since dans ce cas.

  • Vous pouvez appeler l’objet blob de bail pour verrouiller l’objet blob sur d’autres écritures pendant une période d’une minute ou plus si le bail est renouvelé.

  • Vous pouvez utiliser le numéro de séquence de l'objet blob pour vous assurer qu'une nouvelle tentative de la demande qui n'avait pas reçu de réponse ne produit pas des mises à jour simultanées. Cette approche est préférable pour les clients qui requièrent des débits élevés pour les écritures de page. Elle est décrite en détail dans les sections suivantes.

Utilisation du numéro de séquence d'objet blob de pages pour les demandes de nouvelle tentative

Lorsqu'un appel à Put Page From URL dépasse le délai ou ne retourne pas de réponse, il n'est pas possible de savoir si la demande a réussi. Vous devez donc effectuer une nouvelle tentative de la demande, mais en raison de la nature distribuée des services de stockage Azure, il est possible que la demande d'origine puisse être traitée après le succès de la nouvelle tentative. La demande d'origine retardée peut remplacer d'autres mises à jour et produire des résultats inattendus. La séquence suivante illustre cela :

  1. Une demande Put Page From URL d'écriture de la valeur « X » dans la page 0 dépasse le délai et ne retourne pas de réponse.

  2. Une demande de nouvelle tentative d'écriture de la valeur « X » dans la page 0 réussit.

  3. Une demande d'écriture de la valeur « Y » dans la page 0 réussit.

  4. La demande d'origine réussit, et écrit la valeur « X » dans la page 0.

  5. La lecture de la page 0 retourne la valeur « X », alors que le client s'attendait à la valeur « Y ».

Ce type de conflit peut se produire lorsque la demande d'origine ne retourne pas de code d'état entre 100-499, ou 503 (Serveur occupé). Si l'un de ces codes d'état est retourné, vous pouvez savoir si la demande a réussi ou a échoué. Mais si le service retourne un code d'état en dehors de cette plage, il n'existe aucun moyen de savoir l'état de la demande d'origine.

Pour éviter ce type de conflit, vous pouvez utiliser le numéro de séquence de l'objet blob de pages pour garantir que lorsque vous réessayez une demande, la demande d'origine ne réussira pas ultérieurement. Pour cela, vous devez incrémenter le numéro de séquence avant de retenter la demande d'origine. Vous pouvez ensuite utiliser des en-têtes de numéro de séquence conditionnels pour garantir que la demande échoue si son numéro de séquence ne correspond pas au numéro de séquence attendu. La séquence suivante illustre cette approche :

  1. Le client crée un objet blob de pages avec Put Blob et définit son numéro de séquence sur 0.

  2. Demande Put Page From URL d’écriture de la valeur « X » à la page 0 avec l’en-tête if-sequence-number-lt défini pour 1 expirer ou ne retourne pas de réponse.

  3. Le client appelle Set Blob Properties pour mettre à jour le numéro de séquence à 1.

  4. Une demande retentée pour écrire la valeur « X » à la page 0 avec if-sequence-number-lt la valeur définie pour 2 réussir.

  5. Demande d’écriture de la valeur « Y » à la page 0 avec if-sequence-number-lt la valeur définie pour 2 réussir.

  6. La requête d’origine est finalement traitée, mais elle échoue, car elle spécifie la condition selon laquelle le numéro de séquence doit être inférieur à 1 (autrement dit, l’en-tête if-sequence-num-lt est défini 1sur ). L'erreur est SequenceNumberConditionNotMet (code d'état HTTP 412 – Échec de la précondition).

  7. La lecture de la page 0 retourne la valeur attendue « Y ».

Voir aussi

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