租用共享 (FileREST API) - Azure 文件存储

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

项目
07/19/2023

该Lease Share操作在 Azure 文件共享或共享快照上建立和管理锁。此 API 完全受支持，但它是旧版管理 API。请改用存储资源提供程序提供的文件共享 - 租约， (Microsoft.Storage) 。若要详细了解如何使用存储资源提供程序以编程方式与 FileShare 资源交互，请参阅对 FileShares 的操作。

锁的持续时间可以是 15 到 60 秒，也可以是无限期。可以在以下模式之一中调用 Lease Share 操作：

Acquire：请求新的租约。
Renew：续订现有租约。
Change：更改现有租约的 ID。
Release：如果不再需要租约，则释放租约，以便另一个客户端可以立即获取针对文件共享的租约。
Break：结束租约，但确保其他客户端在当前租约期到期之前无法获取新租约。

注意

该 Lease Share 操作在版本 2020-02-10 及更高版本中可用。

协议可用性

已启用文件共享协议	可用
SMB
NFS

请求

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

方法	请求 URI	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

URI 参数

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

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

请求标头

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

请求标头	说明
`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: <action>`	`acquire`：请求新的租约。如果文件共享没有活动租约，Azure 文件存储在文件共享上创建租约并返回新的租约 ID。如果文件共享具有活动租约，则只能使用活动租约 ID 请求新的租约。但是，可以为永不过期的租约指定新的 `x-ms-lease duration`，包括负 1 (-1) 。 `renew`：续订租约。如果请求中指定的租约 ID 与文件共享关联的 ID 匹配，则可以续订租约。请注意，即使租约已过期，也可以续订租约，前提是文件共享自该租约到期后未再次租用。在续订租约时，将重置租约持续时间时钟。 `change`：更改活动租约的租约 ID。 `change`必须在中包含当前租约 ID，并在中包含`x-ms-lease-idx-ms-proposed-lease-id`新的租约 ID。 `release`：释放租约。如果请求中指定的租约 ID 与文件共享关联的 ID 匹配，则可以释放租约。释放租约允许另一个客户端在发布完成后立即获取文件共享的租约。 `break`：如果文件共享具有活动租约，则中断租约。租约中断后，无法续订。任何授权请求都可能会中断租约。该请求不需要指定匹配的租约 ID。当租约中断时，允许租约中断期过，而 `break` 和 `release` 是在此期间可以对文件共享执行的唯一操作。在租约成功中断后，响应指示可以获取新租约之前等待的时间间隔（秒）。也可以释放已中断的租约。客户端可以立即获取已释放的文件共享租约。
`x-ms-lease-break-period: N`	可选。对于操作 `break` ，这是租约在中断前应继续的建议持续时间，以秒为单位，介于 0 到 60 之间。仅当中断期短于租约的剩余时间时，才使用此中断期。如果超过租约的剩余时间，则使用租约的剩余时间。在中断期到期之前，新租约不可用，但租约的保留时间可以超过中断期。如果此标头未随操作一 `break` 起显示，则固定持续时间的租约将在剩余租约期过后中断，无限租约将立即中断。
`x-ms-lease-duration: -1`	对于 `acquire` 是必需的。指定租约的持续时间（秒），或者指定 -1 以表示永不过期的租约。有限期租约在 15 到 60 秒之间。无法使用或 `change`更改`renew`租约持续时间。
`x-ms-proposed-lease-id: <ID>`	为 `acquire`可选，对于是必需的 `change`。建议的租约 ID，采用 GUID 字符串格式。如果建议的租约 ID 格式不正确，Azure Blob 存储返回 `400 (Invalid request)` 。有关有效格式的列表，请参阅 Guid 构造函数 (字符串) 。
`Origin`	可选。指定从中发出请求的来源。如果存在此标头，则会在响应中产生跨域资源共享 (CORS) 标头。有关详细信息，请参阅存储服务的 CORS 支持。
`x-ms-client-request-id`	可选。提供客户端生成的不透明值，其中包含 1-kibite (KiB) 配置日志记录时记录在日志中的字符限制。强烈建议使用此标头将客户端活动与服务器接收的请求相关联。有关详细信息，请参阅监视Azure 文件存储。

请求正文

无。

示例请求

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

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=

响应

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

状态代码

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

Acquire：此操作成功后返回状态代码 201（已创建）。
Renew：此操作成功后返回状态代码 200（正常）。
Change：此操作成功后返回状态代码 200（正常）。
Release：此操作成功后返回状态代码 200（正常）。
Break：此操作成功后返回状态代码 202（已接受）。

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

响应头

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

语法	说明
`ETag`	`ETag`文件共享的。
`Last-Modified`	返回上次修改文件共享的日期和时间。有关详细信息，请参阅标头中的日期时间值的表示形式。修改文件共享或其属性或元数据的任何操作将更新上次修改的时间。这包括设置文件共享的权限。对 Blob 的操作不会影响文件共享的上次修改时间。
`x-ms-lease-id: <id>`	请求租约时，Azure 文件存储返回唯一的租约 ID。当租约处于活动状态时，你必须在删除文件共享或续订、更改或释放租约的任何请求中包含租约 ID。成功的续订操作还会返回活动租约的租约 ID。
`x-ms-lease-time: seconds`	在租约期内的大约剩余时间（秒）。仅为成功的租约中断请求返回此标头。如果中断是即时的， `0` 则返回。
`x-ms-request-id`	唯一标识发出的请求，可用于对请求进行故障排除。有关详细信息，请参阅 API 操作故障排除。
`x-ms-version`	指示用于运行请求的 FileREST API 的版本。
`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-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

授权

只有帐户所有者才能调用此操作。

注解

文件共享上的租约提供对文件共享的独占删除访问权限。获取文件共享操作将成功对租用的文件共享，而不包括租约 ID。设置文件共享操作需要文件共享租约 ID。如果设置文件共享操作中不包含租约 ID，则操作将失败，) 412 (前置条件失败。在获取租约时指定的持续时间内授予租约，可以是 15 到 60 秒，也可以是无限期。

在客户端获取租约时，将返回租约 ID。如果未在获取请求中指定租约 ID，Azure 文件存储将生成租约 ID。客户端可以使用此租约 ID 续订租约、更改其租约 ID 或释放租约。下图说明了租约的五种状态，以及导致租约状态发生变化的命令或事件。

文件共享租用状态和状态更改触发器的示意图。

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

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

Available，租约已解锁而可以获取。允许的操作：acquire。
Leased，租约已锁定。允许的操作：acquire（仅相同租约 ID）、renew、change、release 和 break。
Expired，租约已过期。允许的操作：acquire、renew、release 和 break。
Breaking，租约已中断，但租约将继续锁定，直到中断期到期。允许的操作：release 和 break。
Broken，租约已中断，中断期已过期。允许的操作：acquire、release 和 break。

Azure 文件存储在文件共享租约过期后保留租约 ID。客户端可以使用过期的租约 ID 续订或释放租约。如果客户端尝试使用其以前的租约 ID 续订或释放过期的租约，并且请求失败，则意味着文件共享已重新租用或删除，因为其租约上次处于活动状态。如果租约过期而不是显式释放，客户端可能需要等待长达一分钟才能获取文件共享的新租约。但是，客户端可以通过过期的租约 ID 立即续订租约。

文件共享的 Last-Modified-Time 属性不会通过调用 Lease Share来更新。

下面的表说明对具有各种租约状态的租约的容器进行操作的结果。字母 (A) 、 (B) 和 (C) 表示租约 ID， (X) 表示Azure 文件存储生成的租约 ID。

按租用状态对共享的使用尝试的结果

操作	可用	已租用 (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)，操作成功

按租赁状态对股份进行租赁操作的结果

操作	可用	已租用 (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)
`Renew` (B)	(409) 失败	(409) 失败	(409) 失败	(409) 失败	(409) 失败
`Release` (A)	(409) 失败	可用	可用	可用	可用
`Release` (B)	(409) 失败	(409) 失败	(409) 失败	(409) 失败	(409) 失败
持续时间过期	可用	已过期 (A)	已中断 (A)	已中断 (A)	已过期 (A)

通过

租约共享