Unity Catalog ボリュームで Files API を使用する

Files APIを使ってパスを指定してファイルやディレクトリを読み書き、リストアップ、削除できます。 Unity Catalog のボリューム内のファイル (絶対ボリューム パスで参照する) で動作します。たとえば、/Volumes/<catalog>/<schema>/<volume>/<path>。 Files API 3.0のリクエストは /api/3.0/fs エンドポイントプレフィックスを使用し、ワークスペースの リージョンホスト名に送られます。 すべての操作、パラメータ、ヘッダーについては、Files API 3.0のリファレンスを参照してください。

Files APIの使用はAzure Databricksのデータ転送料金が発生する可能性があります。

リージョンのホスト名にリクエストを送信

Important

この機能は ベータ版です。 使用するには、ワークスペース管理者がPreviewsページからFiles API V3 with Large File Upload Supportを有効にする必要があります。 Manage Azure Databricks プレビューを参照してください。

Send Files API 3.0のリクエストを、リクエストしたユーザーが所属するワークスペースのリージョナルホスト名に送信します。 地域ホスト名のフォーマットは以下の通りです:

<workspace-id>.storage.<workspace-region>.<databricks-domain>

たとえば、「 1234567890123456.storage.westus.azuredatabricks.net 」のように入力します。

ワークスペースIDと地域を調べるには、アカウントコンソールを使ってください。 ワークスペース インスタンス名、URL、ID を参照してください。 また、デプロイのURLにもワークスペースIDが記載されています。 https://<databricks-instance>/?o=1234567890123456では、 o= の後の番号がワークスペースIDです。 ワークスペースUIではワークスペース名の下にリージョンが表示されます。

ネットワーク接続を構成する

Important

この機能は ベータ版です。 使用するには、ワークスペース管理者がPreviewsページからFiles API V3 with Large File Upload Supportを有効にする必要があります。 Manage Azure Databricks プレビューを参照してください。

Files API 3.0は、お客様のネットワークからAzure Databricksへのネットワーク接続、およびAzure Databricksからストレージへの接続を必要とします。

お客様のネットワークから Azure Databricks へ

ワークスペースに公共のインターネットアクセスを許可しつつファイアウォールで制限する場合は、地域のコントロールプレーンのIP範囲を許可リストにしてください。

コントロール プレーン IP に、既定のストレージおよび Web アプリの IP を含めてください。 Azure Databricks コントロール プレーンへの受信を参照してください。

Azure Databricksへのインターネットアクセスを許可せず、フロントエンドのプライベートリンク経由で接続する場合は、パフォーマンス集約型のサービス用に2つ目のフロントエンドプライベートリンクを作成しましょう。 パフォーマンスが重要なサービスのための受信プライベート リンクの構成を参照してください。

Azure Databricksからあなたのストレージへ

ストレージへの公開アクセスを許可しつつネットワーク制限を適用する場合は、地域内ストレージについてはストレージアカウントをAzureネットワークセキュリティペリメーター(NSP)に追加し、AzureDatabricksServerlessサービスタグを許可リストにしてください。 ネットワーク セキュリティ境界はトランジション モードに保たれなければなりません。 それ以外の場合は、Azure DatabricksのアウトバウンドIPをallowlistしてください。

ストレージへの公開アクセスを許可しない場合は、Azureストレージへのプライベートリンクを設定してください。 「Azure リソースへのプライベート接続を構成する」を参照してください。

Note

サーバーレスネットワーク課金が適用されます。 Databricks のネットワーク コストを理解するを参照してください。

マルチパートアップロードで大きなファイルをアップロードする

Important

この機能は ベータ版です。 使用するには、ワークスペース管理者がPreviewsページからFiles API V3 with Large File Upload Supportを有効にする必要があります。 Manage Azure Databricks プレビューを参照してください。

単一のアップロードリクエストで最大5000 MiBのファイルを受け付けることができます。 大きなファイルや、アップロード開始時にサイズが不明なファイルをアップロードするには、マルチパートアップロードを使います。ファイルを分割してアップロードし、Azure Databricksがそれらを1つのファイルにまとめます。

部品番号は1から10000までの範囲です。 最後の部分を除くすべての部分は少なくとも5 MiBでなければならず、各部分は最大4000 MiBまでです。 Azure Databricksはパーツをパーツ番号の昇順で組み立てます。 すべてのパラメータについては、「ファイルのアップロード」と「ファイルに対してアクションを実行」を参照してください。

マルチパートアップロードの例

以下の例はファイルを2回に分けてアップロードします。

