通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

租赁 Blob

  • 项目

该 Lease Blob 操作创建和管理 Blob 上的锁，以便执行写入和删除操作。 锁的持续时间可以是 15 到 60 秒，也可以是无限期。 在 2012-02-12 之前的版本中，锁定持续时间为 60 秒。

重要

从 2012-02-12 版开始，Lease Blob 操作的某些行为与以前的版本有所不同。 例如，在以前的版本中，可以在释放租约后续订租约。 从版本 2012-02-12 开始，此租约请求失败，但使用较旧版本的 Lease Blob 调用仍然成功。 有关此操作行为的更改列表，请参阅本文后面的“备注”部分。

可以在以下模式之一中调用 Lease Blob 操作：

  • Acquire，用于请求新的租约。

  • Renew，用于续订现有的租约。

  • Change，用于更改现有租约的 ID。

  • Release，用于释放不再需要的租约，以便另一个客户端可以立即获取针对 Blob 的租约。

  • Break，用于结束租约，但确保另一个客户端在当前租约期到期之前无法获取新租约。

请求

可以按如下所示构造 Lease Blob 请求。 建议使用 HTTPS。 将 myaccount 替换为存储帐户的名称。

PUT 方法请求 URI HTTP 版本
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=lease HTTP/1.1

模拟存储服务 URI

对模拟存储服务发出请求时，请将模拟器主机名和Azure Blob 存储端口指定为 127.0.0.1:10000，后跟模拟的存储帐户名称。

PUT 方法请求 URI HTTP 版本
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=lease HTTP/1.0

HTTP/1.1

有关详细信息，请参阅 使用 Azurite 模拟器进行本地 Azure 存储开发。

URI 参数

可以在请求 URI 上指定以下附加参数。

参数 说明
timeout 可选。 timeout 参数以秒表示。 有关详细信息，请参阅 设置 Blob 存储操作的超时。

请求标头

下表介绍必需的和可选的请求标头。

请求标头 说明
Authorization 必需。 指定授权方案、帐户名称和签名。 有关详细信息，请参阅授权对 Azure 存储的请求。
Date 或 x-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息，请参阅授权对 Azure 存储的请求。
x-ms-version 可选。 指定用于此请求的操作的版本。 有关详细信息，请参阅 Azure 存储服务的版本控制。
x-ms-lease-id: <ID> 续订、更改或释放租约所必需的。

可以采用任何有效的 GUID 字符串格式指定 的值 x-ms-lease-id 。 有关有效格式的列表 ，请参阅 Guid 构造函数 (字符串) 。
x-ms-lease-action: <acquire ¦ renew ¦ change ¦ release ¦ break> acquire：请求新的租约。 如果 Blob 没有活动租约，Blob 存储将在 Blob 上创建租约，并返回新的租约 ID。 如果 Blob 具有活动租约，则只能使用活动租约 ID 请求新的租约。 但是，可以为永不过期的租约指定新的 x-ms-lease-duration，包括负 1 (-1) 。

renew：续订租约。 如果请求中指定的租约 ID 与 Blob 关联的 ID 匹配，则可以续订租约。 请注意，即使租约已过期，也可以续订该租约，前提是该租约到期后未再次修改或租用 Blob。 在续订租约时，将重置租约持续时间时钟。

change：版本 2012-02-12 及更高版本。 更改活动租约的租约 ID。 change必须在 中包含当前租约 ID，并在 中包含x-ms-lease-idx-ms-proposed-lease-id新的租约 ID。

release：释放租约。 如果请求中指定的租约 ID 与 Blob 关联的 ID 匹配，则可以释放租约。 释放租约允许另一个客户端在发布完成后立即获取 Blob 的租约。

break：在 Blob 具有活动租约时将其中断。 租约中断后，无法续订。 任何授权的请求都可以中断租用；请求不需要指定匹配的租用 ID。 当租约中断时，允许租约中断期过，在此期间 break ， release 是可以在 Blob 上执行的唯一租约操作。 在租约成功中断后，响应指示可以获取新租约之前等待的时间间隔（秒）。

