Lease Container

  • Article

L'opération Lease Container établit et gère un verrou sur un conteneur pour les opérations de suppression. La durée du verrou peut être de 15 à 60 secondes, ou peut être infinie.

Vous pouvez appeler l’opération Lease Container 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, pour libérer le bail s’il n’est plus nécessaire, afin qu’un autre client puisse immédiatement acquérir un bail contre le conteneur.

  • Break, pour 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 Container est disponible dans la version du 12/02/2012 et les versions ultérieures.

Requête

Vous pouvez construire la Lease Container 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.blob.core.windows.net/mycontainer?comp=lease&restype=container HTTP/1.1

Pour spécifier le conteneur racine, entrez $root comme nom de conteneur.

URI de service de stockage émulé

Lorsque vous effectuez une demande auprès du service de stockage émulé, spécifiez le nom d’hôte de l’émulateur et Stockage Blob Azure port comme 127.0.0.1:10000, suivi du nom du compte de stockage émulé.

Méthode URI de demande Version HTTP
PUT http://127.0.0.1:10000/mycontainer?comp=lease&restype=container HTTP/1.0

HTTP/1.1

Pour plus d’informations, consultez Utiliser l’émulateur Azurite pour le développement local de Stockage Azure.

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 de stockage Blob.

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 facultatif. 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: <acquire ¦ renew ¦ change ¦ release ¦ break> acquire : demande un nouveau bail. Si le conteneur n’a pas de bail actif, Stockage Blob crée un bail sur le conteneur et retourne un nouvel ID de bail. Si le conteneur 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 conteneur. Notez que le bail peut être renouvelé même s’il a expiré, tant que le conteneur 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 conteneur. La libération du bail permet à un autre client d’acquérir immédiatement le bail du conteneur, dès que la mise en production est terminée.

break : résilie le bail, si le conteneur 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. Vous pouvez uniquement effectuer et release louer des break opérations sur le conteneur 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 conteneur qui a été libéré.
x-ms-lease-break-period: N facultatif. Pour une break opération, cet en-tête est la durée proposée pendant laquelle le bail doit continuer avant d’être rompu, entre 0 et 60 secondes. 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 ne sera 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 ¦ n seconds 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 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 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 (CORS) dans la réponse. Pour plus d’informations, consultez Prise en charge CORS pour les services de stockage .
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 Stockage Blob Azure.

Cette opération prend également en charge l’utilisation d’en-têtes conditionnels pour exécuter l’opération uniquement si une condition spécifiée est remplie. Pour plus d’informations, consultez Spécification d’en-têtes conditionnels pour les opérations de stockage Blob.

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.blob.core.windows.net/mycontainer?restype=container&comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2012-02-12  
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 conteneur. Cet en-tête est retourné pour les demandes effectuées sur la version 2013-08-15 et ultérieure, et la ETag valeur est entre guillemets. Lease Container les opérations effectuées sur la version 2013-08-15 et ultérieures ne modifient pas cette propriété, mais les versions antérieures le font.
Last-Modified Retourné pour les demandes effectuées sur la version 2013-08-15 et ultérieures. Renvoie la date et l'heure de la dernière modification du conteneur. Pour plus d’informations, consultez Représentation des valeurs date-heure dans les en-têtes.

Toute opération qui modifie le conteneur, 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 conteneur. Les opérations sur les objets blob n’affectent pas l’heure de dernière modification du conteneur. Lease Container les opérations effectuées sur la version 2013-08-15 et ultérieures ne modifient pas cette propriété, mais les versions antérieures le font.
x-ms-lease-id: <id> Lorsque vous demandez un bail, Stockage Blob retourne un ID de bail unique. Pendant que le bail est actif, vous devez inclure l'ID de bail avec les demandes de suppression du conteneur, 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 la résiliation est immédiate, 0 est retourné.
x-ms-request-id Cet en-tête identifie de manière unique la requête qui a été effectuée et peut être utilisé 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 Stockage Blob utilisée pour exécuter la requête. Cet en-tête est renvoyé pour les demandes effectuées avec la version 2009-09-19 ou une version ultérieure.
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 Vous pouvez utiliser cet en-tête 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-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2012-02-12  
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: Thu, 26 Jan 2012 23:30:18 GMT

Autorisation

