租用檔案
Lease File 作業會建立和管理檔案的鎖定，以進行寫入和刪除作業。 2019-02-02 版和更新版本支援 Lease File。
您可以使用下列其中一種模式呼叫 Lease File 作業：
-
Acquire，要求新的租用。 -
Change，以變更現有租用的標識符。 -
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 建構函式 （String）。 |
x-ms-lease-action: <acquire ¦ change ¦ release ¦ break> |
acquire：要求新的租用。 如果檔案沒有作用中的租用，Azure 檔案會在檔案上建立租用，並傳回新的租用標識符。 如果檔案具有作用中的租用，您只能使用使用中租用標識符來要求新的租用。change：變更使用中租用的租用標識符。
change 必須在 x-ms-lease-id中包含目前的租用標識碼，並在 x-ms-proposed-lease-id中包含新的租用標識符。release：釋放租用。 如果要求上指定的租用標識符符合與檔案相關聯的租用標識碼，您可以釋放租用。 發行租用可讓另一個用戶端在發行完成後立即取得檔案的租用。break：如果檔案具有作用中的租用，則會中斷租用。 任何授權的要求都可以中斷租用。 不需要要求來指定相符的租用標識碼。 無限租用會立即中斷。 |
x-ms-lease-duration: -1 |
只有在 acquire 作業上才允許和必要。 必須 -1，才能指出永不過期的租用。 |
x-ms-proposed-lease-id: <ID> |
選擇性 acquire，change為 必要專案。 建議的租用標識碼，格式為 GUID 字串。 如果建議的租用標識符格式不正確，Azure 檔案服務會傳回 400 (Invalid request)。 如需有效格式的清單，請參閱 Guid 建構函式 （String）。 |
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 標頭授權的身分識別中，則此標頭指定應授與 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 或 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 檔案服務會傳回唯一的租用標識符。 當租用為使用中時，您必須將租用標識碼包含在任何要求中以寫入檔案，或變更或釋放租用。 成功的更新作業也會傳回使用中租用的租用標識符。 |
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>
授權
只有帳戶擁有者可以呼叫這項作業。
言論
檔案上的租用提供檔案的獨佔寫入和刪除存取權。 若要寫入具有使用中租用的檔案，客戶端必須包含具有寫入要求的作用中租用標識碼。 租用會獲得無限持續時間。
當用戶端取得租用時，會傳回租用標識符。 如果未在取得要求中指定租用標識符，Azure 檔案服務就會產生租用標識符。 用戶端可以使用此租用標識符來變更其租用標識碼或釋放租用。
當租用為使用中時，租用標識碼必須包含在下列任何作業的要求中：
如果未包含租用識別碼，則租用檔案上的這些作業會失敗，412 – Precondition failed。
下列作業在租用的檔案上成功，但不包含租用標識碼：
- 取得檔案
- 取得檔案元數據
- 取得檔案屬性
- 清單範圍
- 清單目錄和檔案
- 複製檔案 （來源檔案不需要租用標識符。）
-
租用檔案 （REST API） （
x-ms-lease-action: break不需要租用標識符。
在具有作用中租用的檔案上，不需要包含 GET 作業的租用標識碼。 不過，所有 GET 作業都支持條件式租用參數。 在此類型的參數中，只有在要求隨附的租用標識符有效時，才會繼續作業。
共用上允許所有共享作業，其中包含具有使用中租用的檔案，包括 刪除共用。 因此，即使其內的檔案有作用中租用，您也可以刪除共用。
租用狀態
下圖顯示租用的三種狀態，以及導致租用狀態變更的命令或事件。
租用可以有三種狀態，根據租用是否已鎖定或解除鎖定，以及租用是否在該狀態下可更新。 上圖中顯示的租用動作會導致狀態轉換。
-
Available：租用已解除鎖定，而且可以取得。 允許的動作：acquire。 -
Leased：租用已鎖定。 允許的動作：acquire（僅限相同的租用識別元）、change、release和break。 -
Broken：租用已中斷。 允許的動作：acquire、release與break。
請注意，共用快照集中的檔案無法授與租用，因為快照集是唯讀的。 針對共用快照集中的檔案要求租用會導致狀態代碼 400 （不正確的要求）。
如果檔案租用處於 中斷 狀態，而 Put Range 作業會寫入檔案，租用狀態會變更為 Available。 不過，如果檔案已設定只讀屬性，伺服器將會傳回衝突 409。
呼叫 Lease File時，不會更新檔案的 Last-Modified-Time 屬性。
下表顯示具有各種租用狀態之檔案上動作的結果。 字母 （A）、（B） 和 （C） 代表租用標識碼，而 （X） 則代表 Azure 檔案服務所產生的租用識別符。
依租用狀態嘗試檔案的結果
| 行動 | 可用 | 租用 （A） | 破碎 （A） |
|---|---|---|---|
| 使用 （A） 撰寫 | 失敗 （412） | 租用 （A）， 寫入成功 | 失敗 （412） |
| 使用 撰寫 （B） | 失敗 （412） | 失敗 （409） | 失敗 （412） |
| 寫入，未指定租用 | 可用，寫入成功 | 失敗 （412） | 可用，寫入成功 |
| 使用 讀取 （A） | 失敗 （412） | 租用 （A）， 讀取成功 | 失敗 （412） |
| 使用 讀取 （B） | 失敗 （412） | 失敗 （409） | 失敗 （412） |
| 讀取，未指定租用 | 可用、讀取成功 | 租用 （A）， 讀取成功 | 中斷 （A）， 讀取成功 |
依租用狀態對檔案進行租用作業的結果
| 行動 | 可用 | 租用 （A） | 破碎 （A） |
|---|---|---|---|
Acquire，沒有建議的租用標識符 |
租用 （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） |