Lease Blob
この操作では Lease Blob
、書き込み操作と削除操作のための BLOB のロックを作成および管理します。 ロック期間は、15 ~ 60 秒にすることも、無限にすることもできます。 2012-02-12 より前のバージョンでは、ロック期間は 60 秒です。
重要
バージョン 2012-02-12 以降では、Lease Blob
操作の一部の動作が以前のバージョンとは異なります。 たとえば、以前のバージョンの Lease Blob
操作では、リースの解放後にリースを更新することができました。 バージョン 2012-02-12 以降では、このリース要求は失敗します。ただし、古いバージョンの Lease Blob
を使用した呼び出しは引き続き正常に実行されます。 この操作の動作の変更点については、「Changes to Lease Blob introduced in version 2012-02-12
」の「Remarks
」のセクションを参照してください。
Lease Blob
操作は、次の 5 つのモードのいずれかで呼び出すことができます。
Acquire
: 新しいリースを要求します。Renew
: 既存のリースを更新します。Change
: 既存のリースの ID を変更します。Release
: リースが不要になった場合に、別のクライアントがその BLOB に対するリースをすぐに取得できるようにリースを解放します。Break
。リースを終了しますが、現在のリース期間が終了するまで、別のクライアントが新しいリースを取得できないようにします。
Request
Lease Blob
要求の構成は次のとおりです。 HTTPS が推奨されます。 myaccount をストレージ アカウントの名前に置き換えます。
PUT メソッド要求の URI | HTTP バージョン |
---|---|
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=lease |
HTTP/1.1 |
エミュレートされたストレージ サービス URI
エミューレートされたストレージ サービスに対する要求では、エミュレーターのホスト名と BLOB Service ポートを 127.0.0.1:10000
と指定し、その後にエミューレートされたストレージ アカウント名を指定します。
PUT メソッド要求の URI | HTTP バージョン |
---|---|
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=lease |
HTTP/1.0 HTTP/1.1 |
詳細については、「開発とテストにAzure Storage Emulatorを使用する」を参照してください。
URI パラメーター
次の追加パラメーターを要求の URI で指定できます。
パラメーター | 説明 |
---|---|
timeout |
省略可能。 timeout パラメーターは、秒単位で表されます。 詳細については、「 Blob Service 操作のタイムアウトの設定」を参照してください。 |
要求ヘッダー
必須要求ヘッダーと省略可能な要求ヘッダーを次の表に示します。
要求ヘッダー | 説明 |
---|---|
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 文字列形式の一覧については、 Guid コンストラクター (文字列) を参照してください。 |
x-ms-lease-action: <acquire ¦ renew ¦ change ¦ release ¦ break> |
acquire : 新しいリースを要求します。 BLOB にアクティブなリースがない場合、BLOB サービスはその BLOB のリースを作成し、新しいリース ID を返します。 BLOB にアクティブなリースがある場合、新しいリースを要求するには、アクティブなリース ID を使用する必要があります。ただし、新しい x-ms-lease-duration を指定できます。たとえば、リースを無期限にする場合は -1 を指定します。renew : リースを更新します。 要求で指定したリース ID が BLOB に関連付けられているリース ID と一致する場合、リースを更新できます。 リースの有効期限が切れていても、そのリースの期限切れ以降に BLOB が変更されたり、再度リースされたりしていなければ、リースを更新できます。 リースを更新すると、リース期間の時間がリセットされます。change : バージョン 2012-02-12 以降。 アクティブなリースのリース ID を変更します。 change には、x-ms-lease-id の現在のリース ID と x-ms-proposed-lease-id の新しいリース ID を含める必要があります。release : リースを解放します。 要求で指定したリース ID が BLOB に関連付けられているリース ID と一致する場合、リースを解放できます。 リースを解放すると、解放が完了した直後から、別のクライアントがその BLOB のリースを取得できるようになります。break : BLOB にアクティブなリースがある場合、そのリースを中断します。 いったん中断したリースは更新できません。 承認済みの要求によってリースを中断できます。要求で一致するリース ID を指定する必要はありません。 リースを中断した場合、リース中断期間はそのまま経過します。その間、その BLOB に対して break と release 以外のリース操作は実行できません。 リースが正常に中断されると、応答で新しいリースを取得できるようになるまでの時間 (秒単位) が示されます。中断されたリースを解放することもできます。この場合、別のクライアントがその BLOB のリースをすぐに取得できます。 |
x-ms-lease-break-period: N |
省略可能。 バージョン 2012-02-12 以降。 break 操作の場合、これはリースを中断するまでのリース保持推奨期間 (0 ~ 60 秒) です。 この中断期間は、リースの残り時間よりも短い場合にのみ使用されます。 長い場合は、リースの残り時間が使用されます。 中断期間が終了するまで新しいリースは使用できなくなりますが、中断期間よりも長い期間リースが保持される場合があります。 break 操作でこのヘッダーが含まれていない場合、固定期間のリースは残りのリース期間が経過してから中断され、無限リースは即座に中断されます。 |
x-ms-lease-duration: -1 ¦ n seconds |
バージョン 2012-02-12 以降。 操作に対してのみ許可され、必須 acquire です。 リース期間 (秒単位) を指定します。無期限のリースには -1 を指定します。 無限リースでない場合は、15 ~ 60 秒を指定できます。 renew または change を使用して、リース期間を変更することはできません。 |
x-ms-proposed-lease-id: <ID> |
バージョン 2012-02-12 以降。 acquire の場合は省略可能。change の場合は必須。 GUID 文字列形式の推奨リース ID。 推奨リース ID が正しい形式ではない場合、BLOB サービスから 400 (Invalid request) が返されます。 有効な GUID 文字列形式の一覧については、 Guid コンストラクター (文字列) を参照してください。 |
Origin |
省略可能。 要求の送信元を指定します。 このヘッダーが存在する場合、応答のクロス オリジン リソース共有ヘッダーになります。 詳細については、Storage サービスの CORS サポートを参照してください。 |
x-ms-client-request-id |
省略可能。 ストレージ分析ログが有効になっているときに分析ログに記録される 1 KiB 文字制限を持つ、クライアントによって生成された不透明な値を提供します。 クライアント側のアクティビティをサーバーが受信した要求と関連付けるには、このヘッダーを使用することが強く推奨されます。 詳細については、「Storage Analyticsログと Azure ログ: ログを使用したStorage要求の追跡」を参照してください。 |
この操作では、条件ヘッダーを使用して、指定した条件を満たした場合にのみ操作を実行することもできます。 詳細については、「BLOB サービス操作の条件ヘッダーの指定」を参照してください。
要求本文
[なし] :
要求のサンプル
次の要求例は、リースを取得する方法を示しています。
Request Syntax:
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=lease HTTP/1.1
Request Headers:
x-ms-version: 2015-02-21
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=
応答
応答には、HTTP 状態コードおよび一連の応答ヘッダーが含まれています。
状態コード
リース操作に対して返される成功ステータス コードは次のとおりです。
Acquire
: 操作が正常に終了すると、ステータス コード 201 (Created) が返されます。Renew
: 操作が正常に終了すると、ステータス コード 200 (OK) が返されます。Change
: 操作が正常に終了すると、ステータス コード 200 (OK) が返されます。Release
: 操作が正常に終了すると、ステータス コード 200 (OK) が返されます。Break
: 操作が正常に終了すると、ステータス コード 202 (Accepted) が返されます。
状態コードの詳細については、「 状態とエラー コード」を参照してください。
レスポンス ヘッダー
この操作の応答には、次のヘッダーが含まれています。 応答に追加の標準 HTTP ヘッダーが含まれる場合もあります。 すべての標準ヘッダーは 、HTTP/1.1 プロトコル仕様に準拠しています。
構文 | 説明 |
---|---|
ETag |
ETag ヘッダーには、条件に基づく操作の実行に使用できる値が含まれます。 詳細については、「 BLOB サービス操作の条件付きヘッダーの指定 」を参照してください。このヘッダーは、バージョン 2013-08-15 以降に対する要求に対して返されます。ETag の値は引用符で囲まれます。 Lease Blob 操作は、このプロパティを変更しません。 |
Last-Modified |
BLOB が最後に更新された日時。 日付形式は RFC 1123 に従います。 詳細については、「 ヘッダーのDate-Time値の表現」を参照してください。 BLOB の書き込み操作 (BLOB のメタデータやプロパティの更新など) を行うと、BLOB の最終更新時刻が変更されます。 Lease Blob 操作は、このプロパティを変更しません。 |
x-ms-lease-id: <id> |
リースを要求すると、BLOB サービスから一意のリース ID が返されます。 リースがアクティブである間は、BLOB への書き込みや、リースの更新、変更、解放を実行するためのすべての要求にリース ID を含める必要があります。 更新操作が正常に行われた場合も、アクティブなリースのリース ID が返されます。 |
x-ms-lease-time: seconds |
リース期間のおおよその残り時間 (秒単位)。 このヘッダーは、リース中断要求が正常に処理された場合にのみ返されます。 即時中断の場合は 0 が返されます。 |
x-ms-request-id |
このヘッダーは要求を一意に識別するので、要求のトラブルシューティングに使用できます。 詳細については、「 API 操作のトラブルシューティング」を参照してください。 |
x-ms-version |
要求の実行に使用する BLOB サービスのバージョンを示します。 このヘッダーはバージョン 2009-09-19 以降で行った要求に対して返されます。 |
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 が最大 1024 文字の ASCII 文字で表示される場合、ヘッダーの値と同じです。 ヘッダーが x-ms-client-request-id 要求に存在しない場合、このヘッダーは応答に存在しません。 |
応答本文
[なし] :
応答のサンプル
次に示すのは、リース取得要求に対する応答の例です。
Response Status:
HTTP/1.1 201 Created
Response Headers:
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402
x-ms-version: 2015-02-21
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5
Date: <date>
承認
この操作は、アカウント所有者と、この BLOB またはそのコンテナーに対する書き込みアクセス許可がある共有アクセス署名を持つ任意のクライアントが呼び出すことができます。
解説
BLOB のリースによって、BLOB への書き込みアクセスと削除アクセスが排他的になります。 アクティブなリースのある BLOB に書き込むには、クライアントはアクティブなリースの ID を書き込み要求に含める必要があります。 リース期間は、リースの取得時に 15 秒~ 1 分の範囲内で指定できます。また、期間を無限にすることもできます。
クライアントがリースを取得すると、リース ID が返されます。 取得要求でリース ID が指定されていない場合、BLOB サービスはリース ID を生成します。 クライアントは、このリース ID を使用して、リースの更新、リース ID の変更、またはリースの解放を実行できます。
リースがアクティブのときは、以下の操作を行うためには要求にリース ID を含める必要があります。
BLOB のコピー (宛先 BLOB に必要なリース ID)
リース ID が含まれていない場合、リースされている BLOB に対するこれらの操作は 412 – Precondition failed
が返されて失敗します。
リースされた BLOB に対する次の操作は、リース ID を含めなくても正常に実行されます。
BLOB のコピー (ソース BLOB にはリース ID は必要ありません)。
リース BLOB (REST API) (リース ID は必要
x-ms-lease-action: break
ありません。)
アクティブなリースのある BLOB での GET 操作には、リース ID を含める必要はありません。 ただし、すべての GET 操作は条件付きリース パラメーターをサポートしており、要求に含まれるリース ID が有効な場合にのみ操作が続行されます。
コンテナーの削除など、アクティブなリースを持つ BLOB を含むコンテナーでは、すべての コンテナー操作が許可されます。 したがって、アクティブなリースのある BLOB が含まれている場合であっても、コンテナーが削除される場合があります。 コンテナーの リース 操作を使用して、コンテナーを削除する権限を制御します。
次の図は、リースの 5 つの状態とリースの状態を変えるコマンドまたはイベントを示しています。
リースの状態
リースがロックされているかまたはロック解除されているか、また、その状態でリースを更新できるかどうかによって、リースには 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
。
リースの有効期限が切れると、BLOB が変更されるか再度リースされるまで、リース ID は BLOB サービスによって保持されます。 クライアントは、期限切れになったリース ID を使用して、リースの更新または解放を試みることができます。操作が正常に実行された場合は、そのリース ID が最後に有効であった時点以降に BLOB が変更されていないことがわかります。
クライアントが以前のリース ID でリースの更新または解放を試みたときに要求が失敗した場合は、リースが最後にアクティブであった時点以降に BLOB が変更されたか再度リースされたことがわかります。 その場合、クライアントは BLOB に対する新しいリースを要求する必要があります。
リースを明示的に解放するのではなく、期限切れにした場合、クライアントはその BLOB に対する新しいリースを取得する前に、最大 1 分間だけ待つことが必要になる場合があります。 ただし、BLOB が変更されていない場合、クライアントは以前のリース ID でリースをすぐに更新できます。
スナップショットは読み取り専用なので、BLOB のスナップショットに対してはリースを取得できません。 スナップショットに対するリースを要求すると、ステータス コード 400 (Bad Request) が返されます。
BLOB の Last-Modified-Time
プロパティは、Lease Blob
を呼び出しても更新されません。
次の表は、さまざまなリース状態のリースを保持する BLOB に対する操作の結果を示しています。 文字 (A)、(B)、(C) はリース ID を表し、(X) は BLOB サービスによって生成されたリース ID を表します。
BLOB におけるリース状態別使用試行の結果
アクション | 利用可能 | Leased (A) | Breaking (A) | Broken (A) | Expired (A) |
---|---|---|---|---|---|
(A) を使用した書き込み | 失敗 (412) | Leased (A)、書き込み成功 | Breaking (A)、書き込み成功 | 失敗 (412) | 失敗 (412) |
(B) を使用した書き込み | 失敗 (412) | 失敗 (409) | 失敗 (412) | 失敗 (412) | 失敗 (412) |
書き込み (リースの指定なし) | Available、書き込み成功 | 失敗 (412) | 失敗 (412) | Available、書き込み成功 | Available、書き込み成功 |
(A) を使用した読み取り | 失敗 (412) | Leased (A)、読み取り成功 | Breaking (A)、読み取り成功 | 失敗 (412) | 失敗 (412) |
(B) を使用した読み取り | 失敗 (412) | 失敗 (409) | 失敗 (409) | 失敗 (412) | 失敗 (412) |
読み取り (リースの指定なし) | Available、読み取り成功 | Leased (A)、読み取り成功 | Breaking (A)、読み取り成功 | Broken (A)、読み取り成功 | Expired (A)、読み取り成功 |
BLOB におけるリース状態別リース操作の結果
アクション | 利用可能 | 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) (BLOB が変更されなかった場合)。 失敗 (409) (BLOB が変更された場合)。 |
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) |
Changes to Lease Blob introduced in version 2012-02-12
バージョン 2012-02-12 で導入された Lease Blob の動作の変更点を以下に示します。
リースを取得するための Lease Blob の呼び出しには、リース期間ヘッダーを含める必要があります。 リース期間を指定せずにリースを取得しようとすると、
400 Bad Request – Missing required header
が返されて操作は失敗します。リースを解放すると、リースを更新できなくなります。 リースを更新しようとすると、
409 Conflict – The lease ID specified did not match the lease ID for the blob
が返されて操作は失敗します。 release を呼び出した後に renew を呼び出したアプリケーションは、release 呼び出しの ETag を保存してから、If-Match
条件ヘッダーを指定した acquire を呼び出して、BLOB が変更されていない場合にのみリースを取得する必要があります。リースを解放すると、リースを中断できなくなります。 中断しようとすると、
409 Conflict – There is currently no lease on the blob
が返されて操作は失敗します。中断操作をべき等操作 (何回実行しても結果が変わらない操作) にすることで、Breaking または Broken 状態のリースを中断できるようになりました。 以前のバージョンでは、この操作は
409 Conflict – The lease has already been broken and cannot be broken again
が返されて失敗していました。 この変更により、中断期間を短縮できるようになります。 Breaking 状態のリースを中断し、残りの中断期間より短い期間を含めた場合、その短い方の期間が使用されます。
関連項目
BLOB の新しいリース機能: 無限リース、短期間のリースなど
Azure Storageへの要求を承認する
ステータス コードとエラー コード
BLOB サービスのエラー コード
Lease Container