也可以释放已中断的租约，在这种情况下，另一个客户端可以立即获取 Blob 上的租约。
x-ms-lease-break-period: N 可选。 版本 2012-02-12 及更高版本。 对于 break 操作，这是在租约中断之前应继续保留的建议持续时间（0 到 60 秒）。 仅当中断期短于租约的剩余时间时，才使用此中断期。 如果超过租约的剩余时间，则使用租约的剩余时间。 在中断期到期之前，新租约将不可用，但租约的保留时间可以超过中断期。 如果此标头未随操作一 break 起显示，则固定持续时间的租约将在剩余租约期过后中断，无限租约将立即中断。
x-ms-lease-duration: -1 ¦ n seconds 版本 2012-02-12 及更高版本。 仅在操作上 acquire 允许和必需。 指定租约的持续时间（秒），或者指定 -1 以表示永不过期的租约。 有限期租约在 15 到 60 秒之间。 无法使用 或 change更改renew租约持续时间。
x-ms-proposed-lease-id: <ID> 版本 2012-02-12 及更高版本。 为 acquire可选，对于 是必需的 change。 建议的租约 ID，采用 GUID 字符串格式。 如果建议的租约 ID 格式不正确，则 Blob 存储将返回 400 (Invalid request) 。 有关有效格式的列表 ，请参阅 Guid 构造函数 (字符串) 。
Origin 可选。 指定从中发出请求的来源。 如果存在此标头，则会在响应中产生跨域资源共享 (CORS) 标头。 有关详细信息 ，请参阅存储服务的 CORS 支持 。
x-ms-client-request-id 可选。 提供客户端生成的不透明值，其中包含 1-kibite (KiB) 配置日志记录时记录在日志中的字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息，请参阅监视Azure Blob 存储。

仅当满足指定条件时，此操作还支持使用条件标头来运行操作。 有关详细信息，请参阅 为 Blob 存储操作指定条件标头。

请求正文

无。

示例请求

以下示例请求说明了如何获取租约：

  
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=

响应

响应包括 HTTP 状态代码和一组响应标头。

状态代码

为租约操作返回的成功状态代码如下所示：

  • Acquire：此操作成功后返回状态代码 201（已创建）。

  • Renew：此操作成功后返回状态代码 200（正常）。

  • Change：此操作成功后返回状态代码 200（正常）。

  • Release：此操作成功后返回状态代码 200（正常）。

  • Break：此操作成功后返回状态代码 202（已接受）。

有关状态代码的信息，请参阅 状态和错误代码。

响应头

此操作的响应包括以下标头。 响应还可以包含其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范。

语法 说明
ETag 包含可用于有条件地执行操作的值。 有关详细信息 ，请参阅为 Blob 存储操作指定条件标头 。

针对版本 2013-08-15 及更高版本发出的请求返回此标头，并且 ETag 值在引号中。

该 Lease Blob 操作不会修改此属性。
Last-Modified 上次修改 Blob 的日期/时间。 有关详细信息，请参阅 标头中日期时间值的表示形式。

针对 Blob 的任何写操作（包括更新 Blob 的元数据或属性）都会更改 Blob 的上次修改时间。 该 Lease Blob 操作不会修改此属性。
x-ms-lease-id: <id> 请求租约时，Blob 存储将返回唯一的租约 ID。 在租约处于活动状态时，必须在写入到 Blob 或者续订、更改或释放租约的任何请求中包含租约 ID。

成功的续订操作还会返回活动租约的租约 ID。
x-ms-lease-time: seconds 在租约期内的大约剩余时间（秒）。 仅为成功的租约中断请求返回此标头。 如果中断是即时的， 0 则返回 。
x-ms-request-id 此标头唯一标识发出的请求，可用于对请求进行故障排除。 有关详细信息，请参阅 API 操作疑难解答。
x-ms-version 指示用于运行请求的 Blob 存储版本。 针对 2009-09-19 和更高版本发出的请求将返回此标头。
Date 一个 UTC 日期/时间值，该值指示启动响应的时间。 服务生成此值。
Access-Control-Allow-Origin 如果请求包含 Origin 标头，并且使用匹配规则启用了 CORS，则返回 。 如果存在匹配项，此标头返回原始请求标头的值。
Access-Control-Expose-Headers 如果请求包含 Origin 标头，并且使用匹配规则启用了 CORS，则返回 。 返回将向客户端或请求的发出方公开的响应标头的列表。
Access-Control-Allow-Credentials 如果请求包含标头 Origin ，并且使用不允许所有源的匹配规则启用 CORS，则返回 。 此标头设置为 true。
x-ms-client-request-id 可以使用此标头对请求和相应的响应进行故障排除。 如果请求中存在此标头的值，则此标头的值等于该标头的值 x-ms-client-request-id 。 该值最多为 1,024 个可见 ASCII 字符。 x-ms-client-request-id如果请求中不存在标头，则它不会出现在响应中。

响应正文

无。

示例响应

下面是获取租约的请求的示例响应：

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>

授权

在 Azure 存储中调用任何数据访问操作时，都需要授权。 可以如下所述授权 Lease Blob 操作。

重要

