DBFS APIDBFS API

DBFS API は、ファイルを読み取るたびに資格情報を含めなくても、さまざまなデータソースと簡単に対話できるようにする Databricks API です。The DBFS API is a Databricks API that makes it simple to interact with various data sources without having to include your credentials every time you read a file. 詳細については、「 Databricks File System 」を参照してください。See Databricks File System for more information. DBFS API の使いやすいコマンドラインクライアントについては、「 DATABRICKS CLI」を参照してください。For an easy to use command line client of the DBFS API, see Databricks CLI.

ブロックの追加 Add Block

エンドポイントEndpoint HTTP メソッドHTTP Method
2.0/dbfs/add-block POST

入力ハンドルで指定されたストリームにデータのブロックを追加します。Append a block of data to the stream specified by the input handle. ハンドルが存在しない場合、この呼び出しは RESOURCE_DOES_NOT_EXISTで例外をスローします。If the handle does not exist, this call will throw an exception with RESOURCE_DOES_NOT_EXIST. データのブロックが 1 MB を超えると、この呼び出しは MAX_BLOCK_SIZE_EXCEEDEDで例外をスローします。If the block of data exceeds 1 MB, this call will throw an exception with MAX_BLOCK_SIZE_EXCEEDED. 要求の例:Example of request:

{
  "data": "ZGF0YWJyaWNrcwo=",
  "handle": 7904256
}

要求構造 Request Structure

フィールド名Field Name タイプType descriptionDescription
扱えhandle INT64 開いているストリームのハンドル。The handle on an open stream. このフィールドは必須です。This field is required.
datadata BYTES ストリームに追加する base64 でエンコードされたデータ。The base64-encoded data to append to the stream. これには 1 MB の制限があります。This has a limit of 1 MB. このフィールドは必須です。This field is required.

閉じる Close

エンドポイントEndpoint HTTP メソッドHTTP Method
2.0/dbfs/close POST

入力ハンドルで指定されたストリームを閉じます。Close the stream specified by the input handle. ハンドルが存在しない場合、この呼び出しは RESOURCE_DOES_NOT_EXISTで例外をスローします。If the handle does not exist, this call throws an exception with RESOURCE_DOES_NOT_EXIST.

要求構造 Request Structure

フィールド名Field Name タイプType descriptionDescription
扱えhandle INT64 開いているストリームのハンドル。The handle on an open stream. このフィールドは必須です。This field is required.

作成 Create

エンドポイントEndpoint HTTP メソッドHTTP Method
2.0/dbfs/create POST

ストリームを開いてファイルに書き込み、このストリームへのハンドルを返します。Open a stream to write to a file and returns a handle to this stream. このハンドルには、10分間のアイドルタイムアウトがあります。There is a 10 minute idle timeout on this handle. 指定されたパスにファイルまたはディレクトリが既に存在し、overwrite が false に設定されている場合、この呼び出しは RESOURCE_ALREADY_EXISTSで例外をスローします。If a file or directory already exists on the given path and overwrite is set to false, this call throws an exception with RESOURCE_ALREADY_EXISTS. ファイルのアップロードに関する一般的なワークフローは次のとおりです。A typical workflow for file upload would be:

  1. create 呼び出しを発行し、ハンドルを取得します。Issue a create call and get a handle.
  2. ハンドルを使用して1つ以上の add-block 呼び出しを発行します。Issue one or more add-block calls with the handle you have.
  3. ハンドルを使用して close の呼び出しを発行します。Issue a close call with the handle you have.

要求構造 Request Structure

フィールド名Field Name タイプType descriptionDescription
パスpath STRING 新しいファイルのパス。The path of the new file. パスは絶対 DBFS パス (例: "/mnt/foo.txt") にする必要があります。The path should be the absolute DBFS path (e.g. “/mnt/foo.txt”). このフィールドは必須です。This field is required.
overwriteoverwrite BOOL 既存のファイルを上書きするかどうかを指定するフラグ。The flag that specifies whether to overwrite existing file or files.

応答構造体 Response Structure