アップロードセッションを開始するには、アップロードを開始してください。 応答にはセッションを識別する 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_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 つ目の部分をアップロードするには、次の 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 を記載した本文を添えて、アップロードを完了します:

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 は、一部ではなく、組み立てられたファイル全体に属します。 例えば、アップロード後にファイルが変更されていない場合のみ、後で条件 付きリクエストで使うことができます。

アップロードを完了する代わりにキャンセルするには、abort-uploadとともにupload_idアクションを送信してください:

POST /api/3.0/fs/files/Volumes/c/s/v/file?action=abort-upload&upload_id=dvOR6FE39mNb

200 OK

レンジリクエストで大きなファイルをダウンロード

レンジリクエストを使って、大きなファイルを複数の小さなリクエストに分けてダウンロードしたり、中断されたダウンロードを再開したりします。

範囲を要求する

欲しい最初のバイトと最後のバイトのゼロベースの位置を指定して Range ヘッダーを送信します。 この範囲には両方の位置が含まれます。 例えば、 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 構文については、「 ファイルをダウンロード」をご覧ください。

HEADヘッダーを持つRangeリクエストは、本文なしで、対応するGETリクエストと同じステータスとヘッダーを返します。

中断されたダウンロードを再開する

ダウンロードを再開するには、受け取っていない最初のバイトから始まる範囲の残りのバイトをリクエストしてください。 また、最初の回答の If-Match を添えて ETag も送ってください。そうすれば、ファイルの 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を返し、ダウンロードを最初からやり直さなければなりません。

条件付きリクエストの使用

Important

この機能は ベータ版です。 使用するには、ワークスペース管理者がPreviewsページからFiles API V3 with Large File Upload Supportを有効にする必要があります。 Manage Azure Databricks プレビューを参照してください。

条件付き要求は、ファイルが想定した状態にある場合にのみ有効です。 条件付きリクエストを使って繰り返しダウンロードを防ぎ、同時ライター同士が互いの変更を上書きしないようにし、ファイルを安全に作成または削除しましょう。 Files API 3.0は RFC 9110の4つの標準HTTP条件付きヘッダーをサポートしています:

Header ～と比較 表彰日
If-Match ファイルの ETag 読み取り、書き込み、削除
If-None-Match ファイルの ETag 読み取りおよび書き込み
If-Modified-Since ファイルの Last-Modified 時間 読み取り専用
If-Unmodified-Since ファイルの Last-Modified 時間 読み取り専用

条件が満たされない場合、サーバーは操作を行わず、以下のいずれかの状態を返します。

  • 304 Not Modified、GETまたはHEADを含むIf-None-MatchやIf-Modified-Sinceのリクエストが失敗した場合 キャッシュされたコピーはまだ有効です。
  • 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 は同じ秒内で複数の変化を検知できません。 並行制御にはIf-MatchをIf-None-MatchまたはETagと組み合わせて使いましょう。

条件付き読み取り

最も一般的な条件付き読み込みはキャッシュ再検証です。 キャッシュされたコピーの 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: * パスにファイルが存在しない場合のみファイルをアップロードします。 そうでなければ、リクエストは 412 Precondition Failedを返します。
  • If-Match: <etag> 現在の 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

ファイルを上書きするには、最後に取得したバージョンのままである場合にのみ、If-Match を指定して ETag を送信してください。

PUT /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Content-Type: application/octet-stream
<binary data>

200 OK

マルチパートアップロードの場合は、initiate-uploadコールに条件付きヘッダーを送信します。 Files APIはアップロード完了時にそれを評価するため、この条件はアセンブルされたファイルに適用されます。 各コールがサポートするヘッダー形式については、「ファイルのアップロード」および「ファイルに対してアクションを実行する」を参照してください。

条件付き削除

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のバージョン

ファイル API 2.0は、/api/2.0/fs をエンドポイント プレフィックスとして使用して、ワークスペース ホスト名に要求を送信します。 マルチパートアップロードには対応しておらず、条件付きヘッダーはダウンロード時の If-Unmodified-Since のみです。 Files API 2.0のリファレンスを参照してください。

コードを Files API 2.0 から 3.0 に移行するには、以下の変更を加えてください:

  • /api/3.0/fsにエンドポイントプレフィックス付きでリクエストを送信し、ネットワーク接続を設定します。
  • すべてのアップロード時に Content-Length ヘッダーを送信してください。 ファイルサイズが事前に分からない場合は、 マルチパートアップロードを使いましょう。
  • 成功したアップロードでは200 OKではなく204 No Contentを期待してください。
  • 存在しないファイルを削除した場合は、404 Not Found ではなく、204 No Content が返されることを想定してください。 条件付き削除を参照してください。
  • 最終更新: