你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
租约文件
Lease File
作创建和管理文件上的锁以执行写入和删除作。 版本 2019-02-02 及更高版本支持 Lease File
。
可以在以下模式之一中调用 Lease File
作:
-
Acquire
,请求新的租约。 -
Change
,更改现有租约的 ID。 -
Release
,如果不再需要租约,则释放租约,以便另一个客户端可以立即获取针对该文件的租约。 -
Break
,以强行结束租约,但确保另一个客户端在当前租约期到期之前无法获取新租约。
协议可用性
已启用文件共享协议 | 可用 |
---|---|
SMB |
![]() |
NFS |
![]() |
请求
Lease File
请求构造如下。 建议使用 HTTPS。
方法 | 请求 URI | HTTP 版本 |
---|---|---|
放 | https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease |
HTTP/1.1 |
将请求 URI 中显示的路径组件替换为你自己的路径组件,如下所示:
路径组件 | 描述 |
---|---|
myaccount |
存储帐户的名称。 |
myshare |
文件共享的名称。 |
mydirectorypath |
自选。 目录的路径。 |
myfile |
文件的名称。 |
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: <acquire ¦ change ¦ release ¦ break> |
acquire :请求新的租约。 如果文件没有活动租约,Azure 文件会在该文件上创建租约,并返回新的租约 ID。 如果文件具有活动租约,则只能使用活动租约 ID 请求新的租约。change :更改活动租约的租约 ID。
change 必须在 x-ms-lease-id 中包含当前租约 ID,x-ms-proposed-lease-id 中必须包含新的租约 ID。release :释放租约。 如果请求中指定的租约 ID 与与文件关联的租约 ID 匹配,则可以释放租约。 释放租约允许另一个客户端在发布完成后立即获取文件的租约。break :如果文件具有活动租约,则中断租约。 任何授权请求都可能会中断租约。 不需要请求来指定匹配的租约 ID。 无限租约立即中断。 |
x-ms-lease-duration: -1 |
仅在 acquire 作上允许和必需。 需要 -1 ,以指示永不过期的租约。 |
x-ms-proposed-lease-id: <ID> |
acquire 可选,change 是必需的。 建议的租约 ID,采用 GUID 字符串格式。 如果建议的租约 ID 格式不正确,Azure 文件将返回 400 (Invalid request) 。 有关有效格式的列表,请参阅 Guid 构造函数(字符串)。 |
x-ms-client-request-id |
自选。 提供客户端生成的不透明值,该值具有配置日志记录时日志中记录的 1-kibibyte (KiB) 字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息,请参阅 监视 Azure 文件。 |
x-ms-file-request-intent |
如果需要 Authorization 标头指定 OAuth 令牌。 可接受的值为 backup 。 此标头指定,如果 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 或 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 包含在分配给使用 Authorization 标头授权的标识的 RBAC 策略中,则应授予 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 。 适用于版本 2022-11-02 及更高版本。 |
x-ms-allow-trailing-dot: { <Boolean> } |
自选。 版本 2022-11-02 及更高版本。 布尔值指定是否应剪裁请求 URL 中存在的尾随点。 有关详细信息,请参阅 命名和引用共享、目录、文件和元数据。 |
请求正文
没有。
示例请求
以下示例请求演示如何获取租约:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease HTTP/1.1
Request Headers:
x-ms-version: 2019-07-07
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 myaccount:esSKMOYdK4o+nGTuTyeOLBI+xqnqi6aBmiW4XI699+o=
响应
响应包括 HTTP 状态代码和一组响应标头。
状态代码
为租约作返回的成功状态代码如下:
-
Acquire
:成功的作返回状态代码 201(已创建)。 -
Change
:成功的作返回状态代码 200(正常)。 -
Release
:成功的作返回状态代码 200(正常)。 -
Break
:成功的作返回状态代码 202(已接受)。
有关状态代码的信息,请参阅 状态和错误代码。
响应标头
此作的响应包括下表中的标头。 响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范。
响应标头 | 描述 |
---|---|
ETag |
包含一个值,可用于按引号有条件地执行作。
Lease File 作不会修改此属性。 |
Last-Modified |
上次修改文件的日期/时间。 有关详细信息,请参阅 标头中的日期/时间值的表示形式。 对文件的任何写入作(包括文件的元数据或属性的更新)更改文件的上次修改时间。 Lease File 作不会修改此属性。 |
x-ms-lease-id:<ID> |
请求租约时,Azure 文件存储将返回唯一的租约 ID。 当租约处于活动状态时,必须包含租约 ID 以及写入文件或更改或更改或释放租约的任何请求。 成功的续订作还会返回活动租约的租约 ID。 |
x-ms-lease-time: seconds |
仅返回成功请求以中断租约。
0 将立即返回中断。 |
x-ms-request-id |
唯一标识已发出的请求,并可用于对请求进行故障排除。 有关详细信息,请参阅 API作故障排除。 |
x-ms-version |
指示用于运行请求的 Azure 文件的版本。 |
Date |
一个 UTC 日期/时间值,指示响应的启动时间。 服务将生成此值。 |
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: 2019-07-07
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5
Date: <date>
授权
只有帐户所有者才能调用此作。
言论
文件的租约提供对文件的独占写入和删除访问权限。 若要写入具有活动租约的文件,客户端必须包含包含写入请求的活动租约 ID。 该租约将无限期授予。
当客户端获取租约时,将返回租约 ID。 如果未在获取请求中指定租约 ID,Azure 文件会生成租约 ID。 客户端可以使用此租约 ID 更改其租约 ID 或释放租约。
当租约处于活动状态时,租约 ID 必须包含在以下任何作的请求中:
如果未包含租约 ID,则这些作在租用的文件上失败,412 – Precondition failed
。
以下作在租约文件上成功,而不包括租约 ID:
- 获取文件
- 获取文件元数据
- 获取文件属性
- 列表范围
- 列出目录和文件
- 复制文件(源文件不需要租约 ID)。
-
租约文件(REST API)(
x-ms-lease-action: break
不需要租约 ID)。
无需在具有活动租约的文件上包括 GET作的租约 ID。 但是,所有 GET作都支持条件租约参数。 在此类型的参数中,仅当请求附带的租约 ID 有效时,该作才会继续。
允许在包含具有活动租约的文件的共享上执行所有共享作,包括 删除共享。 因此,即使其中的文件具有活动租约,也可以删除共享。
租约状态
下图显示了租约的三种状态,以及导致租约状态更改的命令或事件。
租约可以分为三种状态,具体取决于租约是锁定还是解锁,以及租约是否在该状态下可续订。 上图中显示的租约作会导致状态转换。
-
Available
:租约已解锁,可以获取。 允许的作:acquire
。 -
Leased
:租约已锁定。 允许的作:acquire
(仅限同一租约 ID)、change
、release
和break
。 -
Broken
:租约已中断。 允许的作:acquire
、release
和break
。
请注意,无法为共享快照中的文件授予租约,因为快照是只读的。 针对共享快照中的文件请求租约会导致状态代码 400 (请求错误)。
如果文件租约处于 中断 状态,并且 Put Range作将写入文件,则租约状态将更改为 可用。 但是,如果文件设置了只读属性,服务器将返回冲突 409。
对 Lease File
的调用不会更新文件的 Last-Modified-Time
属性。
下表显示了对处于各种租约状态的文件执行的作结果。 字母(A)、(B)和(C)表示租约 ID,(X)表示 Azure 文件生成的租约 ID。
按租约状态对文件使用尝试的结果
行动 | 可用 | 租用 (A) | 破碎 (A) |
---|---|---|---|
使用 (A) 进行写入 | 失败 (412) | 租用 (A),写入成功 | 失败 (412) |
使用 (B) 进行写入 | 失败 (412) | 失败 (409) | 失败 (412) |
写入,未指定租约 | 可用,写入成功 | 失败 (412) | 可用,写入成功 |
使用 (A) 读取 | 失败 (412) | 租用 (A),读取成功 | 失败 (412) |
使用 (B) 读取 | 失败 (412) | 失败 (409) | 失败 (412) |
读取,未指定租约 | 可用,读取成功 | 租用 (A),读取成功 | 断开 (A),读取成功 |
按租约状态对文件的租约作结果
行动 | 可用 | 租用 (A) | 破碎 (A) |
---|---|---|---|
Acquire ,没有建议的租约 ID |
租用 (X) | 失败 (409) | 租用 (X) |
Acquire (A) |
租用 (A) | 租用 (A) | 租用 (A) |
Acquire (B) |
租用 (B) | 失败 (409) | 租用 (B) |
Break |
失败 (409) | 破碎 (A) | 破碎 (A) |
Change , (A) 到 (B) |
失败 (409) | 租用 (B) | 失败 (409) |
Change , (B) 到 (A) |
失败 (409) | 租用 (A) | 失败 (409) |
Change , (B) 到 (C) |
失败 (409) | 失败 (409) | 失败 (409) |
Release (A) |
失败 (409) | 可用 | 可用 |
Release (B) |
失败 (409) | 失败 (409) | 失败 (409) |
另请参阅
- 对文件 作
- 授权对 Azure 存储 的请求
- 状态和错误代码
- Azure 文件存储错误代码