租用共用
作業 Lease Share 會建立和管理 Azure 檔案共用或共用快照集上的鎖定。 此 API 完全受到支援，但它是舊版管理 API。 請改用 檔案共用 - 租用，由儲存體資源提供者提供， (Microsoft.Storage) 。 若要深入瞭解如何使用儲存體資源提供者以程式設計方式與 FileShare 資源互動，請參閱 FileShares 上的作業。
鎖定持續時間的範圍是 15 到 60 秒，也可以設為無限。 您可以在下列其中一種模式中呼叫 Lease Share 作業：
-
Acquire：要求新的租用。 -
Renew：若要更新現有的租用。 -
Change：若要變更現有租用的識別碼。 -
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 檔案儲存體會在檔案共用上建立租用，並傳回新的租用識別碼。 如果檔案共用有作用中的租用，您只能使用作用中的租用識別碼來要求新的租用。 不過，您可以針對永不過期的租用指定新的 x-ms-lease duration ，包括負數 (-1) 。renew：更新租用。 如果要求上指定的租用識別碼符合與檔案共用相關聯的租用識別碼，您可以更新租用。 請注意，即使租用已過期，您也可以更新租用，只要檔案共用自該租用到期後尚未再次租用即可。 當您更新租用時，租用持續時間的時鐘會重設。change：變更作用中租用的租用識別碼。
change必須包含 中的 x-ms-lease-id 目前租用識別碼，以及 中的新租用識別碼 x-ms-proposed-lease-id 。release：釋放租用。 如果要求上指定的租用識別碼符合與檔案共用相關聯的租用識別碼，您可以釋放租用。 釋放租用可讓另一個用戶端在發行完成後立即取得檔案共用的租用。break：如果檔案共用有作用中的租用，請中斷租用。 租用中斷之後，就無法更新。 任何授權的要求都可以中斷租用。 要求不需要指定相符的租用識別碼。 當租用中斷時，允許租用中斷期間經過，而且 breakrelease 是您目前在檔案共用上可執行檔唯一作業。 當租用成功中斷時，回應會指出可取得新租用之前的間隔秒數。已中斷的租用也可以釋放。 用戶端可以立即取得已發行的檔案共用租用。 |
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 。 建議的租用識別碼，使用 GUID 字串格式。 如果建議的租用識別碼格式不正確，Azure Blob 儲存體會傳回 400 (Invalid request) 。 如需有效格式的清單，請參閱 Guid 建構函式 (字串) 。 |
Origin |
選擇性。 指定發出要求的來源。 此標頭的顯示會導致在回應上跨原始資源共用 (CORS) 標頭。 如需詳細資訊 ，請參閱儲存體服務的 CORS 支援 。 |
x-ms-client-request-id |
選擇性。 提供用戶端產生的不透明值，其中包含 1-kibibyte (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 (OK)」。 -
Change：成功的作業會傳回狀態碼「200 (OK)」。 -
Release：成功的作業會傳回狀態碼「200 (OK)」。 -
Break：成功的作業會傳回狀態碼「202 (已接受)」。
如需狀態碼的相關資訊，請參閱 狀態和錯誤碼。
回應標頭
這項作業的回應包括下列標頭。 回應也可以包含額外的標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協定規格。
| 語法 | 描述 |
|---|---|
ETag |
ETag檔案共用的 。 |
Last-Modified |
傳回上次修改檔案共用的日期和時間。 如需詳細資訊，請參閱 標頭中的日期時間值表示。 修改檔案共用或其屬性或中繼資料的任何作業，都會更新上次修改的時間。 這包括設定檔案共用的許可權。 Blob 上的作業不會影響檔案共用的上次修改時間。 |
x-ms-lease-id: <id> |
當您要求租用時，Azure 檔案儲存體會傳回唯一的租用識別碼。 當租用作用中時，您必須包含租用識別碼，以及刪除檔案共用的任何要求，或更新、變更或釋放租用。 成功的更新作業也會傳回作用中租用的租用識別碼。 |
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
授權
只有帳戶擁有者可以呼叫這項作業。
備註
檔案共用上的租用提供檔案共用的獨佔刪除存取權。 在租用的檔案共用上取得檔案共用作業將會成功，而不包含租用識別碼。 設定檔案共用作業需要檔案共用租用識別碼。 如果設定檔案共用作業中未包含租用識別碼，作業會失敗，並出現 412 (前置條件失敗) 。 租用會在取得租用時所指定的持續時間授與租用，可以是 15 到 60 秒，或無限持續時間。
當用戶端取得租用時，會傳回租用識別碼。 如果取得要求中未指定租用識別碼，Azure 檔案儲存體會產生租用識別碼。 用戶端可以使用此租用識別碼來更新租用、變更其租用識別碼，或釋放租用。 下圖顯示租用的五個狀態，以及會導致租用狀態變更的命令或事件。
租用可以是上述任一狀態，取決於租用是鎖定還是解除鎖定，以及租用是否在該狀態中可更新。 上圖中顯示的租用動作會導致狀態轉換。
| 更新狀態 | 鎖定的租用 | 解除鎖定的租用 |
|---|---|---|
| 可更新租用 | 已租用 | 已過期 |
| 非可更新租用 | 中斷 | 中斷、可用 |
-
Available：租用已解除鎖定，並可取得。 允許的動作：acquire。 -
Leased：租用已鎖定。 允許的動作：acquire(僅限相同的租用識別碼)、renew、change、release和break。 -
Expired：租用持續時間到期。 允許的動作：acquire、renew、release和break。 -
Breaking，租用已中斷，但租用會繼續鎖定，直到中斷期間過期為止。 允許的動作：release和break。 -
Broken、租用已中斷，且中斷期間已過期。 允許的動作：acquire、release和break。
Azure 檔案儲存體在檔案共用租用過期之後維護租用識別碼。 用戶端可以使用過期的租用識別碼來更新或釋放租用。 如果用戶端嘗試使用其先前的租用識別碼來更新或釋放過期的租用，且要求失敗，這表示檔案共用自上次使用中的租用後再次租用或刪除。 如果租用到期，而不是明確釋放，用戶端可能需要等候最多一分鐘，才能取得檔案共用的新租用。 不過，用戶端可以立即以到期的租用識別碼更新租用。
呼叫 不會更新 Lease Share 檔案共用的 Last-Modified-Time 屬性。
下表顯示租用處於各種租用狀態時，在容器上執行動作的結果。 字母 (A) 、 (B) 和 (C) 代表租用識別碼，而 (X) 代表Azure 檔案儲存體所產生的租用識別碼。
依租用狀態在共用上使用嘗試的結果
| 動作 | 可用 | 已租用 (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：沒有建議的租用識別碼 |
已租用 (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) |