Placer une plage à partir d’une URL
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 :
|
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 Microsoft Entra. 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 (Demande 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 mettez en corrélation des activités côté client avec des demandes reçues par le serveur. Pour plus d’informations, consultez Surveiller le stockage d’objets 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 :
|
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 la version 2022-11-02 et ultérieure. |
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 supprimé ou non. Pour plus d’informations, consultez Affectation de noms et référencement de partages, de répertoires, de fichiers et de 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 supprimé 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 Affectation de noms et référencement de partages, de répertoires, de fichiers et de 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 de manière conditionnelle. 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 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 qui a été 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 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. |
x-ms-file-last-write-time |
Version 2021-06-08 et ultérieures. Heure de la 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é disposant des autorisations nécessaires pour écrire 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 http status code 404 (introuvable).
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.
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).