リース ファイル

  • [アーティクル]

この操作では Lease File 、書き込み操作と削除操作に対するファイルのロックを作成および管理します。 Lease File はバージョン 2019-02-02 以降でサポートされています。

操作は Lease File 、次のいずれかのモードで呼び出すことができます。

  • Acquire: 新しいリースを要求します。
  • Change: 既存のリースの ID を変更します。
  • Releaseは、不要になった場合にリースを解放し、別のクライアントがファイルに対するリースをすぐに取得できるようにします。
  • Breakは、リースを強制的に終了しますが、現在のリース期間が切れるまで別のクライアントが新しいリースを取得できないようにします。

プロトコルの可用性

有効なファイル共有プロトコル 使用可能
SMB はい
NFS いいえ

要求

要求は Lease File 次のように構築できます。 HTTPS が推奨されます。

Method 要求 URI HTTP バージョン
Put https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease HTTP/1.1

次のように、要求 URI に示されたパス コンポーネントを独自の URI に置き換えます。

パス コンポーネント 説明
myaccount ご利用のストレージ アカウントの名前。
myshare ファイル共有の名前。
mydirectorypath 省略可能。 ディレクトリへのパス。
myfile ファイルの名前です。

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: <acquire ¦ change ¦ release ¦ break> acquire: 新しいリースを要求します。 ファイルにアクティブなリースがない場合、Azure Filesはファイルにリースを作成し、新しいリース ID を返します。 ファイルにアクティブなリースがある場合は、アクティブなリース ID を使用してのみ新しいリースを要求できます。

change: アクティブなリースのリース ID を変更します。 には change 、現在のリース ID を に x-ms-lease-id、新しいリース ID を に x-ms-proposed-lease-id含める必要があります。

release: リースを解放します。 要求で指定されたリース ID がファイルに関連付けられているリース ID と一致する場合は、リースを解放できます。 リースを解放すると、リリースが完了するとすぐに、別のクライアントがファイルのリースをすぐに取得できます。

break: ファイルにアクティブなリースがある場合は、リースを中断します。 承認された要求は、リースを中断する可能性があります。 要求は、一致するリース ID を指定するために必要ありません。 無限リースはすぐに解除されます。
x-ms-lease-duration: -1 操作でのみ acquire 許可され、必須です。 -1有効期限が切れないリースを示すには、 を にする必要があります。
x-ms-proposed-lease-id: <ID> の場合 acquireは省略可能、の場合 changeは必須です。 GUID 文字列形式の推奨リース ID。 提案されたリース ID が正しい形式でない場合、Azure Files は を返400 (Invalid request)します。 有効な形式の一覧については、「 Guid コンストラクター (String)」 を参照してください。
x-ms-client-request-id 省略可能。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「Azure Filesの監視」を参照してください。
x-ms-file-request-intent ヘッダーが OAuth トークンを指定する場合 Authorization は必須。 許容される値は です backup。 このヘッダーは、 ヘッダーをMicrosoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action使用してAuthorization承認された ID に割り当てられた 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 testaccount1:esSKMOYdK4o+nGTuTyeOLBI+xqnqi6aBmiW4XI699+o=

Response

応答には、HTTP 状態コードおよび一連の応答ヘッダーが含まれています。

status code

リース操作に対して返される成功ステータス コードは次のとおりです。

  • Acquire: 操作が正常に終了すると、ステータス コード 201 (Created) が返されます。
  • Change: 操作が正常に終了すると、ステータス コード 200 (OK) が返されます。
  • Release: 操作が正常に終了すると、ステータス コード 200 (OK) が返されます。
  • Break: 操作が正常に終了すると、ステータス コード 202 (Accepted) が返されます。

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

応答ヘッダー

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

構文 説明
ETag 条件付きで操作を実行するために使用できる値を引用符で囲んで格納します。 Lease Fileこの操作では、このプロパティは変更されません。
Last-Modified ファイルが最後に更新された日時。 詳細については、「 ヘッダーでの日時値の表現」を参照してください。

ファイルに対する書き込み操作 (ファイルのメタデータまたはプロパティの更新を含む) は、ファイルの最終変更時刻を変更します。 Lease Fileこの操作では、このプロパティは変更されません。
x-ms-lease-id: <id> リースを要求すると、Azure Filesは一意のリース ID を返します。 リースがアクティブな間は、リース ID をファイルに書き込むか、リースを変更または解放する要求を含める必要があります。

