条件付きリクエストの使用
ベータ版
この機能はプレビュー版です。使用するには、ワークスペース管理者は プレビューページ から 大規模ファイルuploadをサポートするFiles API V3 を有効にする必要があります。Databricks のプレビューを管理を参照してください。
条件付きリクエストを使用すると、対象ファイルの現在の状態に応じて操作を実行できます。そのため、ファイルが想定した状態にある場合にのみリクエストが反映されます。これにより、無駄な転送を避け、並列書き込みによる更新の消失を防ぎ、ファイルを安全に作成または削除できます。
Files API 3.0 は、RFC 9110 の4つの標準 HTTP 条件付きヘッダーをサポートしています。
Header | 比較対象と比較 | 表彰された日 |
|---|---|---|
| ファイルの | 読み取り、書き込み、削除を行います |
| ファイルの | 読み取りと書き込み |
| ファイルの | 読み取りのみを行います |
| ファイルの | 読み取りのみを行います |
If-Modified-Since およびIf-Unmodified-Sinceは、読み取り操作（GETおよびHEAD）にのみ適用されます。これらは、uploadまたは削除ではサポートされていません。
条件が満たされない場合、サーバーは操作を実行せず、次のいずれかのステータスを返します。
304 Not Modified、GETまたはHEAD要求がIf-None-MatchまたはIf-Modified-Sinceで失敗した場合。これにより、キャッシュされたコピーがまだ有効であることが確認されるため、ファイルを再送信する必要はありません。412 Precondition Failed、他の条件のいずれかが失敗した場合。読み取り、upload、または削除は実行されません。
バリデーター：ETagとLast-Modified
条件付き要求は、提供された バリデーター とファイルの現在のバリデーターを比較します。Files APIは両方のバリデーターを応答ヘッダーとして返すため、それらをキャプチャして後の要求で使用できます。
ETag: ファイルの現在のコンテンツの不透明な識別子。サーバーが返した正確な値（周囲の引用符を含む）を保存し、変更せずに送信し返します。解析や構築は行わないでください。Last-Modified：HTTP日時としてのファイルの最終変更時刻。
両方のバリデーターは、GETとHEADの応答で返されます。ETagはPUTおよびマルチパートcomplete-upload応答でも返されます。
Last-Modified の精度は1秒です。If-Modified-Since と If-Unmodified-Since は、同じ秒内に作成されたいくつかの変更を検出できないため、正確な同時並列制御には信頼しないでください。代わりに、If-Match または If-None-Match で ETag を使用してください。
条件付き読み取り
GET と HEAD では、4 つの条件付きヘッダーすべてが適用されます。最も一般的な使用方法は キャッシュの再検証 であり、以前にdownloadしたコピーがあり、変更された場合にのみサーバーにバイトを再送信させたい場合に使用します。
キャッシュされたコピーのETagとともにIf-None-Matchを送信するか、最後に取得した時刻とともにIf-Modified-Sinceを送信します。ファイルが変更されていない場合、サーバーは本文なしで304 Not Modifiedを返します。ユーザーはキャッシュされたコピーを使い続けます。変更されている場合、サーバーは新しいコンテンツとともに200 OKを返します。
キャッシュされたファイルを再検証するには、その ETag を送信し、ファイルが変更された場合にのみ download します。
GET /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
304 Not Modified
他の2つの読み取りヘッダーは、逆の条件をアサートします。If-Match は、その ETag がまだ一致する場合にのみファイルを返し、それ以外の場合は 412 を返します。If-Unmodified-Since は、指定された時刻からファイルが変更されていない場合にのみファイルを返し、それ以外の場合は 412 を返します。
読み取り時に送信できる条件付きヘッダーは最大2つです。それ以上のリクエストはサポートされていません。2つ送信すると、優先順位は RFC 9110 に従います。
条件付き書き込み
PUT では、 If-None-Match と If-Match を使用して、ファイルの現在の状態に対してuploadを保護できます。
If-None-Match: *ファイルが存在しない場合のみ、ファイルを保存します。これにより、uploadが他のuploadを誤って上書きしてデータが失われないことが保証されます。これは更新消失問題のバリエーションです。そのパスにファイルが既に存在する場合、リクエストは412 Precondition Failedを返します。If-Match: <etag>更新の損失の問題を回避します。upload は、ファイルをフェッチした後に別の変更がファイルに対して行われていないことをチェックします。uploadが成功するのは、ファイルの現在のETagが指定したものと一致する場合のみです。それ以外の場合、リクエストは412 Precondition Failedを返します。パスにファイルが存在しない場合、リクエストは404を返します。
ファイルが存在しない場合にのみファイルを作成するには、If-None-Match: *を送信します。
PUT /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-None-Match: *
Content-Type: application/octet-stream
<binary data>
200 OK
最後に取得したバージョンである場合にのみファイルを上書きするには、ETagとIf-Matchを送信します。
PUT /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Content-Type: application/octet-stream
<binary data>
200 OK
PUTでは、 ETagのリスト、 If-Match: *、特定の ETag、 If-Modified-Since、および If-Unmodified-Sinceを持つ If-None-Matchの形式はサポートされていません。
マルチパートuploadの場合は、initiate-upload呼び出しで条件付きヘッダーを送信します。Files APIはそれを格納し、uploadが完了したときに評価するため、条件は最終的にアセンブルされたファイルに適用されます。PUTと同じ2つのヘッダー（If-None-Match: *とIf-Match: <etag>）を使用できます。complete-upload呼び出しまたはabort-upload呼び出し自体の条件付きヘッダーはサポートされていません。
条件付き削除
DELETE はべき等です。存在しないファイルを削除しても、204 No Contentが返されます。これによりクリーンアップが簡単になりますが、単純なDELETEでは意図したバージョンを削除したかどうかを判断できません。削除を条件付きにするには、If-Matchを送信します。
If-Match: <etag>現在のETagが提供した内容と一致する場合のみ、ファイルを削除します。ファイルをフェッチした後に他のユーザーがそのファイルを変更した場合、要求は変更を削除する代わりに412 Precondition Failedを返します。ファイルがもう存在しない場合、リクエストは404を返します。If-Match: *ファイルが存在する場合にのみファイルを削除します。このリクエストは、ファイルが存在していた場合は204を返し、存在しなかった場合は404を返します。
DELETE /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
204 No Content
残りの条件付きヘッダー（If-None-Match、If-Modified-Since、および If-Unmodified-Since）は、DELETEではサポートされていません。