Lease Blob

  • Article

L’opération Lease Blob crée et gère un verrou sur un objet blob pour les opérations d’écriture et de suppression. La durée du verrou peut être de 15 à 60 secondes, ou peut être infinie. Dans les versions antérieures à 2012-02-12, la durée de verrouillage est de 60 secondes.

Important

Depuis la version du 12/02/2012, certains comportements de l'opération Lease Blob diffèrent des versions antérieures. Par exemple, dans les versions précédentes, vous pouviez renouveler un bail après l’avoir libéré. À compter de la version 2012-02-12, cette demande de bail échoue, mais les appels qui utilisent des versions antérieures de Lease Blob réussissent toujours. Pour obtenir la liste des modifications apportées au comportement de cette opération, consultez la section « Remarques » plus loin dans cet article.

Vous pouvez appeler l’opération Lease Blob 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 l’objet blob.

  • 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é.

Requête

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

URI de requête de méthode PUT Version HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=lease HTTP/1.1

URI du 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é.

URI de requête de méthode PUT Version HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=lease HTTP/1.0

HTTP/1.1

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

Paramètres URI

Vous pouvez spécifier le paramètre supplémentaire suivant sur 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 des 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 x-ms-lease-id quel format de chaîne GUID valide. Consultez Guid Constructor (String) pour obtenir la liste des formats valides.
x-ms-lease-action: <acquire ¦ renew ¦ change ¦ release ¦ break> acquire : demande un nouveau bail. Si l’objet blob n’a pas de bail actif, le Stockage Blob crée un bail sur l’objet blob et retourne un nouvel ID de bail. Si l’objet blob a un bail actif, vous pouvez demander un nouveau bail uniquement à l’aide de l’ID de bail actif. Toutefois, vous pouvez spécifier un nouveau x-ms-lease-duration, y compris un 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é sur la demande correspond à celui associé à l’objet blob. Notez que le bail peut être renouvelé même s’il a expiré, tant que l’objet blob n’a pas été modifié ou loué à nouveau depuis l’expiration de ce bail. Lorsque vous renouvelez un bail, la durée de bail est réinitialisée.

change: version 2012-02-12 et ultérieure. Modifie l'ID du bail d'un bail actif. Un change doit inclure l’ID de bail actuel dans x-ms-lease-idet 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é à l’objet blob. La libération du bail permet à un autre client d’acquérir immédiatement le bail pour l’objet blob, dès que la publication est terminée.

break : résilie le bail, si l'objet blob a un bail actif. Une fois qu’un bail est rompu, il ne peut pas être renouvelé. Toute requête autorisée peut arrêter le bail ; la demande ne spécifie pas obligatoirement un ID de bail correspondant. Lorsqu’un bail est rompu, la période d’arrêt de bail est autorisée à s’écouler, pendant laquelle break et release sont les seules opérations de bail que vous pouvez effectuer sur l’objet blob. 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 rompu peut également être libéré, auquel cas un autre client peut acquérir immédiatement le bail sur l’objet blob.
x-ms-lease-break-period: N facultatif. Version 2012-02-12 et versions ultérieures. 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 d’arrêt n’est utilisée que si elle est inférieure à la durée restante 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 de pause. Si cet en-tête n’apparaît pas avec une break opération, un bail à durée fixe se termine après l’expiration de la période de bail restante et un bail infini se termine immédiatement.
x-ms-lease-duration: -1 ¦ n seconds Version 2012-02-12 et versions ultérieures. Autorisés et requis uniquement sur une acquire opération. 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 à l’aide de renew ou changede .
x-ms-proposed-lease-id: <ID> Version 2012-02-12 et versions ultérieures. Facultatif pour acquireet obligatoire pour change. ID de bail proposé, dans un format de chaîne GUID. Le Stockage Blob retourne 400 (Invalid request) si l’ID de bail proposé n’est pas au format correct. Consultez Guid Constructor (String) pour obtenir la liste des formats valides.
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 de 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 que le serveur reçoit. 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/myblob?comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-lease-action: acquire  
x-ms-lease-duration: -1  
x-ms-proposed-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-date: <date>  
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 Contient une valeur que vous pouvez utiliser pour effectuer des opérations de manière conditionnelle. Pour plus d’informations, consultez Spécification d’en-têtes conditionnels pour les opérations de stockage Blob .

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.

L’opération Lease Blob ne modifie pas cette propriété.
Last-Modified Date et heure de la dernière modification apportée à l'objet blob. Pour plus d’informations, consultez Représentation des valeurs date-heure dans les en-têtes.