フィールド名Field Name タイプType descriptionDescription
扱えhandle INT64 ストリームを介してファイルに書き込むときに、後で AddBlock に渡す必要があるハンドル。Handle which should subsequently be passed into the AddBlock and Close calls when writing to a file through a stream.

削除 Delete

エンドポイントEndpoint HTTP メソッドHTTP Method
2.0/dbfs/delete POST

ファイルまたはディレクトリを削除します (必要に応じて、ディレクトリ内のすべてのファイルを再帰的に削除します)。Delete the file or directory (optionally recursively delete all files in the directory). パスが空でないディレクトリで、recursive が false または他の同様のエラーに設定されている場合、この呼び出しは IO_ERROR で例外をスローします。This call throws an exception with IO_ERROR if the path is a non-empty directory and recursive is set to false or on other similar errors.

要求構造 Request Structure

フィールド名Field Name タイプType descriptionDescription
パスpath STRING 削除するファイルまたはディレクトリのパス。The path of the file or directory to delete. パスは絶対 DBFS パス (例: "/mnt/foo/") にする必要があります。The path should be the absolute DBFS path (e.g. “/mnt/foo/”). このフィールドは必須です。This field is required.
recursiverecursive BOOL ディレクトリの内容を再帰的に削除するかどうかを指定します。Whether or not to recursively delete the directory’s contents. 空のディレクトリの削除は、再帰フラグを指定せずに実行できます。Deleting empty directories can be done without providing the recursive flag.

状態の取得 Get Status

エンドポイントEndpoint HTTP メソッドHTTP Method
2.0/dbfs/get-status GET

ファイルまたはディレクトリのファイル情報を取得します。Get the file information of a file or directory. ファイルまたはディレクトリが存在しない場合、この呼び出しは RESOURCE_DOES_NOT_EXISTで例外をスローします。If the file or directory does not exist, this call throws an exception with RESOURCE_DOES_NOT_EXIST.

要求構造 Request Structure

フィールド名Field Name タイプType descriptionDescription
パスpath STRING ファイルまたはディレクトリのパス。The path of the file or directory. パスは絶対 DBFS パス (例: "/mnt/foo/") にする必要があります。The path should be the absolute DBFS path (e.g. “/mnt/foo/”). このフィールドは必須です。This field is required.

応答構造体 Response Structure

フィールド名Field Name タイプType descriptionDescription
パスpath STRING ファイルまたはディレクトリのパス。The path of the file or directory.
is_diris_dir BOOL パスがディレクトリである場合は True。True if the path is a directory.
file_sizefile_size INT64 ファイルの長さ (バイト単位)。または、パスがディレクトリの場合は0。The length of the file in bytes or zero if the path is a directory.

リスト List

エンドポイントEndpoint HTTP メソッドHTTP Method
2.0/dbfs/list GET

ディレクトリの内容またはファイルの詳細を一覧表示します。List the contents of a directory, or details of the file. ファイルまたはディレクトリが存在しない場合、この呼び出しは RESOURCE_DOES_NOT_EXISTで例外をスローします。If the file or directory does not exist, this call throws an exception with RESOURCE_DOES_NOT_EXIST. 応答の例:Example of reply:

{
  "files": [
    {
      "path": "/a.cpp",
      "is_dir": false,
      "file_size": 261
    },
    {
      "path": "/databricks-results",
      "is_dir": true,
      "file_size": 0
    }
  ]
}

要求構造 Request Structure

フィールド名Field Name タイプType descriptionDescription
パスpath STRING ファイルまたはディレクトリのパス。The path of the file or directory. パスは絶対 DBFS パス (例: "/mnt/foo/") にする必要があります。The path should be the absolute DBFS path (e.g. “/mnt/foo/”). このフィールドは必須です。This field is required.

応答構造体 Response Structure

フィールド名Field Name タイプType descriptionDescription
ファイルのアップロードfiles FileInfoの配列An array of FileInfo ディレクトリまたはファイルの内容を記述する FileInfo の一覧。A list of FileInfo that describe contents of directory or file. (上記の例を参照)。See example above.

Mkdirs Mkdirs

