メインコンテンツまでスキップ
に最終更新

Files APIを使用する

Files API を使用して、パスによってファイルとディレクトリの読み取り、書き込み、一覧表示、削除を行います。これは Unity Catalog ボリューム内のファイルで動作し、/Volumes/<catalog>/<schema>/<volume>/<path> のような絶対ボリュームパスで参照します。Files API 3.0 リクエストは /api/3.0/fs Endpoint プレフィックスを使用し、ワークスペースのリージョンホスト名に移動します。すべての操作、パラメーター、ヘッダーについては、Files API 3.0 リファレンスを参照してください。

備考

ベータ版

この機能はベータ版です。使用するには、ワークスペース管理者は プレビュー ページから 大きなファイルuploadをサポートするFiles API V3 を有効にする必要があります。Databricksのプレビューを管理を参照してください。

Files API の使用には、Databricks のデータ転送料金が発生する場合があります。

リージョナルホスト名にリクエストを送信する​

リクエストユーザーが所属するワークスペースのリージョンホスト名に「Files API 3.0」のリクエストを送信します。リージョンホスト名の形式は次のとおりです。

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

たとえば、 1234567890123456.storage.us-west-2.cloud.databricks.com。

ワークスペースIDとリージョンを見つけるには、アカウントコンソールを使用してください。「ワークスペースインスタンス名、URL、およびID」を参照してください。ワークスペースIDは、デプロイメントURLから見つけることもできます。https://<databricks-instance>/?o=1234567890123456では、o= の後の数字がワークスペースIDです。ワークスペースUIには、ワークスペース名の下にリージョンが表示されます。

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

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のネットワークコストを理解するを参照してください。

大きなファイルをUploadする​

1回のuploadリクエストで、最大5000 MiBまでのファイルを受け入れることができます。より大きなファイルをuploadする場合、またはupload起動時にサイズが不明なファイルをuploadする場合は、Files API 3.0マルチパートuploadを使用します：initiate-uploadアクションでセッションを起動し、PUTで各パートをuploadし、complete-uploadアクションで各パートを組み立てます。パートの制限とリクエストの詳細については、ファイルをuploadするおよびファイルに対するアクションを実行するを参照してください。

中断されたdownloadを再開する​

中断されたdownloadを再開するには、受信していない最初のバイトから始まる Range ヘッダーで残りのバイトをリクエストします。リクエスト間でファイルが変更されていないことを確認するには、最初の応答の ETag を指定して If-Match も送信します。

HTTP
GET /api/3.0/fs/files/Volumes/main/default/my-volume/large-file.bin
Range: bytes=1048576-
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

206 Partial Content
Content-Range: bytes 1048576-10485759/10485760
<binary data>

ファイルが変更された場合、サーバーは 412 Precondition Failed を返します。downloadを再度起動する必要があります。ファイルの異なるバージョンのバイトを組み合わせると、結果が破損します。Range ヘッダー構文については、ファイルのdownloadを参照してください。

条件付きリクエスト​

条件付きヘッダーを使用して、ファイルの現在の ETag または Last-Modified 値が設定した条件を満たす場合にのみリクエストをランします。各オペレーションがサポートするヘッダーについては、Files API 3.0 リファレンスを参照してください。それらを使用する際は、以下に注意してください。

  • ETagを、周囲の引用符を含め、サーバーが返したとおりに保存し、変更せずに送信し返します。ETagを解析または作成しないでください。
  • Last-Modified 精度は1秒単位であるため、If-Modified-SinceとIf-Unmodified-Sinceでは同じ秒内に発生した複数の変更を検出できません。並列書き込みによって互いの変更が上書きされないようにするには、代わりにIf-MatchまたはIf-None-Matchを使用してください。
  • 読み取りリクエストには、最大2つの条件付きヘッダーを含めることができます。2つ送信すると、その優先順位はRFC 9110に従います。

Files 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/fsのEndpoint接頭辞を持つリージョンホスト名に送信し、ネットワーク接続を構成します。
  • すべてのuploadでContent-Lengthヘッダーを送信します。事前にファイルサイズが分からない場合は、マルチパートuploadを使用します。
  • 成功したuploadから、204 No Contentではなく200 OKを予期します。
  • 存在しないファイルを削除すると、204 No Contentが返されることを想定します。ファイル API 2.0 のように 404 Not Found を取得するには、 If-Match: * を送信します。
このページの見出し