Plage de mise en place
L’opération Put Range écrit une plage d’octets dans un fichier. Cette opération est prise en charge dans la version 2025-05-05 et ultérieure pour les partages de fichiers avec le protocole NFS activé.
Disponibilité du protocole
| Protocole de partage de fichiers activé | Disponible |
|---|---|
| SMB |
|
| NFS |
|
Demander
La requête Put Range est construite comme suit. Nous vous recommandons d’utiliser HTTPS.
| Méthode | URI de requête | Version HTTP |
|---|---|---|
| METTRE | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
Remplacez les composants de chemin d’accès indiqués dans l’URI de requête par vos propres composants, comme suit :
| Composant Path | Description |
|---|---|
myaccount |
Nom de votre compte de stockage. |
myshare |
Nom de votre partage de fichiers. |
mydirectorypath |
Optionnel. Chemin d’accès au répertoire parent. |
myfile |
Nom du fichier. |
Pour plus d’informations sur les restrictions de nommage de chemin d’accès, consultez partages de noms et de références, répertoires, fichiers et métadonnées.
Paramètres d’URI
Les paramètres supplémentaires suivants peuvent être spécifiés sur l’URI de requête.
| Paramètre | Description |
|---|---|
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 de fichiers. |
En-têtes de requête
Les en-têtes de requête obligatoires et facultatifs sont décrits dans les tableaux suivants :
En-têtes de requête courants
| 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 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. Cette opération est prise en charge dans la version 2025-05-05 et ultérieure pour les partages de fichiers avec le protocole NFS activé. Pour plus d’informations, consultez Contrôle de version pour les services stockage Azure. |
Range ou x-ms-range |
Range ou x-ms-range est nécessaire.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 de protocole HTTP/1.1 . Pour une opération de mise à jour, la plage peut atteindre jusqu’à 4 Mio de taille. Pour une opération claire, la plage peut être jusqu’à la valeur de la taille complète du fichier. Le service De fichiers accepte uniquement une plage d’octets pour les en-têtes Range 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 de service de fichiers. |
Content-Length |
Obligatoire. Spécifie le nombre d’octets transmis dans le corps de la requête. Lorsque l’en-tête x-ms-write est défini sur clear, la valeur de cet en-tête doit être définie sur 0. |
Content-MD5 |
Optionnel. Hachage MD5 du contenu. Ce hachage est utilisé pour vérifier l’intégrité des données pendant le transport. Lorsque l’en-tête Content-MD5 est spécifié, Azure Files compare le hachage du contenu arrivé avec la valeur d’en-tête envoyée. Si les deux hachages ne correspondent pas, l’opération échoue avec le code d’erreur 400 (requête incorrecte).L’en-tête Content-MD5 n’est pas autorisé lorsque l’en-tête x-ms-write est défini sur clear. S’il est inclus dans la requête, le service Fichier retourne le code d’état 400 (requête incorrecte). |
x-ms-write: { update ¦ clear } |
Obligatoire. Vous devez spécifier l’une des options suivantes :
|
x-ms-lease-id:<ID> |
Obligatoire si le fichier a un bail actif. Disponible pour la version 2019-02-02 et ultérieure. Cet en-tête est ignoré si le fichier se trouve sur un partage de fichiers avec le protocole NFS activé, ce qui ne prend pas en charge les baux de fichiers. |
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 Azure Files. |
x-ms-file-last-write-time: { now ¦ preserve } |
Optionnel. Version 2021-06-08 et ultérieure. Vous pouvez spécifier l’une des options suivantes :
|
x-ms-file-request-intent |
Obligatoire si Authorization 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 Authorization. Disponible pour la version 2022-11-02 et ultérieure. |
x-ms-allow-trailing-dot: { <Boolean> } |
Optionnel. Version 2022-11-02 et ultérieure. La valeur booléenne spécifie si un point de fin présent dans l’URL de requête doit être supprimé ou non. Cet en-tête est ignoré si la cible se trouve sur un partage de fichiers avec le protocole NFS activé, qui prend en charge le point de fin par défaut. Pour plus d’informations, consultez nommage et référencement de partages, répertoires, fichiers et métadonnées. |
En-têtes de requête SMB uniquement
Aucun.
En-têtes de requête NFS uniquement
Aucun.
Corps de la demande
Données représentant la plage à charger.
Exemple de requête : Mettre à jour la plage d’octets
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: update
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Exemple de requête : Effacer la plage d’octets
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=1024-2048
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Réponse
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 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 dans les tableaux 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êtes de réponse courants
| En-tête de réponse | Description |
|---|---|
ETag |
L’ETag contient une valeur qui représente la version du fichier. La valeur est placée entre guillemets. |
Last-Modified |
Retourne la date et l’heure de la dernière modification du répertoire. Le format de date suit RFC 1123. Pour plus d’informations, consultez Représenter les valeurs de date/heure dans les en-têtes. Toute opération qui modifie le partage ou ses propriétés ou métadonnées met à jour l’heure de dernière modification. Les opérations sur les fichiers n’affectent pas l’heure de dernière modification du partage. |
Content-MD5 |
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 de fichiers. Il n’est pas nécessairement identique à la valeur spécifiée dans les en-têtes de requête. |
x-ms-request-id |
Identifie de manière unique la demande qui a été effectuée et peut être utilisée pour résoudre la demande. Pour plus d’informations, consultez Résoudre les problèmes d’opérations d’API. |
x-ms-version |
Indique la version du service de fichiers 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 2017-04-17 et ultérieure. La valeur de cet en-tête est définie sur true si le contenu de la requête est correctement chiffré à l’aide de l’algorithme spécifié. Sinon, la valeur est définie sur false. |
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 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 n’est pas présent dans la réponse. |
x-ms-file-last-write-time |
Version 2021-06-08 et ultérieure. Heure de la dernière écriture du fichier, au format ISO 8601. Exemple : 2017-05-10T17:52:33.9551861Z. |
En-têtes de réponse SMB uniquement
Aucun.
En-têtes de réponse NFS uniquement
Aucun.
Corps de la réponse
Aucun.
Exemple de réponse
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date:Mon, 27 Jan 2014 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT
x-ms-version: 2014-02-14
Content-Length: 0
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Autorisation
Seul le propriétaire du compte peut appeler cette opération.
Remarques
L’opération Put Range écrit une plage d’octets dans un fichier. Cette opération peut être appelée uniquement sur un fichier existant. Il ne peut pas être appelé pour créer un fichier. L’appel de Put Range avec un nom de fichier qui n’existe pas retourne actuellement le code d’état 404 (introuvable).
Pour créer un fichier, appelez Créer un fichier. Un fichier peut comporter jusqu’à 4 Tio de taille.
Une opération de Put Range est autorisée à effectuer 10 minutes par Mio. Si l’opération prend plus de 10 minutes par Mio en moyenne, elle expire.
Si le fichier possède un bail actif, le client doit spécifier un ID de bail valide sur la demande d’écriture d’une plage.
opérations de mise à jour de plage
L’appel de Put Range avec l’option Update effectue une écriture sur place sur le fichier spécifié. Tout contenu de la plage spécifiée est remplacé par la mise à jour. Chaque plage envoyée avec Put Range pour une opération de mise à jour peut atteindre 4 Mio. Si vous tentez de charger une plage supérieure à 4 Mio, le service retourne le code d’état 413 (Entité de requête trop grande).
opérations clear range
L’appel de Put Range avec l’option Clear libère l’espace dans le stockage tant que la plage spécifiée est alignée sur 512 octets. Les plages qui ont été effacées ne sont plus suivies dans le fichier et ne sont pas retournées dans la réponse plage de listes. Si la plage spécifiée n’est pas alignée sur 512 octets, l’opération écrit des zéros au début ou à la fin de la plage qui n’est pas alignée sur 512 octets et libère le reste de la plage à l’intérieur de 512 octets alignée.
Toutes les plages qui n’ont pas été effacées sont retournées dans les plages de listes réponse. Pour obtenir un exemple, consultez la section « Exemple de plage claire non alignée » qui suit.
de bail de fichier
Vous pouvez appeler fichier de bail pour obtenir un verrou d’écriture exclusif dans le fichier sur d’autres écritures pendant une durée infinie.
verrous de plage d’octets du client SMB
Le protocole SMB permet aux verrous de plage d’octets de gérer l’accès en lecture et en écriture aux régions d’un fichier. Cela signifie que Put Range sur un fichier situé sur un partage de fichiers avec le protocole SMB activé échoue si un client SMB a un verrou qui chevauche la plage spécifiée par l’opération de Put Range à l’aide de x-ms-range. Pour plus d’informations, consultez Gérer les verrous de fichier.
verrous de plage d’octets du client NFS
Les verrous de plage d’octets POSIX du protocole NFS sont par nature consultatifs. Par conséquent, les Put Range sur un fichier situé sur un partage de fichiers avec le protocole NFS activé ne échouent pas même s’il existe un verrou de plage d’octets en conflit détenu par un client NFS.
notifications de modification du répertoire client SMB
Le protocole SMB prend en charge la fonction API FindFirstChangeNotification qui permet aux applications de détecter quand des modifications se produisent dans le système de fichiers. Il peut détecter quand un fichier ou un répertoire est ajouté, modifié ou supprimé, et quand la taille, les attributs ou les descripteurs de sécurité d’un fichier changent. Les clients SMB qui utilisent cette API ne recevront pas de notifications lorsqu’une modification de fichier ou de répertoire se produit via l’API REST Azure Files. Toutefois, les modifications provoquées par d’autres clients SMB propagent des notifications.
Exemple de plage claire non alignée
Supposons qu’un fichier soit créé avec Créer un fichier et qu’une plage unique est écrite avec Put Range, comme suit :
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: updte
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65536
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
L’exécution d’une opération Plages de listes sur le fichier retourne le corps de la réponse suivant :
<?xml version="1.0" ecoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>65536</End>
</Range>
</Ranges>
Supposons maintenant qu’une opération de plage d’octets de plage d’octets non alignée soit effectuée :
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=768-2304
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Une opération de de plages de listes ultérieures sur le fichier retourne le corps de réponse suivant :
<?xml version="1.0" encoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>1024</End>
</Range>
<Range>
<Start>2048</Start>
<End>65535</End>
</Range>
</Ranges>
Notez que les zéros ont été écrits dans l’espace non aligné de 768-1024 et 2048-2304.
Put Range n’est pas pris en charge sur un instantané de partage, qui est une copie en lecture seule d’un partage. Une tentative d’exécution de cette opération sur un instantané de partage échoue avec 400 (InvalidQueryParameterValue).
Voir aussi
opérations sur les fichiers