エンドポイントEndpoint HTTP メソッドHTTP Method
2.0/dbfs/mkdirs POST

指定したディレクトリと、必要な親ディレクトリが存在しない場合は作成します。Create the given directory and necessary parent directories if they do not exist. 入力パスの任意のプレフィックスに (ディレクトリではなく) ファイルが存在する場合、この呼び出しは RESOURCE_ALREADY_EXISTSで例外をスローします。If there exists a file (not a directory) at any prefix of the input path, this call throws an exception with RESOURCE_ALREADY_EXISTS. この操作が失敗した場合は、必要な親ディレクトリの一部の作成に成功した可能性があります。If this operation fails it may have succeeded in creating some of the necessary parent directories.

要求構造 Request Structure

フィールド名Field Name タイプType descriptionDescription
パスpath STRING 新しいディレクトリのパス。The path of the new directory. パスは絶対 DBFS パス (例: "/mnt/foo/") にする必要があります。The path should be the absolute DBFS path (e.g. “/mnt/foo/”). このフィールドは必須です。This field is required.

移動 Move

エンドポイントEndpoint HTTP メソッドHTTP Method
2.0/dbfs/move POST

DBFS 内のある場所から別の場所にファイルを移動します。Move a file from one location to another location within DBFS. ソースファイルが存在しない場合、この呼び出しは RESOURCE_DOES_NOT_EXISTで例外をスローします。If the source file does not exist, this call throws an exception with RESOURCE_DOES_NOT_EXIST. コピー先のパスにファイルが既に存在する場合、この呼び出しは RESOURCE_ALREADY_EXISTSで例外をスローします。If there already exists a file in the destination path, this call throws an exception with RESOURCE_ALREADY_EXISTS. 指定されたソースパスがディレクトリである場合、この呼び出しは常にすべてのファイルを再帰的に移動します。If the given source path is a directory, this call always recursively moves all files.

要求構造 Request Structure

フィールド名Field Name タイプType descriptionDescription
source_pathsource_path STRING ファイルまたはディレクトリのソースパス。The source path of the file or directory. パスは絶対 DBFS パス (例: "/mnt/foo/") にする必要があります。The path should be the absolute DBFS path (e.g. “/mnt/foo/”). このフィールドは必須です。This field is required.
destination_pathdestination_path STRING ファイルまたはディレクトリの移動先のパス。The destination path of the file or directory. パスは絶対 DBFS パス (例: "/mnt/bar/") にする必要があります。The path should be the absolute DBFS path (e.g. “/mnt/bar/”). このフィールドは必須です。This field is required.

Put Put

エンドポイントEndpoint HTTP メソッドHTTP Method
2.0/dbfs/put POST

マルチパートフォーム post を使用してファイルをアップロードします。Upload a file through the use of multipart form post. これは主にストリーミングアップロードに使用されますが、データをアップロードするための便利な1回の呼び出しとして使用することもできます。It is mainly used for streaming uploads, but can also be used as a convenient single call for data upload. 使用例:Example usage:

次の例では、<databricks-instance> を Azure Databricks デプロイの <region>.azuredatabricks.net ドメイン名に置き換えます。In the following examples, replace <databricks-instance> with the <region>.azuredatabricks.net domain name of your Azure Databricks deployment.

curl -F contents=@localsrc -F path="PATH" https://<databricks-instance>/api/2.0/dbfs/put

localsrc は、アップロードするローカルファイルへのパスであり、この使用方法はマルチパートフォームポスト (つまり、curl-F `` or ``--form を使用) でのみサポートされています。localsrc is the path to a local file to upload and this usage is supported only with multipart form post (i.e. using -F `` or ``--form with curl).

または、コンテンツを base64 文字列として渡すこともできます。Alternatively you can pass contents as a base64 string. 例:Examples:

curl -F contents="BASE64" -F path="PATH" https://<databricks-instance>/api/2.0/dbfs/put
curl  -H "Content-Type: application/json" -d '{"path":"PATH","contents":"BASE64"}' https://<databricks-instance>/api/2.0/dbfs/put``

contents (ストリーミングなし) パラメーターを使用して渡すことができるデータの量は 1 MB に制限されています。を超えると MAX_BLOCK_SIZE_EXCEEDED がスローされます。The amount of data that can be passed using contents (i.e. not streaming) parameter is limited to 1 MB; MAX_BLOCK_SIZE_EXCEEDED is thrown if exceeded. 大きなファイルをアップロードする場合は、ストリーミングアップロードを使用します。Use streaming upload if you want to upload large files. 詳細については、「 Create」、「 Add Block」、および「 Close 」を参照してください。See Create, Add Block, and Close for details.

要求構造 Request Structure

フィールド名Field Name タイプType descriptionDescription
パスpath STRING 新しいファイルのパス。The path of the new file. パスは絶対 DBFS パス (例: "/mnt/foo/") にする必要があります。The path should be the absolute DBFS path (e.g. “/mnt/foo/”). このフィールドは必須です。This field is required.
内容contents BYTES このパラメーターは存在しない可能性があり、代わりにポストされたファイルが使用されます。This parameter might be absent, and instead a posted file will be used.
overwriteoverwrite BOOL 既存のファイルを上書きするかどうかを指定するフラグ。The flag that specifies whether to overwrite existing files.

読み取り Read

エンドポイントEndpoint HTTP メソッドHTTP Method
2.0/dbfs/read GET

ファイルの内容を返します。Return the contents of a file. ファイルが存在しない場合、この呼び出しは RESOURCE_DOES_NOT_EXISTで例外をスローします。If the file does not exist, this call throws an exception with RESOURCE_DOES_NOT_EXIST. パスがディレクトリの場合、読み取り長が負の場合、またはオフセットが負の場合、この呼び出しは INVALID_PARAMETER_VALUEで例外をスローします。If the path is a directory, the read length is negative, or if the offset is negative, this call throws an exception with INVALID_PARAMETER_VALUE. 読み取りの長さが 1 MB を超えた場合、この呼び出しは MAX_READ_SIZE_EXCEEDEDで例外をスローします。If the read length exceeds 1 MB, this call throws an exception with MAX_READ_SIZE_EXCEEDED. offset + length がファイル内のバイト数を超えている場合、はファイルの最後までコンテンツを読み取ります。If offset + length exceeds the number of bytes in a file, reads contents until the end of file.

要求構造 Request Structure

フィールド名Field Name タイプType descriptionDescription
パスpath STRING 読み取るファイルのパス。The path of the file to read. パスは絶対 DBFS パス (例: "/mnt/foo/") にする必要があります。The path should be the absolute DBFS path (e.g. “/mnt/foo/”). このフィールドは必須です。This field is required.
offsetoffset INT64 読み取るオフセット (バイト単位)。The offset to read from in bytes.
lengthlength INT64 オフセットから読み取りを開始するバイト数。The number of bytes to read starting from the offset. これには 1 MB の制限があり、既定値は 0.5 MB です。This has a limit of 1 MB, and a default value of 0.5 MB.

応答構造体 Response Structure

フィールド名Field Name タイプType descriptionDescription
bytes_readbytes_read INT64 読み取られたバイト数 (ファイルの終端に達した場合は length 未満の可能性があります)。The number of bytes read (could be less than length if we hit end of file). これは、エンコードされていないバージョンで読み取られたバイト数を表します (応答データは base64 でエンコードされます)。This refers to number of bytes read in unencoded version (response data is base64-encoded).
datadata BYTES 読み取られたファイルの base64 でエンコードされた内容。The base64-encoded contents of the file read.

データ構造 Data Structures

FileInfo FileInfo

ファイルまたはディレクトリの属性を格納します。Store the attributes of a file or directory.

フィールド名Field Name タイプType descriptionDescription
パスpath STRING ファイルまたはディレクトリのパス。The path of the file or directory.
is_diris_dir BOOL パスがディレクトリである場合は True。True if the path is a directory.
file_sizefile_size INT64 ファイルの長さ (バイト単位)。または、パスがディレクトリの場合は0。The length of the file in bytes or zero if the path is a directory.