Partage de baux

L' Lease Share opération établit et gère un verrou sur un partage de fichiers Azure ou un instantané de partage. Bien que cette API soit entièrement prise en charge, il s’agit d’une API de gestion héritée. nous vous recommandons d’utiliser des partages de fichiers-bail fournis par le fournisseur de ressources de stockage (Microsoft. Stockage) à la place. Pour en savoir plus sur l’interaction par programmation avec FileShare les ressources à l’aide du fournisseur de ressources de stockage, consultez opérations sur partages.

La durée du verrou peut être de 15 à 60 secondes, ou peut être infinie. L'opération Lease Share peut être appelée dans cinq modes :

  • Acquire: pour demander un nouveau bail.
  • Renew: pour renouveler un bail existant.
  • Change: pour modifier l’ID d’un bail existant.
  • Release: pour libérer le bail s’il n’est plus nécessaire, de sorte qu’un autre client puisse immédiatement acquérir un bail sur le partage de fichiers.
  • Break, pour résilier le bail mais vous assurer qu'un autre client ne peut pas acquérir un nouveau bail tant que la durée du bail n'a pas expiré.

Notes

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

Disponibilité du protocole

Protocole de partage de fichiers activé Disponible
SMB Oui
NFS Oui

Requête

La demande Lease Share peut être construite comme indiqué ci-dessous. HTTPS est recommandé. 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?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 d’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 de délais d’attente pour les opérations de service de fichiers.

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 de 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 Facultatif. Spécifie la version de l'opération à utiliser pour cette demande. pour plus d’informations, consultez contrôle de version pour les Services stockage Azure.
x-ms-lease-id: <ID> Obligatoire pour renouveler, modifier ou libérer le bail.

La valeur de x-ms-lease-id peut être spécifiée dans n'importe quel format de chaîne GUID valide. Pour obtenir la liste des formats de chaîne GUID valides , consultez constructeur de 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, mais vous pouvez spécifier un nouveau x-ms-lease duration , y compris le signe moins (-1) pour un bail qui n’expire jamais.

renew : renouvelle le bail. Le bail peut être renouvelé si l’ID de bail spécifié dans la demande correspond à celui associé au partage de fichiers. Notez que le bail peut être renouvelé même s’il a expiré tant que le partage de fichiers n’a pas été loué à nouveau 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 du bail actuel dans x-ms-lease-id et un nouvel ID de bail dans x-ms-proposed-lease-id.

release : libère le bail. Le bail peut être libéré si l’ID de bail spécifié dans 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 sortie est terminée.

break: Rompre le bail, si le partage de fichiers a un bail actif. Une fois un bail résilié, il ne peut pas être renouvelé. Toute demande autorisée peut résilier le bail ; la demande ne spécifie pas obligatoirement un ID de bail correspondant. Lorsqu’un bail est rompu, la période de résiliation du bail est autorisée à s’écouler, au cours de laquelle aucune opération de bail sauf break et release peut être effectuée sur le partage de fichiers. 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 Facultatif. Pour une opération break, il s'agit de la durée proposée en secondes pendant laquelle le bail doit continuer avant qu'il soit résilié, entre 0 et 60 secondes. Cette période de résiliation n'est utilisée que si elle est plus courte que la durée du bail restante. Si elle est plus longue, la durée restante du bail est utilisée. Un nouveau bail ne sera pas disponible avant l'expiration de la période de résiliation, mais le bail peut être conservé au-delà de cette période. Si cet en-tête n'apparaît pas avec une opération break, un bail à durée fixe est résilié après le dépassement de la période de résiliation du bail restante et un bail infini est immédiatement résilié.
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. Une durée de bail ne peut pas être modifiée en utilisant renew ou change.
x-ms-proposed-lease-id: <ID> Facultatif pour acquire, requis pour change. ID de bail proposé, dans un format de chaîne GUID. Le service BLOB retourne 400 (Invalid request) si l'ID de bail proposé n'est pas dans un format correct. Pour obtenir la liste des formats de chaîne GUID valides , consultez constructeur de GUID (String) .
Origin Facultatif. 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 dans la réponse. pour plus d’informations, consultez prise en charge de CORS pour les Services Stockage .
x-ms-client-request-id Facultatif. Fournit une valeur opaque générée par le client avec une limite de 1 Kio de caractères qui est enregistrée dans les journaux d’analyse lorsque la journalisation de l’analyse 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 à propos de la journalisation des Storage Analytics et de la journalisation Azure : utilisation des journaux pour suivre les demandes de Stockage.

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=  