更新操作が正常に行われた場合も、アクティブなリースのリース ID が返されます。
x-ms-lease-time: seconds リースを解除する要求が成功した場合にのみ返されます。 0 は、直ちに中断するために返されます。
x-ms-request-id 行われた要求を一意に識別し、要求のトラブルシューティングに使用できます。 詳細については、「 API 操作のトラブルシューティング」を参照してください。
x-ms-version 要求の実行に使用Azure Filesのバージョンを示します。
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 Filesはリース ID を生成します。 クライアントは、このリース ID を使用してリース ID を変更したり、リースを解放することができます。

リースがアクティブのときは、以下の操作を行うためには要求にリース ID を含める必要があります。

リース ID が含まれていない場合、これらの操作は、 を使用して、リースされたファイルで 412 – Precondition failed失敗します。

リース ID を含めずに、リースされたファイルに対して次の操作が成功します。

アクティブなリースを持つファイルに対する操作の GET リース ID を含める必要はありません。 ただし、すべての GET 操作で条件付きリース パラメーターがサポートされます。 この型のパラメーターでは、要求に含まれるリース ID が有効な場合にのみ操作が続行されます。

共有の削除など、アクティブなリースを持つファイルを含む共有では、すべての 共有操作が許可されます。 そのため、共有内のファイルにアクティブなリースがある場合でも、共有を削除できます。

リースの状態

次の図は、リースの 3 つの状態と、リース状態の変更を引き起こすコマンドまたはイベントを示しています。

ファイル リースの状態と状態変更トリガーを示す図。

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

  • Available: リースはロック解除され、取得できます。 許可されるアクション: acquire。
  • Leased: リースがロックされています。 許可されるアクション: acquire (同じリース ID のみ) change、、、 releaseおよび break。
  • Broken: リースが壊れています。 許可される操作: acquire、release、および break。

スナップショットは読み取り専用であるため、共有スナップショット内のファイルにリースを付与できないことに注意してください。 共有スナップショットのファイルに対してリースを要求すると、状態コード 400 (無効な要求) になります。

ファイルリースが 破損 状態で、Put Range 操作がファイルに書き込む場合、リース状態は [利用可能] に変わります。 ただし、ファイルに読み取り専用属性が設定されている場合、サーバーは競合 409 を返します。

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

次の表は、さまざまなリース状態のリースを持つファイルに対するアクションの結果を示しています。 文字 (A)、(B)、および (C) はリース ID を表し、(X) はAzure Filesによって生成されたリース ID を表します。

リース状態別のファイルでの使用試行の結果

アクション 使用可能 Leased (A) Broken (A)
(A) を使用して書き込む 失敗 (412) Leased (A)、書き込み成功 失敗 (412)
を使用した書き込み (B) 失敗 (412) 失敗 (409) 失敗 (412)
書き込み (リースの指定なし) Available、書き込み成功 失敗 (412) Available、書き込み成功
(A) を使用して読み取る 失敗 (412) Leased (A)、読み取り成功 失敗 (412)
を使用して読み取る (B) 失敗 (412) 失敗 (409) 失敗 (412)
読み取り (リースの指定なし) Available、読み取り成功 Leased (A)、読み取り成功 Broken (A)、読み取り成功

リース状態別のファイルに対するリース操作の結果

アクション 使用可能 Leased (A) Broken (A)
Acquire (推奨リース ID なし) Leased (X) 失敗 (409) Leased (X)
Acquire (A) Leased (A) Leased (A) Leased (A)
Acquire (B) Leased (B) 失敗 (409) Leased (B)
Break 失敗 (409) Broken (A) Broken (A)
Change、(A) から (B) 失敗 (409) Leased (B) 失敗 (409)
Change、(B) から (A) 失敗 (409) Leased (A) 失敗 (409)
Change、(B) から (C) 失敗 (409) 失敗 (409) 失敗 (409)
Release (A) 失敗 (409) 利用可能 利用可能
Release (B) 失敗 (409) 失敗 (409) 失敗 (409)

こちらもご覧ください