Unity CatalogボリュームでFiles APIを使用する
Files API を使用して、パス別にファイルとディレクトリを読み取り、書き込み、一覧表示、削除します。Unity Catalog ボリューム内のファイルで動作します。これらは、/Volumes/<catalog>/<schema>/<volume>/<path> のような絶対ボリュームパスで参照します。Files API 3.0 リクエストは、/api/3.0/fs Endpoint プレフィックスを使用し、ワークスペースの リージョンホスト名に送信されます。すべての操作、パラメーター、およびヘッダーについては、「Files API 3.0リファレンス」を参照してください。
Files APIを使用すると、Databricksのデータ転送料金が発生する場合があります。
リージョンのホスト名にリクエストを送信する
ベータ版
この機能はベータ版です。使用するには、ワークスペース管理者は プレビューページ から Files API V3 with Large File Upload Support を有効にする必要があります。Databricksのプレビューを管理するを参照してください。
リクエストユーザーが属するワークスペースのリージョンホスト名に Files API 3.0 リクエストを送信します。リージョンホスト名の形式は次のとおりです。
<workspace-id>.storage.<workspace-region>.<databricks-domain>
たとえば、 1234567890123456.storage.us-west-2.cloud.databricks.com。
ワークスペースIDとリージョンを見つけるには、アカウントコンソールを使用します。「ワークスペースインスタンス名、URL、およびID」を参照してください。デプロイメントURLでワークスペースIDを見つけることもできます。https://<databricks-instance>/?o=1234567890123456では、o=の後の数字がワークスペースIDです。ワークスペースUIには、ワークスペース名の下にリージョンが表示されます。
ネットワーク接続を構成する
ベータ版
この機能はベータ版です。使用するには、ワークスペース管理者は プレビューページ から Files API V3 with Large File Upload Support を有効にする必要があります。Databricksのプレビューを管理するを参照してください。
Files API 3.0には、ネットワークからDatabricksへのネットワーク接続と、Databricksからストレージへのネットワーク接続が必要です。
ネットワークからDatabricksへの接続
ワークスペースへのパブリックインターネットアクセスを許可し、ファイアウォールで制限している場合は、お使いのリージョンのコントロールプレーン IP 範囲を許可リストに登録してください。
defaultストレージ、 OpenSharing SecureConnect 、 Zerobus Ingestion 、および Lakebase オートスケールのIPを含めます。「 インバウンドIP 」を参照してください。
Databricks へのインターネットアクセスを許可せず、フロントエンドプライベートLink経由で接続する場合は、パフォーマンス集中型サービス用に2つ目のフロントエンドプライベートLinkを作成してください。「 パフォーマンス集中型サービスのインバウンドPrivateLinkを構成する 」を参照してください。
Databricksからストレージへの移動
ストレージへのパブリックアクセスを許可していてもネットワーク制限を適用している場合は、リージョン内ストレージに対して Databricks Serverless OrgPath を許可リストに追加してください。それ以外の場合は、 Databricks アウトバウンドIP を許可リストに追加してください。
ストレージへのパブリックアクセスを許可しない場合は、 Amazon S3 へのプライベート Link を作成してください。「 AWS管理のリソースへのプライベート接続を構成する 」を参照してください。
Serverlessネットワーク課金が適用されます。Databricksのネットワーク コストを理解するを参照してください。
multipart uploadを使用して大きなファイルをuploadする
ベータ版
この機能はベータ版です。使用するには、ワークスペース管理者は プレビューページ から Files API V3 with Large File Upload Support を有効にする必要があります。Databricksのプレビューを管理するを参照してください。
単一のupload要求は、最大5000 MiBまでのファイルを許可します。より大きなファイルや、upload起動時にサイズが不明なファイルをuploadするには、マルチパートuploadを使用します。ファイルを分割してuploadすると、Databricksがそれらを単一のファイルにアセンブルします。
パート番号の範囲は 1 から 10000 です。最後のパートを除くすべてのパートは 5 MiB 以上である必要があり、各パートは最大 4000 MiB にできます。Databricks は、パート番号の昇順でパートを組み立てます。すべてのパラメーターについては、ファイルのuploadおよびファイルに対するアクションの実行を参照してください。
マルチパート upload の例
以下の例では、ファイルを2つの部分に分けてuploadしています。
uploadセッションを開始するには、uploadを開始します。応答には、セッションを識別する upload_id が含まれます：
POST /api/3.0/fs/files/Volumes/c/s/v/file?action=initiate-upload
200 OK
Content-Type: application/json
{
"upload_id": "dvOR6FE39mNb"
}
最初の部分をuploadするには、その内容をupload_idおよびpart_numberと共に送信します。応答には、パートのETagが含まれます。
PUT /api/3.0/fs/files/Volumes/c/s/v/file?upload_id=dvOR6FE39mNb&part_number=1
Content-Length: 268435456
Content-Type: application/octet-stream
<binary data>
200 OK
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
2番目の部分をuploadするには、次の part_number で要求を繰り返します：
PUT /api/3.0/fs/files/Volumes/c/s/v/file?upload_id=dvOR6FE39mNb&part_number=2
Content-Length: 268435456
Content-Type: application/octet-stream
<binary data>
200 OK
ETag: "954fb694be262821177cfbc47f9d4a0aa06c349b"
終了するには、すべての部分とその保存された ETag をリストする本文で upload を完了します：
POST /api/3.0/fs/files/Volumes/c/s/v/file?action=complete-upload&upload_id=dvOR6FE39mNb
Content-Type: application/json
{
"parts": [
{ "part_number": 1, "etag": "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"" },
{ "part_number": 2, "etag": "\"954fb694be262821177cfbc47f9d4a0aa06c349b\"" }
]
}
200 OK
ETag: "b3f1c2a94d6e7085f2a1c0b9e8d7654321fedcba"
このレスポンスのETagは、部品ではなく、組み立てられたファイル全体に属しています。これは後の条件付きリクエストで使用できます。たとえば、ファイルをuploadしてから変更されていない場合にのみファイルを上書きするために使用できます。
upload をキャンセルして完了しない場合は、upload_id を指定して abort-upload アクションを送信します。
POST /api/3.0/fs/files/Volumes/c/s/v/file?action=abort-upload&upload_id=dvOR6FE39mNb
200 OK
大きなファイルを範囲リクエストでdownload
範囲リクエストを使用して、大きなファイルをいくつかの小さなリクエストでdownloadするか、中断されたdownloadを再開します。
範囲をリクエストする
Range ヘッダーと共に、必要な最初のバイトと最後のバイトの 0 から始まる位置を送信します。この範囲には、両方の位置が含まれます。たとえば、bytes=0-1048575 は 10 MiB ファイルの最初の 1 MiB をリクエストします。
GET /api/3.0/fs/files/Volumes/main/default/my-volume/large-file.bin
Range: bytes=0-1048575
206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 0-1048575/10485760
Content-Length: 1048576
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
<binary data>
206 Partial Content レスポンスには、リクエストされたバイトのみが含まれており、Content-Range は含まれているバイトとファイルの合計サイズを示します。ファイルの末尾まで読み取るには、bytes=1048576- のように最後の位置を省略します。最後の位置がファイルの末尾を過ぎている場合、レスポンスには末尾までのバイトが含まれます。他の Range 構文については、downloadを参照してください。
Rangeヘッダーを使用したHEAD要求は、一致するGET要求と同じステータスとヘッダーを返しますが、本文は返しません。
中断したdownloadを再開する
downloadを再開するには、まだ受信していない最初のバイトで始まる範囲で残りのバイトをリクエストします。また、最初のレスポンスの ETag を指定して If-Match を送信し、ファイルの 2 つのバージョンのバイトを結合しないようにしてください。
GET /api/3.0/fs/files/Volumes/main/default/my-volume/large-file.bin
Range: bytes=1048576-
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 1048576-10485759/10485760
Content-Length: 9437184
<binary data>
ファイルが変更されている場合、サーバーは 412 Precondition Failed を返し、downloadを再度起動する必要があります。
条件付きリクエストの使用
ベータ版
この機能はベータ版です。使用するには、ワークスペース管理者は プレビューページ から Files API V3 with Large File Upload Support を有効にする必要があります。Databricksのプレビューを管理するを参照してください。
条件付きリクエストは、ファイルが想定の状態にある場合にのみ有効になります。条件付きリクエストを使用して、繰り返しdownloadを回避し、並列ライターが互いの変更を上書きしないようにし、ファイルを安全に作成または削除します。Files API 3.0 は、RFC 9110 の 4 つの標準 HTTP 条件付きヘッダーをサポートします。
Header | 比較 | 受賞日時 |
|---|---|---|
| ファイルの | 読み取り、書き込み、削除 |
| ファイルの | 読み取りと書き込み |
| ファイルの | 読み取りのみ |
| ファイルの | 読み取りのみ |
条件が満たされていない場合、サーバーは操作を実行せず、次のステータスのいずれかを返します。
304 Not Modified,If-None-MatchまたはIf-Modified-Sinceを含むGETまたはHEAD要求が失敗したとき。キャッシュされたコピーは引き続き有効です。412 Precondition Failed他の条件が満たされない場合に。
バリデーター：ETagおよびLast-Modified
条件付きヘッダーは、提供した値をファイルのバリデーターの1つと比較します。Files APIは、両方のバリデーターをGETおよびHEADのレスポンスヘッダーとして返します。
ETag: ファイルのコンテンツの不透明な識別子。PUTとマルチパートcomplete-upload応答でも返されます。前後の引用符を含め、返されたとおりに正確に保存し、解析や構築は行わないでください。Last-Modified：HTTP日時としてのファイルの最終変更日時。その精度は1秒であるため、If-Modified-SinceとIf-Unmodified-Sinceは同じ秒内の複数の変更を検出できません。同時実行制御には、ETagでIf-MatchまたはIf-None-Matchを使用します。
条件付き読み取り
最も一般的な条件付き読み取りは、キャッシュの再検証です。キャッシュしたコピーの ETag と共に If-None-Match を送信するか、最後に取得した時刻と共に If-Modified-Since を送信します。ファイルが変更されていない場合、サーバーは本文なしで 304 Not Modified を返します。変更されている場合、新しいコンテンツと共に 200 OK を返します。
GET /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
304 Not Modified
If-Match および If-Unmodified-Since は逆の方法で機能します。サーバーはファイルが変更されていない場合にのみファイルを返し、変更されている場合は 412 を返します。読み取りには最大で 2 つの条件付きヘッダーを含めることができ、その優先順位は RFC 9110 に従います。
条件付き書き込み
PUT で、If-None-Match と If-Match を使用して、まだ確認していない変更が上書きされるのを防ぎます。これは ロストアップデート問題 とも呼ばれます：
If-None-Match: *パスにファイルが存在しない場合にのみファイルをuploadします。それ以外の場合、リクエストは412 Precondition Failedを返します。If-Match: <etag>現在のETagが提供したものと一致する場合にのみ、ファイルをuploadします。それ以外の場合、リクエストは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
マルチパートuploadの場合、initiate-upload呼び出しで条件付きヘッダーを送信します。Files APIはuploadが完了したときに評価するため、条件はアセンブルされたファイルに適用されます。各呼び出しでサポートされているヘッダー形式については、upload ファイルとファイルに対するアクションの実行を参照してください。
条件付き削除
単純なDELETEはファイルが存在しなくても成功するため、意図したバージョンを削除したかどうかを判別できません。削除を条件付きにするには、If-Matchを送信します。
If-Match: <etag>現在のETagが指定したものと一致する場合にのみ、ファイルを削除します。取得後に誰かがファイルを変更した場合、リクエストは412 Precondition Failedを返します。ファイルが既に存在しない場合、404が返されます。If-Match: *ファイルが存在する場合にのみファイルを削除し、存在しない場合は404を返します。
DELETE /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
204 No Content
ファイルAPIバージョン
Files API 2.0 は、/api/2.0/fs Endpoint プレフィックスを使用してワークスペースホスト名にリクエストを送信します。マルチパート upload はサポートしておらず、download 時の唯一の条件付きヘッダーは If-Unmodified-Since です。Files API 2.0 リファレンスを参照してください。
コードを Files API 2.0 から 3.0 に移行するには、次の変更を行います。
/api/3.0/fsEndpointプレフィックスを使用してリージョナルホスト名にリクエストを送信し、ネットワーク接続を構成します。- すべての upload で
Content-Lengthヘッダーを送信します。ファイルサイズが事前にわからない場合は、マルチパート upload を使用します。 - uploadが成功した場合、
204 No Contentの代わりに200 OKを予期してください。 - 存在しないファイルを削除した場合、
404 Not Foundではなく204 No Contentが返されます。条件付き削除 を参照してください。