Plage de put from URL

Article
03/29/2023

L’opération Put Range From URL crée une plage à commiter dans le cadre d’un fichier où le contenu est lu à partir d’une URL. Cette API est disponible à partir de la version 2019-02-02.

Disponibilité du protocole

Protocole de partage de fichiers activé	Disponible
SMB
NFS

Requête

La demande Put Range From URL peut être construite comme indiqué ci-dessous. Nous vous recommandons d’utiliser HTTPS. Remplacez moncompte par le nom de votre compte de stockage :

Méthode	URI de demande	Version HTTP
`PUT`	`https://myaccount.file.core.windows.net/myshare/myfile?comp=range`	HTTP/1.1

Paramètres URI

Paramètre	Description
`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 Azure Files.

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 la page Contrôle de version pour les services de Stockage Microsoft Azure. Pour `Put Range From URL`, la version doit être 2019-02-02 ou ultérieure.
`x-ms-copy-source:name`	Obligatoire. Spécifie l’URL du fichier source. La valeur peut être une URL d’une longueur maximale de 2 Kio qui spécifie un fichier. La valeur doit être encodée sous forme d'URL, comme dans une URI de demande. Le fichier source doit être public ou doit être autorisé via une signature d’accès partagé. Si le fichier source est public, aucune autorisation n’est requise pour effectuer l’opération. Voici quelques exemples d’URL d’objet source : `https://myaccount.file.core.windows.net/myshare/mydir/myfile` `https://myaccount.file.core.windows.net/myshare/mydir/myfile?<sastoken>`
`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 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-write: { update }`	Obligatoire. Vous devez spécifier uniquement `update`. La demande échoue si elle est appelée avec `clear`. La `update` valeur écrit les octets spécifiés par le corps de la requête dans les plages spécifiées.
`Range` ou `x-ms-range`	Obligatoire. `Range` ou `x-ms-range` est requis. Spécifie la plage d'octets à écrire. 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, la plage peut atteindre 4 Mio. Azure Files n’accepte qu’une seule plage d’octets pour les `Range` en-têtes et `x-ms-range` , et la plage d’octets doit être spécifiée au 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écifier l’en-tête de plage pour les opérations Azure Files.
`x-ms-source-range`	Obligatoire. Spécifie la plage d’octets à lire à partir de la source. Le début et la fin de la plage doivent être spécifiés. Azure Files n’accepte qu’une seule plage d’octets pour les `Range` en-têtes et `x-ms-range` , et la plage d’octets doit être spécifiée au format suivant : `bytes=startByte-endByte`. La plage source peut atteindre 4 Mio. Si la taille de la plage source dépasse 4 Mio, Azure Files retourne status code 413 (Entité de requête trop grande). Si la taille de la plage source ne correspond pas à la taille de la plage (plage cible), le service retourne status code 400 (requête incorrecte).
`Content-Length`	Obligatoire. Indique le nombre d'octets transmis dans le corps de demande. La valeur de cet en-tête doit être `0`. Lorsque la longueur n’est pas `0`, l’opération échoue avec le code status 400 (requête incorrecte).
`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 Azure Files.
`x-ms-source-content-crc64`	facultatif. Hachage CRC64 de la plage spécifiée à partir de l’URI. Ce hachage est utilisé pour vérifier l’intégrité de la plage pendant le transport des données à partir de l’URI. Lorsque cet en-tête est spécifié, Azure Files 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 le fichier. Si les deux hachages ne correspondent pas, l’opération échoue avec le code d’erreur 400 (requête incorrecte).
`x-ms-source-if-match-crc64`	facultatif. Valeur de somme de contrôle CRC64. Spécifiez cet en-tête pour effectuer l’opération uniquement si la somme de contrôle de la plage donnée lue à partir de la source correspond à la somme de contrôle fournie. Si la condition spécifiée n’est pas remplie, Azure Files retourne status code 412 (Échec de la condition préalable).
`x-ms-source-if-none-match-crc64`	facultatif. Valeur de somme de contrôle CRC64. Spécifiez cet en-tête pour effectuer l’opération uniquement si la somme de contrôle de la plage donnée lue à partir de la source est différente de la somme de contrôle fournie. Si la condition spécifiée n’est pas remplie, Azure Files retourne status code 412 (Échec de la condition préalable).
`x-ms-lease-id:<ID>`	Obligatoire si le fichier a un bail actif. Pour effectuer cette opération sur un fichier 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), qui est enregistrée dans les journaux d’analyse lorsque la journalisation Azure Storage Analytics est activée. Nous vous recommandons vivement d’utiliser cet en-tête lorsque vous associez des activités côté client aux demandes reçues par le serveur. Pour plus d’informations, consultez Surveiller le stockage Blob.
`x-ms-file-last-write-time: { now ¦ preserve }`	facultatif. Version 2021-06-08 et ultérieures. Vous pouvez spécifier l'une des options suivantes : `now`: valeur par défaut. Mises à jour l’horodatage de la dernière heure d’écriture à l’heure de la demande. `preserve`: conserve le dernier horodatage de la dernière écriture existant inchangé.
`x-ms-file-request-intent`	Obligatoire si `Authorization` l’en-tête spécifie un jeton OAuth. La valeur acceptable est `backup`. Cet en-tête spécifie que le `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` ou `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` doit être accordé s’il est inclus dans la stratégie RBAC affectée à l’identité autorisée à l’aide de l’en-tête `Authorization` . Disponible pour les versions 2022-11-02 et ultérieures.
`x-ms-allow-trailing-dot: { <Boolean> }`	facultatif. Version 2022-11-02 et ultérieures. La valeur booléenne spécifie si un point de fin présent dans l’URL de la demande doit être rogné ou non. Pour plus d’informations, consultez Nommer et référencer des partages, des répertoires, des fichiers et des métadonnées.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	facultatif. Version 2022-11-02 et ultérieures. La valeur booléenne spécifie si un point de fin présent dans l’URL source doit être rogné ou non. Cet en-tête doit être spécifié uniquement si la source de copie est un fichier Azure. Cet en-tête n’est pas pris en charge pour tout autre type de source de copie. Pour plus d’informations, consultez Nommer et référencer des partages, des répertoires, des fichiers et des métadonnées.

Corps de la demande

Aucun corps de requête.

Exemple de requête

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/mydir/myfile?comp=range HTTP/1.1  
  
Request Headers:  
x-ms-page-write: update  
x-ms-copy-source: http://myaccount2.file.core.windows.net/myshare2/mydirectory2/myfile2?sv=2018-11-09&sp=r&sr=s&se=2018-08-22T09%3A59%3A28.2185790Z&sig=Qn6QEET3Gn%2FhCEVcXuwG7ssatIYiYRM5pNIy4Q3N0cQ%3D 
x-ms-date: Fri, 22 Aug 2018 01:15:50 GMT  
x-ms-version: 2019-02-02 
x-ms-range: bytes=100-1023  
x-ms-source-range: bytes=200-1123  
x-ms-source-content-crc64: 3bedb8b3730fc205 
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 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
`ETag`	Contient une valeur que vous pouvez utiliser pour effectuer des opérations conditionnelles. La valeur est placée entre guillemets.
`Last-Modified`	Date et heure de la dernière modification du fichier. Le format de date est conforme à la RFC 1123. Pour plus d’informations, consultez Représentation des valeurs de date/heure dans les en-têtes. Toute opération d’écriture sur le fichier, y compris les mises à jour des métadonnées ou propriétés du fichier, modifie l’heure de la dernière modification du fichier.
`x-ms-request-id`	Identifie de manière unique la demande qui a été effectuée et vous pouvez l’utiliser pour résoudre les problèmes de 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 l’API FileREST 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-content-crc64`	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 Azure Files. Elle n’est pas nécessairement identique à la valeur spécifiée dans les en-têtes de requête.
`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 demande, il ne sera pas présent dans la réponse.
`x-ms-file-last-write-time`	Version 2021-06-08 et ultérieures. Heure de dernière écriture du fichier, au format ISO 8601 (par exemple, `2017-05-10T17:52:33.9551861Z`).

Exemple de réponse

Response Status:  
HTTP/1.1 201 Created  

Response Headers:
Date: Sun, 22 Aug 2020 01:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Wed, 22 Aug 2020 01:13:31 GMT  
x-ms-version: 2019-02-02
x-ms-content-crc64: 3bedb8b3730fc205 
Content-Length: 0  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

Autorisation

Cette opération peut être appelée par le propriétaire du compte et par toute personne disposant d’une signature d’accès partagé avec des autorisations d’écriture dans ce fichier ou le partage de fichiers Azure.

Remarques

L’opération Put Range From URL écrit une plage de données dans un fichier. Si l’API est appelée sur un fichier inexistant sur la cible, l’API retourne le code HTTP status 404 (introuvable).

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

Pour créer un fichier, appelez Create File.

Put Range From URL l’opération retourne success 201 (Created) uniquement si la plage spécifiée est écrite dans le fichier.

Opération de lecture de fichier
Put Range From URL utilise Get File pour lire des données et des métadonnées, des attributs et des listes de contrôle d’accès à partir de la source.

Opération de mise à jour de fichier
L’appel Put Range From URL avec l’option « update » effectue une écriture sur place sur le fichier spécifié. Tout contenu du fichier spécifié est remplacé par la mise à jour.  

La taille de la plage dans l’opération Put Range From URL pour une opération de mise à jour peut atteindre 4 Mio. Si vous tentez de charger une plage supérieure à 4 Mio, Azure Files retourne status code 413 (RequestEntityTooLarge).