Toute opération d'écriture dans l'objet blob (notamment les mises à jour des métadonnées ou des propriétés de l'objet blob), modifie l'heure de la dernière modification de l'objet blob. L’opération Lease Blob ne modifie pas cette propriété.
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 d'écriture dans l'objet blob, 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 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: 2015-02-21  
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: <date>

Autorisation

Une autorisation est requise lors de l’appel d’une opération d’accès aux données dans stockage Azure. Vous pouvez autoriser l’opération Lease Blob comme décrit ci-dessous.

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 requête auprès du service 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

Vous trouverez ci-dessous l’action RBAC nécessaire pour qu’un utilisateur, un groupe ou un principal de service Microsoft Entra appelle l’opérationLease Blob, ainsi que le rôle RBAC intégré Azure 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 objet blob fournit un accès exclusif en écriture et en suppression à l'objet blob. Pour écrire dans un objet blob avec un bail actif, un client doit inclure l'ID de bail actif à la demande d'écriture. Le bail est accordé pour la durée spécifiée lors de l’acquisition du bail. Cette durée 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é. Le Stockage Blob 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.

Quand un bail est actif, l'ID de bail doit être inclus dans la demande pour les opérations suivantes :

Si l’ID de bail n’est pas inclus, ces opérations échouent sur un objet blob loué, avec 412 – Precondition failed.

Les opérations suivantes réussissent sur un objet blob loué, sans inclure l’ID de bail :

Il n’est pas nécessaire d’inclure l’ID de bail pour GET les opérations sur un objet blob qui a un bail actif. Toutefois, toutes les GET opérations prennent en charge un paramètre de bail conditionnel, où l’opération ne se poursuit que si l’ID de bail inclus dans la demande est valide.

Toutes les opérations de conteneur sont autorisées sur un conteneur qui comprend des blobs avec un bail actif, notamment Delete Container. Par conséquent, un conteneur peut être supprimé même si les objets blob qu’il contient ont des baux actifs. Utilisez l’opération Lease Container pour contrôler les droits de suppression d’un conteneur.

États de 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.

Diagramme montrant les états de bail d’objet blob et les déclencheurs de changement d’état.

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.

Une fois qu’un bail a expiré, l’ID de bail est conservé par le Stockage Blob jusqu’à ce que l’objet blob soit modifié ou loué à nouveau. Un client peut tenter de renouveler ou de libérer le bail à l’aide de son ID de bail expiré. Si l’opération réussit, cela signifie que l’objet blob n’a pas été modifié depuis la dernière validité de l’ID de bail.

Si le client tente de renouveler ou de libérer un bail avec son ID de bail précédent et que la demande échoue, l’objet blob a été modifié ou loué à nouveau depuis la dernière fois que le bail du client était actif. Le client doit ensuite acquérir un nouveau bail sur l'objet blob.

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 l’objet blob. Toutefois, le client peut renouveler immédiatement le bail avec son ID de bail, si l’objet blob n’a pas été modifié.

Notez qu’un bail ne peut pas être accordé pour un objet blob instantané, car les instantanés sont en lecture seule. La demande d'un bail sur un instantané entraîne un code d'état 400 (Demande incorrecte).

La propriété de l’objet Last-Modified-Time blob n’est pas mise à jour par les appels à Lease Blob.

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

Résultats des tentatives d'utilisation dans des objets blob par état du bail

Action Disponible Loué (A) En cours de résiliation (A) Résilié (A) Expiré (A)
Écrire avec (A) Échecs (412) Loué (A), l'écriture a réussi En cours de résiliation (A), l'écriture a réussi Échecs (412) Échecs (412)
Écrire avec (B) Échecs (412) Échec (409) Échecs (412) Échecs (412) Échecs (412)
Écriture, aucun bail spécifié Disponible, l'écriture a réussi Échecs (412) Échecs (412) Disponible, l'écriture a réussi Disponible, l'écriture a réussi
Lecture avec (A) Échecs (412) Loué (A), la lecture a réussi En cours de résiliation (A), la lecture a réussi Échecs (412) Échecs (412)
Lire avec (B) Échecs (412) Échec (409) Échec (409) Échecs (412) Échecs (412)
Lecture, aucun bail spécifié Disponible, la lecture a réussi Loué (A), la lecture a réussi En cours de résiliation (A), la lecture a réussi Résilié (A), la lecture a réussi Expiré (A), la lecture a réussi

Résultats des opérations de bail sur des objets blob 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) Baild(A), si l’objet blob n’a pas été modifié.

Échec (409) si l'objet blob a été modifié.
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)

Modifications apportées à l’objet blob de bail dans la version 2012-02-12

La liste suivante spécifie les changements de Lease Blob comportement introduits dans la version 2012-02-12.

  • Un appel à pour Lease Blob acquérir un bail doit maintenant inclure un en-tête de durée de bail. Si vous essayez d’acquérir un bail sans spécifier de durée de bail, le service retourne 400 Bad Request – Missing required header.

  • Vous ne pouvez plus renouveler un bail après l'avoir libéré. Si vous essayez de le faire, le service retourne 409 Conflict – The lease ID specified did not match the lease ID for the blob. Les applications qui ont appelé release, puis ont appelé renew, doivent maintenant enregistrer à ETag partir de l’appel de mise en production. Ensuite, les applications doivent appeler acquire, avec un If-Match en-tête conditionnel, pour acquérir le bail uniquement lorsque l’objet blob est inchangé.

  • Vous ne pouvez plus résilier un bail après l'avoir libéré. Si vous essayez de le faire, le service retourne 409 Conflict – There is currently no lease on the blob.

  • Vous pouvez désormais résilier un bail en cours de résiliation ou résilié, ce qui rend les opérations de résiliation idempotentes. Dans les versions précédentes, vous obteniez le message d'échec 409 Conflict – The lease has already been broken and cannot be broken again. Cette modification vous permet de raccourcir la durée d'une résiliation. Si vous rompez un bail à l’état de rupture et incluez une durée plus courte que la période d’arrêt restante, votre durée plus courte est utilisée.

Facturation

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

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

Voir aussi

new-blob-lease-features-infinite-leases-smaller-lease-times-and-more.aspx)
Autoriser les demandes dans le Stockage Azure
Codes d’état et d’erreur
Codes d’erreur stockage Blob
Lease Container