Partage de bail

L’opération Lease Share établit et gère un verrou sur un partage de fichiers Azure ou un partage instantané. Cette API est entièrement prise en charge, mais il s’agit d’une API de gestion héritée. Utilisez plutôt Partages de fichiers - Bail, fourni par le fournisseur de ressources de stockage (Microsoft.Storage). Pour en savoir plus sur l’interaction programmatique avec FileShare les ressources à l’aide du fournisseur de ressources de stockage, consultez Operations on FileShares.

La durée du verrou peut être de 15 à 60 secondes, ou peut être infinie. Vous pouvez appeler l’opération Lease Share dans l’un des modes suivants :

• Acquire: Pour demander un nouveau bail.
• Renew: Pour renouveler un bail existant.
• Change: pour modifier l’ID d’un bail existant.
• Release: Libérer le bail s’il n’est plus nécessaire, afin qu’un autre client puisse immédiatement acquérir un bail sur le partage de fichiers.
• Break: Mettre fin au bail, mais s’assurer qu’un autre client ne peut pas acquérir un nouveau bail tant que la période de bail actuelle n’a pas expiré.

Notes

L’opération Lease Share est disponible dans les versions 2020-02-10 et ultérieures.

Disponibilité du protocole

Protocole de partage de fichiers activé	Disponible
SMB
NFS

Requête

Vous pouvez construire la Lease Share requête comme suit. HTTPS est recommandé. Remplacez myaccount par le nom de votre compte de stockage.

Méthode	URI de demande	Version HTTP
PUT	https://myaccount.file.core.windows.net/myshare?comp=lease&restype=share	HTTP/1.1
PUT	https://myaccount.file.core.windows.net/myshare?comp=lease&sharesnapshot=<DateTime>&restype=share	HTTP/1.1

Paramètres URI

Vous pouvez spécifier le paramètre supplémentaire suivant sur l’URI de demande.

Paramètre	Description
timeout	facultatif. Le paramètre timeout est exprimé en secondes. Pour plus d’informations, consultez Définition de délais d’expiration pour les opérations Azure Files.

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 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	Optionnel. 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.
x-ms-lease-id: <ID>	Obligatoire pour renouveler, modifier ou libérer le bail. Vous pouvez spécifier la valeur de dans n’importe quel format de x-ms-lease-id chaîne GUID valide. Pour obtenir la liste des formats valides , consultez Constructeur guid (String ).
x-ms-lease-action: <action>	acquire : demande un nouveau bail. Si le partage de fichiers n’a pas de bail actif, Azure Files crée un bail sur le partage de fichiers et retourne un nouvel ID de bail. Si le partage de fichiers a un bail actif, vous pouvez uniquement demander un nouveau bail à l’aide de l’ID de bail actif. Vous pouvez toutefois spécifier un nouveau x-ms-lease duration, y compris négatif (-1) pour un bail qui n’expire jamais. renew : renouvelle le bail. Vous pouvez renouveler le bail si l’ID de bail spécifié dans la demande correspond à celui associé au partage de fichiers. Notez que vous pouvez renouveler le bail même s’il a expiré, tant que le partage de fichiers n’a pas été à nouveau loué depuis l’expiration de ce bail. Lorsque vous renouvelez un bail, la durée de bail est réinitialisée. change : modifie l'ID du bail d'un bail actif. Un change doit inclure l’ID de bail actuel dans x-ms-lease-id, et un nouvel ID de bail dans x-ms-proposed-lease-id. release : libère le bail. Vous pouvez libérer le bail si l’ID de bail spécifié sur la demande correspond à celui associé au partage de fichiers. La libération du bail permet à un autre client d’acquérir immédiatement le bail pour le partage de fichiers, dès que la mise en production est terminée. break: Interrompez le bail, si le partage de fichiers a un bail actif. Une fois qu’un bail est rompu, il ne peut pas être renouvelé. Toute demande autorisée peut rompre le bail. La demande n’est pas nécessaire pour spécifier un ID de bail correspondant. Lorsqu’un bail est rompu, la période d’interruption de bail est autorisée à s’écouler et breakrelease sont les seules opérations que vous pouvez effectuer sur le partage de fichiers pendant cette période. Lorsqu'un bail est correctement résilié, la réponse indique l'intervalle en secondes avant qu'un nouveau bail puisse être acquis. Un bail qui a été résilié peut également être libéré. Un client peut immédiatement acquérir un bail de partage de fichiers qui a été libéré.
x-ms-lease-break-period: N	Optionnel. Pour une break opération, il s’agit de la durée proposée que le bail doit continuer avant d’être rompu, en secondes, entre 0 et 60. Cette période d’arrêt n’est utilisée que si elle est plus courte que le temps restant sur le bail. Si elle est plus longue, la durée restante du bail est utilisée. Un nouveau bail n’est pas disponible avant l’expiration de la période de pause, mais le bail peut être conservé plus longtemps que la période d’interruption. Si cet en-tête n’apparaît pas avec une break opération, un bail à durée fixe s’interrompt une fois la période de bail restante écoulée et un bail infini s’interrompt immédiatement.
x-ms-lease-duration: -1	Requis pour acquire. Spécifie la durée de bail, en secondes, ou moins un (- 1) pour un bail qui n'expire jamais. Un bail qui n'est pas infini peut durer entre 15 et 60 secondes. La durée d’un bail ne peut pas être modifiée à l’aide de renew ou change.
x-ms-proposed-lease-id: <ID>	Facultatif pour acquireet obligatoire pour change. ID de bail proposé, dans un format de chaîne GUID. Stockage Blob Azure retourne 400 (Invalid request) si l’ID de bail proposé n’est pas au format correct. Pour obtenir la liste des formats valides , consultez Constructeur guid (String ).
Origin	Optionnel. Spécifie l'origine à partir de laquelle la demande est émise. La présence de cet en-tête entraîne des en-têtes de partage de ressources cross-origine (CORS) dans la réponse. Pour plus d’informations, consultez Prise en charge CORS pour les services de stockage .
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 (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.

Corps de la demande

Aucun.

Exemple de requête

L'exemple de demande suivant montre comment acquérir un bail :

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare?restype=share&comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2020-02-10  
x-ms-lease-action: acquire  
x-ms-lease-duration: -1  
x-ms-proposed-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-date: Thu, 26 Jan 2012 23:30:18 GMT  
Authorization: SharedKey testaccount1:esSKMOYdK4o+nGTuTyeOLBI+xqnqi6aBmiW4XI699+o=  

response

La réponse inclut un code d'état HTTP et un ensemble d'en-têtes de réponse.

Code d’état

Les codes d'état de réussite retournés pour les opérations de bail sont les suivants :

• Acquire : une opération ayant réussi retourne le code d'état 201 (Créée).
• Renew : une opération ayant réussi retourne le code d'état 200 (OK).
• Change : une opération ayant réussi retourne le code d'état 200 (OK).
• Release : une opération ayant réussi retourne le code d'état 200 (OK).
• Break : une opération ayant réussi retourne le code d'état 202 (Acceptée).

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 également 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 le partage de fichiers.
Last-Modified	Retourne la date et l’heure de la dernière modification du partage de fichiers. Pour plus d’informations, consultez Représentation des valeurs date-heure dans les en-têtes. Toute opération qui modifie le partage de fichiers, ses propriétés ou métadonnées, met à jour l’heure de la dernière modification. Cela inclut la définition des autorisations du partage de fichiers. Les opérations sur les objets blob n’affectent pas l’heure de dernière modification du partage de fichiers.
x-ms-lease-id: <id>	Lorsque vous demandez un bail, Azure Files retourne un ID de bail unique. Pendant que le bail est actif, vous devez inclure l’ID de bail avec toute demande de suppression du partage de fichiers, ou de renouvellement, de modification ou de libération du bail. Une opération de renouvellement réussie retourne également l'ID du bail pour le bail actif.
x-ms-lease-time: seconds	Durée approximative restante de la période du bail, en secondes. Cet en-tête est retourné uniquement pour une demande réussie de résiliation du bail. Si l’arrêt est immédiat, 0 est retourné.
x-ms-request-id	Identifie de manière unique la requête qui a été effectuée et peut être utilisée pour la résolution des 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 de l’API FileREST utilisée pour exécuter la requête.
Date	Valeur de date/heure UTC qui indique l’heure à laquelle la réponse a été lancée. Le service génère cette valeur.
Access-Control-Allow-Origin	Retourné si la requête inclut un Origin en-tête et que CORS est activé avec une règle de correspondance. Cet en-tête retourne la valeur de l'en-tête de demande d'origine en cas de correspondance.
Access-Control-Expose-Headers	Retourné si la requête inclut un Origin en-tête et que CORS est activé avec une règle de correspondance. Retourne la liste des en-têtes de réponse qui doivent être exposés au client ou à l'émetteur de la demande.
Access-Control-Allow-Credentials	Retourné si la requête inclut un Origin en-tête et que CORS est activé avec une règle de correspondance qui n’autorise pas toutes les origines. Cet en-tête est défini sur true.
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. 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 demande, il ne sera pas présent dans la réponse.

Response body

Aucun.

Exemple de réponse

Voici un exemple de réponse pour une demande d'acquisition de bail :

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2020-02-10  
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: Thu, 26 Jan 2012 23:30:18 GMT  

Autorisation

Seul le propriétaire du compte peut appeler cette opération.

Notes

Un bail sur un partage de fichiers fournit un accès de suppression exclusif au partage de fichiers. Les opérations d’obtention du partage de fichiers réussissent sur un partage de fichiers loué, sans inclure l’ID de bail. Les opérations de définition du partage de fichiers nécessitent l’ID de bail du partage de fichiers. Si l’ID de bail n’est pas inclus dans les opérations de partage de fichiers définies, l’opération échoue avec 412 (échec de la condition préalable). Le bail est accordé pour la durée spécifiée lors de l’acquisition du bail, qui peut être comprise entre 15 et 60 secondes, ou une durée infinie.

Lorsqu'un client acquiert un bail, un ID de bail est retourné. Azure Files génère un ID de bail s’il n’en est pas spécifié dans la demande d’acquisition. Le client peut utiliser cet ID de bail pour renouveler le bail, modifier son ID de bail ou libérer le bail. Le diagramme suivant montre les cinq états d'un bail, et les commandes ou les événements qui peuvent entraîner des modifications d'état du bail.

Un bail peut être dans l’un de ces états, selon qu’il est verrouillé ou déverrouillé, et si le bail est renouvelable dans cet état. Les actions de bail présentées dans le diagramme précédent entraînent des transitions d’état.

Renouvellement status	Bail verrouillé	Bail déverrouillé
Bail renouvelable	Loué	Expiré
Bail non renouvelable	Rupture	Résilié, disponible

• Available, le bail est déverrouillé et peut être acquis. Action autorisée : acquire.
• Leased, le bail est verrouillé. Actions autorisées : acquire (ID de bail identique uniquement), renew, change, release, et break.
• Expired, la durée du bail a expiré. Actions autorisées : acquire, renew, release, et break.
• Breaking, le bail a été rompu, mais le bail continuera d’être verrouillé jusqu’à l’expiration de la période d’arrêt. Actions autorisées : release et break.
• Broken, le bail a été rompu et la période d’arrêt a expiré. Actions autorisées : acquire, release et break.

Azure Files conserve l’ID de bail après l’expiration d’un bail de partage de fichiers. Un client peut renouveler ou libérer le bail à l’aide de son ID de bail expiré. Si le client tente de renouveler ou de libérer un bail expiré avec son ID de bail précédent et que la demande échoue, cela signifie que le partage de fichiers a été à nouveau loué ou supprimé depuis la dernière fois que son bail a été actif. Si un bail expire au lieu d’être explicitement libéré, un client peut avoir besoin d’attendre jusqu’à une minute avant qu’un nouveau bail puisse être acquis pour le partage de fichiers. Toutefois, le client peut renouveler le bail avec l'ID de bail expiré immédiatement.

La propriété du partage de Last-Modified-Time fichiers n’est pas mise à jour par les appels à Lease Share.

Les tableaux ci-dessous montrent les résultats des actions sur les conteneurs avec des baux dans différents états. Les lettres (A), (B) et (C) représentent les ID de bail, et (X) représentent un ID de bail généré par Azure Files.

Résultats des tentatives d’utilisation sur les partages par état de bail

Action	Disponible	Loué (A)	En cours de résiliation (A)	Résilié (A)	Expiré (A)
Supprimer avec (A)	Échecs (412)	Loué (A), la suppression a réussi	En cours de résiliation (A), la suppression a réussi	Échecs (412)	Échecs (412)
Supprimer avec (B)	Échecs (412)	Échec (409)	Échecs (412)	Échecs (412)	Échecs (412)
Supprimer, aucun bail spécifié	Disponible, la suppression a réussi	Échecs (412)	Échecs (412)	Disponible, la suppression a réussi	Disponible, la suppression a réussi
Autres opérations avec (A)	Échecs (412)	Loué (A), l'opération a réussi	En cours de résiliation (A), l'opération a réussi	Échecs (412)	Échecs (412)
Autres opérations avec (B)	Échecs (412)	Échec (409)	Échec (409)	Échecs (412)	Échecs (412)
Opérations, aucun bail spécifié	Non disponible, l'opération a réussi	Loué (A), l'opération a réussi	En cours de résiliation (A), l'opération a réussi	Résilié (A), l'opération a réussi	Expiré (A), l'opération a réussi

Résultats des opérations de bail sur les partages par état de bail

Action	Disponible	Loué (A)	En cours de résiliation (A)	Résilié (A)	Expiré (A)
Acquire, aucun ID de bail proposé	Loué (X)	Échec (409)	Échec (409)	Loué (X)	Loué (X)
Acquire (A)	Loué (A)	Loué (A), nouvelle durée	Échec (409)	Loué (A)	Loué (A)
Acquire (B)	Loué (B)	Échec (409)	Échec (409)	Loué (B)	Loué (B)
Break, période=0	Échec (409)	Résilié (A)	Résilié (A)	Résilié (A)	Résilié (A)
Break, période>0	Échec (409)	En cours de résiliation (A)	En cours de résiliation (A)	Résilié (A)	Résilié (A)
Change, (A) à (B)	Échec (409)	Loué (B)	Échec (409)	Échec (409)	Échec (409)
Change, (B) à (A)	Échec (409)	Loué (A)	Échec (409)	Échec (409)	Échec (409)
Change, (B) à (C)	Échec (409)	Échec (409)	Échec (409)	Échec (409)	Échec (409)
Renew (A)	Échec (409)	Loué (A), réinitialisation de l'horloge d'expiration	Échec (409)	Échec (409)	Loué (A)
Renew (B)	Échec (409)	Échec (409)	Échec (409)	Échec (409)	Échec (409)
Release (A)	Échec (409)	Disponible	Disponible	Disponible	Disponible
Release (B)	Échec (409)	Échec (409)	Échec (409)	Échec (409)	Échec (409)
Durée expire	Disponible	Expiré (A)	Résilié (A)	Résilié (A)	Expiré (A)