リース共有 (FileREST API) - Azure Files

[アーティクル]
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 をストレージアカウントの名前に置き換えます。

Method	要求 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 Files操作のタイムアウトの設定」を参照してください。

要求ヘッダー

必須要求ヘッダーと省略可能な要求ヘッダーを次の表に示します。

要求ヘッダー	説明
`Authorization`	必須。承認スキーム、アカウント名、署名を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`Date` または `x-ms-date`	必須。要求に対して協定世界時 (UTC) を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`x-ms-version`	省略可能。この要求に使用する操作のバージョンを指定します。詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
`x-ms-lease-id: <ID>`	リースを更新、変更、または解放する場合は必須です。の値は、任意の `x-ms-lease-id` 有効な GUID 文字列形式で指定できます。有効な形式の一覧については、「 Guid コンストラクター (String)」を参照してください。
`x-ms-lease-action: <action>`	`acquire`: 新しいリースを要求します。ファイル共有にアクティブなリースがない場合、Azure Filesはファイル共有にリースを作成し、新しいリース ID を返します。ファイル共有にアクティブなリースがある場合は、アクティブなリース ID を使用してのみ新しいリースを要求できます。ただし、無期限のリースに対して負の 1 (-1) を含む新しい `x-ms-lease duration`を指定できます。 `renew`: リースを更新します。要求で指定されたリース ID がファイル共有に関連付けられているリース ID と一致する場合は、リースを更新できます。リースが期限切れになった場合でも、そのリースの有効期限が切れてからファイル共有が再びリースされていない限り、リースを更新できることに注意してください。リースを更新すると、リース期間の時間がリセットされます。 `change`: アクティブなリースのリース ID を変更します。には`change`、現在のリース ID をに、新しいリース ID をに`x-ms-proposed-lease-idx-ms-lease-id`含める必要があります。 `release`: リースを解放します。要求で指定されたリース ID がファイル共有に関連付けられているリース ID と一致する場合は、リースを解放できます。リースを解放すると、リリースが完了するとすぐに、別のクライアントがファイル共有のリースをすぐに取得できます。 `break`: ファイル共有にアクティブなリースがある場合は、リースを中断します。リースが壊れた後は、更新できません。承認された要求は、リースを中断する可能性があります。要求は、一致するリース ID を指定する必要はありません。リースが切断されると、リース中断期間が経過することが許可され`breakrelease`、この期間中にファイル共有に対して実行できる操作は 1 つだけです。リースが正常に中断されると、応答で新しいリースを取得できるようになるまでの時間 (秒単位) が示されます。中断されたリースを解放することもできます。クライアントは、リリースされたファイル共有リースをすぐに取得できます。
`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 文字列形式の推奨リース ID。 Azure Blob Storageは、`400 (Invalid request)`提案されたリース ID が正しい形式でない場合にを返します。有効な形式の一覧については、「 Guid コンストラクター (String)」を参照してください。
`Origin`	省略可能。要求の送信元を指定します。このヘッダーが存在する場合、応答のクロスオリジンリソース共有 (CORS) ヘッダーになります。詳細については、「ストレージサービスの CORS サポート」を参照してください。
`x-ms-client-request-id`	省略可能。ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。詳細については、「Azure Filesの監視」を参照してください。

要求本文

なし。

要求のサンプル

次の要求例は、リースを取得する方法を示しています。

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 (Created) が返されます。
Renew: 操作が正常に終了すると、ステータスコード 200 (OK) が返されます。
Change: 操作が正常に終了すると、ステータスコード 200 (OK) が返されます。
Release: 操作が正常に終了すると、ステータスコード 200 (OK) が返されます。
Break: 操作が正常に終了すると、ステータスコード 202 (Accepted) が返されます。

状態コードの詳細については、「状態とエラーコード」を参照してください。

応答ヘッダー

この操作の応答には、次のヘッダーが含まれています。応答には、追加の標準 HTTP ヘッダーを含めることもできます。すべての標準ヘッダーは、HTTP/1.1 プロトコル仕様に準拠しています。

構文	説明
`ETag`	`ETag`ファイル共有の。
`Last-Modified`	ファイル共有が最後に変更された日時を返します。詳細については、「ヘッダー内の日時値の表現」を参照してください。ファイル共有またはそのプロパティまたはメタデータを変更する操作は、最終変更時刻を更新します。これには、ファイル共有のアクセス許可の設定が含まれます。 BLOB に対する操作は、ファイル共有の最終変更時刻には影響しません。
`x-ms-lease-id: <id>`	リースを要求すると、Azure Filesは一意のリース 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 が返されます。 Azure Filesは、取得要求でリース ID が指定されていない場合に、リース ID を生成します。クライアントはこのリース ID を使用して、リースの更新、リース ID の変更、またはリースの解放を行うことができます。次の図は、リースの 5 つの状態とリースの状態を変えるコマンドまたはイベントを示しています。

ファイル共有のリース状態と状態変更トリガーの図。

リースは、リースがロックされているかロック解除されているか、およびその状態でリースが更新可能かどうかに基づいて、これらの状態のいずれかに設定できます。前の図に示したリースアクションは、状態遷移を引き起こします。

更新の状態	ロックされたリース	ロック解除されたリース
再生可能なリース	Leased	有効期限切れ
更新不可能なリース	あり	Broken、Available

Available: リースはロック解除されており、リースを取得できます。許可されるアクション: acquire。
Leased: リースはロックされています。許可される操作: acquire (同じリース ID のみ)、renew、change、release、および break。
Expired: リース期間の有効期限が切れています。許可される操作: acquire、renew、release、および break。
Breakingの場合、リースは壊れていますが、中断期間が切れるまでリースはロックされ続けます。許可される操作: release および break。
Broken、リースが壊れ、中断期間が経過しました。許可される操作: acquire、release、および break。

Azure Filesは、ファイル共有リースの有効期限が切れた後もリース ID を保持します。クライアントは、期限切れのリース ID を使用してリースを更新または解放できます。クライアントが以前のリース ID で期限切れのリースを更新または解放しようとして、要求が失敗した場合は、リースが最後にアクティブになった後にファイル共有が再びリースされたか削除されたことを意味します。明示的に解放されるのではなくリースの有効期限が切れた場合、クライアントは最大 1 分待ってから、ファイル共有の新しいリースを取得できる場合があります。ただし、クライアントは、有効期限切れのリース ID でリースを直ちに更新できます。

ファイル共有の Last-Modified-Time プロパティは、の Lease Share呼び出しによって更新されません。

次の表は、さまざまなリース状態のリースが含まれるコンテナーにおけるアクションの結果を示しています。文字 (A)、(B)、および (C) はリース ID を表し、(X) はAzure Filesによって生成されたリース ID を表します。

リース状態別の共有に対する使用試行の結果

アクション	利用可能	Leased (A)	Breaking (A)	Broken (A)	Expired (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)、操作成功

リース状態別株式に対するリース操作の結果

アクション	利用可能	Leased (A)	Breaking (A)	Broken (A)	Expired (A)
`Acquire` (推奨リース ID なし)	Leased (X)	失敗 (409)	失敗 (409)	Leased (X)	Leased (X)
`Acquire` (A)	Leased (A)	Leased (A)、新しい期間	失敗 (409)	Leased (A)	Leased (A)
`Acquire` (B)	Leased (B)	失敗 (409)	失敗 (409)	Leased (B)	Leased (B)
`Break`、期間 = 0	失敗 (409)	Broken (A)	Broken (A)	Broken (A)	Broken (A)
`Break`、期間>0	失敗 (409)	Breaking (A)	Breaking (A)	Broken (A)	Broken (A)
`Change`、(A) から (B)	失敗 (409)	Leased (B)	失敗 (409)	失敗 (409)	失敗 (409)
`Change`、(B) から (A)	失敗 (409)	Leased (A)	失敗 (409)	失敗 (409)	失敗 (409)
`Change`、(B) から (C)	失敗 (409)	失敗 (409)	失敗 (409)	失敗 (409)	失敗 (409)
`Renew` (A)	失敗 (409)	Leased (A)、有効期限の時間のリセット	失敗 (409)	失敗 (409)	Leased (A)
`Renew` (B)	失敗 (409)	失敗 (409)	失敗 (409)	失敗 (409)	失敗 (409)
`Release` (A)	失敗 (409)	利用可能	利用可能	利用可能	利用可能
`Release` (B)	失敗 (409)	失敗 (409)	失敗 (409)	失敗 (409)	失敗 (409)
有効期限切れ	利用可能	Expired (A)	Broken (A)	Broken (A)	Expired (A)

リース共有