Réponse

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 d’État, 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.

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. Le format de date est conforme à la RFC 1123. Pour plus d’informations, consultez représentation des valeurs de Date-Time dans les en-têtes.

Toute opération qui modifie le partage de fichiers ou ses propriétés ou métadonnées met à jour l’heure de la dernière modification, notamment la définition des autorisations du partage de fichiers. Les opérations sur les objets BLOB n’affectent pas l’heure de la 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 pour renouveler, modifier ou libérer le 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 la résiliation est immédiate, 0 est retourné.
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 Troubleshooting API Operations.
x-ms-version Indique la version de l’API du serveur de fichiers utilisée pour exécuter la requête.
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.
Access-Control-Allow-Origin Retourné si la demande inclut un en-tête Origin et le partage de ressources cross-origine (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 demande inclut un en-tête Origin et le partage de ressources cross-origine (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 demande inclut un en-tête Origin et le partage de ressources cross-origine (CORS) est activé avec une règle de correspondance qui n'autorise pas toutes les origines. Cet en-tête doit avoir la valeur True.
x-ms-client-request-id Cet en-tête peut être utilisé pour dépanner les demandes et les réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l' x-ms-client-request-id en-tête si elle est présente dans la demande et que la valeur est supérieure à 1024 caractères ASCII visibles. Si l' x-ms-client-request-id en-tête n’est pas présent dans la demande, cet en-tête 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.

Remarques

Un bail sur un partage de fichiers fournit un accès en suppression exclusive au partage de fichiers. Les opérations obtenir le partage de fichiers sont effectuées sur un partage de fichiers loué sans inclure l’ID de bail ; les opérations Set File Share requièrent l’ID de bail de 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 précondition). Le bail est autorisé pour la durée spécifiée lors de l'acquisition du bail, qui peut avoir lieu entre 15 secondes et une minute, ou pour une durée infinie.

Lorsqu'un client acquiert un bail, un ID de bail est retourné. Azure Files générera un ID de bail s’il n’est pas spécifié dans la demande d’acquisition. Le client peut utiliser cet ID de bail pour renouveler le bail, pour modifier son ID de bail ou pour 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.

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.

États de bail de partage de fichiers et déclencheurs de changement d’État

États du bail
Un bail peut avoir 5 états, selon si le bail est verrouillé ou déverrouillé, et si le bail est renouvelable dans cet état. Les actions de bail ci-dessus entraînent des transitions d'état.

État du renouvellement 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é résilié, mais le bail continue d'être verrouillé jusqu'à ce que la période de résiliation expire. Actions autorisées : release et break.
  • Broken, le bail a été résilié et la période de résiliation a expiré. Actions autorisées : acquire, release et break.

L’ID de bail est conservé par Azure Files après l’expiration du bail d’un partage de fichiers. Un client peut renouveler ou libérer le bail en utilisant l'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, le client sait alors que le partage de fichiers a été reloué ou supprimé depuis la dernière activation du bail. Si un bail expire au lieu d’être explicitement libéré, un client devra peut-être 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 fichiers Last-Modified-Time 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 des ID de bail, tandis que (X) représente un ID de bail généré par Azure Files.

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

Action Disponible Loué (A) En cours de résiliation (A) Résilié (A) Expiré (A)
Supprimer en utilisant (A) Échec (412) Loué (A), la suppression a réussi En cours de résiliation (A), la suppression a réussi Échec (412) Échec (412)
Supprimer en utilisant (B) Échec (412) Échec (409) Échec (412) Échec (412) Échec (412)
Supprimer, aucun bail spécifié Disponible, la suppression a réussi Échec (412) Échec (412) Disponible, la suppression a réussi Disponible, la suppression a réussi
Autres opérations en utilisant (A) Échec (412) Loué (A), l'opération a réussi En cours de résiliation (A), l'opération a réussi Échec (412) Échec (412)
Autres opérations en utilisant (B) Échec (412) Échec (409) Échec (409) Échec (412) Échec (412)
aucun, 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)