Une autorisation est requise lorsque vous appelez une opération d’accès aux données dans stockage Azure. Vous pouvez autoriser l’opération Lease Container comme décrit dans les sections suivantes.

Le Stockage Azure prend en charge l’utilisation de Microsoft Entra ID pour autoriser les demandes de données blob. Avec Microsoft Entra ID, vous pouvez utiliser le contrôle d’accès en fonction du rôle Azure (Azure RBAC) pour accorder des autorisations à un principal de sécurité. Le principal de sécurité peut être un utilisateur, un groupe, un principal de service d’application ou une identité managée Azure. Le principal de sécurité est authentifié par Microsoft Entra ID pour retourner un jeton OAuth 2.0. Le jeton peut ensuite être utilisé pour autoriser une demande sur le Stockage Blob.

Pour en savoir plus sur l’autorisation à l’aide de Microsoft Entra ID, consultez Autoriser l’accès aux objets blob à l’aide de Microsoft Entra ID.

Autorisations

Les actions RBAC suivantes sont nécessaires pour qu’un utilisateur, un groupe ou un principal de service Microsoft Entra appelle l’opérationLease Container, ainsi que le rôle Azure RBAC intégré le moins privilégié qui inclut cette action :

Pour en savoir plus sur l’attribution de rôles à l’aide d’Azure RBAC, consultez Attribuer un rôle Azure pour accéder aux données blob.

Remarques

Un bail sur un conteneur fournit un accès exclusif en suppression au conteneur. Un bail de conteneur contrôle uniquement la possibilité de supprimer le conteneur à l’aide de l’opération Supprimer le conteneur . Pour supprimer un conteneur avec un bail actif, le client doit inclure l'identificateur du bail actif dans la demande de suppression. Si l’ID de bail n’est pas inclus, l’opération échoue avec 412 (échec de la condition préalable). Toutes les autres opérations de conteneur réussissent sur un conteneur loué, sans inclure l’ID de bail. 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é. Stockage Blob génère un ID de bail, si celui-ci n’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 états possibles d’un bail, ainsi que les commandes ou événements qui provoquent des changements d’état du bail.

Diagramme des états de bail de conteneur et des déclencheurs de changement d’état.

Un bail peut se trouver dans l’un des cinq États, selon que le bail est verrouillé ou déverrouillé, et si le bail est renouvelable dans cet état. Les actions de bail indiqué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’interruption. 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.

Stockage Blob conserve l’ID de bail après l’expiration d’un bail de conteneur. 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, le conteneur a été à nouveau loué ou supprimé depuis la dernière fois que le bail du client a été actif pour la dernière fois.

Si un bail expire plutôt que d’être libéré explicitement, un client peut devoir attendre jusqu’à une minute avant qu’un nouveau bail puisse être acquis pour le conteneur. Toutefois, le client peut renouveler le bail avec l'ID de bail expiré immédiatement.

La propriété du Last-Modified-Time conteneur n’est pas mise à jour par des appels à Lease Container.

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 Stockage Blob.

Résultats des tentatives d'utilisation dans des conteneurs par état du 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 des conteneurs 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)

Facturation

Les demandes de tarification peuvent provenir de clients qui utilisent des API Stockage Blob, soit directement via l’API REST Stockage Blob, soit à partir d’une bibliothèque cliente stockage Azure. Ces demandes cumulent des frais par transaction. Le type de transaction affecte la façon dont le compte est facturé. Par exemple, les transactions de lecture sont comptabilisées dans une catégorie de facturation différente de celle des transactions en écriture. Le tableau suivant montre la catégorie de facturation pour Lease Container les demandes en fonction du type de compte de stockage :

Opération Type de compte de stockage Catégorie de facturation
Conteneur de bail (acquérir, libérer, renouveler) Objet blob de blocs Premium
Usage général v2 Standard		 Autres opérations
Conteneur de bail (acquérir, libérer, renouveler) Usage général v1 standard Lire les opérations
Conteneur de bail (arrêt, modification) Objet blob de blocs Premium
Usage général v2 Standard		 Autres opérations
Conteneur de bail (arrêt, modification) Usage général v1 standard Opérations d’écriture

Pour en savoir plus sur la tarification de la catégorie de facturation spécifiée, consultez Stockage Blob Azure Tarification.

Voir aussi

Autoriser les demandes à Stockage Azure
Codes d’état et d’erreur
Codes d’erreur Stockage Blob
Bail Blob