Microsoft 建议将 Microsoft Entra ID 与托管标识配合使用来授权对 Azure 存储的请求。 与共享密钥授权相比，Microsoft Entra ID提供优越的安全性和易用性。

Azure 存储支持使用 Microsoft Entra ID 授权对 Blob 数据的请求。 使用 Microsoft Entra ID，可以使用 Azure 基于角色的访问控制 (Azure RBAC) 向安全主体授予权限。 安全主体可以是用户、组、应用程序服务主体或 Azure 托管标识。 安全主体由 Microsoft Entra ID 进行身份验证，以返回 OAuth 2.0 令牌。 然后可以使用令牌来授权对 Blob 服务发出请求。

若要详细了解如何使用Microsoft Entra ID授权，请参阅使用 Microsoft Entra ID 授权访问 blob。

权限

下面列出了Microsoft Entra用户、组、托管标识或服务主体调用Lease Blob操作所需的 RBAC 操作，以及包含此操作的最低特权内置 Azure RBAC 角色：

若要详细了解如何使用 Azure RBAC 分配角色，请参阅 分配 Azure 角色以访问 Blob 数据。

注解

Blob 上的租约提供对 Blob 的排他写入和删除访问。 要写入到具有活动租约的 Blob 中，客户端必须在写入请求中包含活动租约 ID。 在获取租约时指定的持续时间内授予租约。 此持续时间可以介于 15 到 60 秒之间，或无限期。

在客户端获取租约时，将返回租约 ID。 如果未在获取请求中指定租约 ID，Blob 存储将生成租约 ID。 客户端可以使用此租约 ID 续订租约、更改其租约 ID 或释放租约。

在租约处于活动状态时，必须在任何以下操作的请求中包含租约 ID：

如果未包含租约 ID，则这些操作在租用的 Blob 上失败，并带有 412 – Precondition failed。

以下操作在未包括租约 ID 的情况下成功对租用的 Blob：

对于具有活动租约的 Blob 上的操作，无需包含租约 ID GET 。 但是，所有操作都 GET 支持条件租用参数，在该参数中，仅当请求附带的租约 ID 有效时，操作才会继续。

允许在包含具有活动租用的 Blob 的容器上执行所有容器操作，包括删除容器。 因此，即使容器中的 Blob 具有活动租约，也可以删除容器。 使用租用容器操作控制删除容器的权限。

租约状态

下图说明了租约的五种状态，以及导致租约状态发生变化的命令或事件。

显示 Blob 租约状态和状态更改触发器的关系图。

租约可以处于以下状态之一，具体取决于租约是锁定还是已解锁，以及该状态是否可续订。 上图中显示的租用操作会导致状态转换。

续订状态 锁定的租约 未锁定的租约
可续订租约 已租用 已过期
不可续订的租赁 重大 已中断，可用

  • Available：租约已解锁，可以获取。 允许的操作：acquire。

  • Leased：租约已锁定。 允许的操作：acquire（仅相同租约 ID）、renew、change、release 和 break。

  • Expired：租约持续时间已过期。 允许的操作：acquire、renew、release 和 break。

  • Breaking：租约已中断，但租约将继续锁定，直到中断期到期。 允许的操作：release 和 break。

  • Broken：租约已中断，中断期已过期。 允许的操作：acquire、release 和 break。

租约到期后，租约 ID 由 Blob 存储维护，直到再次修改或租用 Blob。 客户端可以使用过期的租约 ID 尝试续订或释放租约。 如果操作成功，则表示自租约 ID 上次有效以来，Blob 未发生更改。

如果客户端尝试使用其以前的租约 ID 续订或释放租约，但请求失败，则由于客户端的租约上次处于活动状态，Blob 会再次被修改或租用。 然后，客户端必须在 Blob 上获取新的租约。

如果租约过期而不是显式释放，客户端可能需要等待长达一分钟，然后才能获取 Blob 的新租约。 但是，如果 Blob 尚未修改，客户端可以立即使用其租约 ID 续订租约。

请注意，无法为 blob 快照授予租约，因为快照是只读的。 如果针对快照请求租约，则会导致返回状态代码 400（错误的请求）。

Blob 的 Last-Modified-Time 属性不会通过调用 Lease Blob来更新。

下表说明了在具有处于不同状态的租约的 Blob 上执行操作的结果。 字母 (A) 、 (B) 和 (C) 表示租约 ID， (X) 表示 Blob 存储生成的租约 ID。

Blob 上的使用尝试的结果，按租约状态划分

操作 可用 已租用 (A) 正在中断 (A) 已中断 (A) 已过期 (A)
使用 (A) 进行写入 失败 (412) 已租用 (A)，写入成功 正在中断 (A)，写入成功 失败 (412) 失败 (412)
使用 (B) 进行写入 失败 (412) (409) 失败 失败 (412) 失败 (412) 失败 (412)
写入，未指定租约 可用，写入成功 失败 (412) 失败 (412) 可用，写入成功 可用，写入成功
使用 (A) 进行读取 失败 (412) 已租用 (A)，读取成功 正在中断 (A)，读取成功 失败 (412) 失败 (412)
使用 (B) 进行读取 失败 (412) (409) 失败 (409) 失败 失败 (412) 失败 (412)
读取，未指定租约 可用，读取成功 已租用 (A)，读取成功 正在中断 (A)，读取成功 已中断 (A)，读取成功 已过期 (A)，读取成功

Blob 上的租约操作的结果，按租约状态划分

操作 可用 已租用 (A) 正在中断 (A) 已中断 (A) 已过期 (A)
Acquire，无建议的租约 ID 已租用 (X) (409) 失败 (409) 失败 已租用 (X) 已租用 (X)
Acquire (A) 已租用 (A) 已租用 (A)，新的持续时间 (409) 失败 已租用 (A) 已租用 (A)
Acquire (B) 已租用 (B) (409) 失败 (409) 失败 已租用 (B) 已租用 (B)
Break，期间 = 0 (409) 失败 已中断 (A) 已中断 (A) 已中断 (A) 已中断 (A)
Break，句点>0 (409) 失败 正在中断 (A) 正在中断 (A) 已中断 (A) 已中断 (A)
Change，(A) 到 (B) (409) 失败 已租用 (B) (409) 失败 (409) 失败 (409) 失败
Change，(B) 到 (A) (409) 失败 已租用 (A) (409) 失败 (409) 失败 (409) 失败
Change，(B) 到 (C) (409) 失败 (409) 失败 (409) 失败 (409) 失败 (409) 失败
Renew (A) (409) 失败 已租用 (A)，重置到期时钟 (409) 失败 (409) 失败 租用 (A) （如果 blob 尚未修改）。

失败 (409)（如果已修改 Blob）。
Renew (B) (409) 失败 (409) 失败 (409) 失败 (409) 失败 (409) 失败
Release (A) (409) 失败 可用 可用 可用 可用
Release (B) (409) 失败 (409) 失败 (409) 失败 (409) 失败 (409) 失败
持续时间过期 可用 已过期 (A) 已中断 (A) 已中断 (A) 已过期 (A)

版本 2012-02-12 中引入的对租用 Blob 的更改

以下列表指定对版本 2012-02-12 中引入的行为所做的更改 Lease Blob 。

  • 对 获取租约的调用 Lease Blob 现在必须包含租约持续时间标头。 如果在未指定租约持续时间的情况下尝试获取租约，则服务将 400 Bad Request – Missing required header返回 。

  • 在释放租约后，你无法再续订该租约。 如果尝试这样做，服务将 409 Conflict – The lease ID specified did not match the lease ID for the blob返回 。 调用 release，然后调用续订的应用程序现在必须保存 ETag 发布调用中的 。 然后， If-Match 应用程序必须使用条件标头调用 acquire，以便仅在 Blob 未更改时获取租约。

  • 在释放租约后，你无法再中断该租约。 如果尝试这样做，服务将 409 Conflict – There is currently no lease on the blob返回 。

  • 现在，你可以中断正在中断或已中断的租约，从而使中断操作是幂等的。 在以前的版本中，此操作将失败并返回 409 Conflict – The lease has already been broken and cannot be broken again。 可以通过此更改缩短中断的持续时间。 如果中断处于中断状态的租约，并且包含比剩余中断期短的持续时间，则使用较短的持续时间。

计费

定价请求可以源自使用 Blob 存储 API 的客户端，可以直接通过 Blob 存储 REST API 或 Azure 存储客户端库。 这些请求按事务产生费用。 事务类型会影响帐户的计费方式。 例如，读取事务应计为与写入事务不同的计费类别。 下表显示了基于存储帐户类型的请求的计费类别 Lease Blob ：

操作 存储帐户类型 计费类别
租用 Blob (获取、发布、续订) 高级块 blob
标准常规用途 v2		 其他操作
租用 Blob (获取、发布、续订) 标准常规用途 v1 读取操作
租用 Blob (中断、更改) 高级块 blob
标准常规用途 v2		 其他操作
租用 Blob (中断、更改) 标准常规用途 v1 写入操作

另请参阅

new-blob-lease-features-infinite-leases-smaller-lease-times-and-more.aspx)
授权对 Azure 存储的请求
状态和错误代码
Blob 存储错误代码
Lease Container（租赁容器）