Databricks REST API リファレンス

[アーティクル]
02/01/2023

Azure Databricks には、異なるタスクを実行する次の 3 種類の REST API があります。

一般的な管理用の 2.0 および 2.1
Azure Databricks でコマンドを直接実行する場合は 1.2

すべての REST API の最新バージョンについては、「REST API (最新)」を参照してください。また、各バージョンの REST API ホームページ ( 2.1、 2.0、または 1.2) に直接ジャンプすることもできます。

重要

Databricks REST API にアクセスするには、認証する必要があります。

Account API 2.0
Clusters API 2.0
Cluster Policies API 2.0
データ系列 API 2.0
Databricks SQL Queries, Dashboards, and Alerts API 2.0
Databricks SQL Query History API 2.0
Databricks SQL Warehouses API 2.0
DBFS API 2.0
Delta Live Tables API 2.0
Git Credentials API 2.0
Global Init Scripts API 2.0
Groups API 2.0
Instance Pools API 2.0
IP Access List API 2.0
Jobs API 2.1, 2.0
Libraries API 2.0
MLflow API 2.0
Permissions API 2.0
Repos API 2.0
SCIM API 2.0
Secrets API 2.0
Token API 2.0
Token Management API 2.0
Unity Catalog API 2.1、2.0
Workspace API 2.0
API 1.2

認証

個人用アクセストークンを使用した REST API に対する認証の詳細については、「Azure Databricks 個人用アクセストークンを使用して認証する」を参照してください。

Azure Active Directory トークンを使用した REST API に対する認証の詳細については、「Azure Active Directory トークンを使用して認証する」を参照してください。例については、ユーザーに対する Azure AD アクセストークンの使用およびサービスプリンシパルに対する Azure AD アクセストークンの使用に関する記事を参照してください。

API の例については、「API の例」を参照してください。

転送率の制限

負荷が高い状態でのサービスの高品質を確保するために、Databricks ではすべての REST API 呼び出しに対してレート制限が適用されます。制限は、公平な使用と高可用性を確保するために、エンドポイントごとおよびワークスペースごとに設定されます。

レート制限を超える要求には、429 応答状態コードが返されます。

API 要求のレート制限の詳細については、「API レート制限」を参照してください。

出力を解析する

JSON 出力の一部を解析すると便利な場合があります。 Databricks では、JSON を解析するユーティリティ jq をお勧めします。 jq は、Linux では jq Releases を使用して、macOS では Homebrew を使用して brew install jq で、Windows では Chocolatey を使用して choco install jq でインストールできます。 jq の詳細については、jq のマニュアルを参照してください。

この例では、指定されたワークスペースで使用可能なクラスターの名前と ID を一覧表示します。この例では、.netrc ファイルを使用します。

curl --netrc -X GET https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/list \
| jq '[ .clusters[] | { id: .cluster_id, name: .cluster_name } ]'

[
  {
    "id": "1234-567890-batch123",
    "name": "My Cluster 1"
  },
  {
    "id": "2345-678901-rigs234",
    "name": "My Cluster 2"
  }
]

互換性

同じ API バージョンに対する応答では、JSON 出力からフィールドは削除されません。ただし、API のバージョンをインクリメントせずに、API によって JSON 出力に新しいフィールドが追加される場合があります。プログラムのワークフローでは、これらの追加を認識し、不明なフィールドを無視する必要があります。

一部の STRING フィールド (UI で使用することを目的としたエラーと説明のメッセージングを含む) は構造化されていないため、プログラムによるワークフローではこれらのフィールドの形式に依存できません。

curl を使用して Databricks REST API を呼び出す

curl は、サーバーとの間でデータを転送するための一般的なツールです。このセクションでは、curl を使用して Databricks REST API を呼び出す方法について具体的に説明します。

クエリ文字列を使用して GET を呼び出す

ほとんどの API 呼び出しでは JSON 本文を指定する必要がありますが、GET 呼び出しの場合は、? の後に追加して URL を引用符で囲むことでクエリ文字列を指定できます。 curl を使用する場合は、クエリ文字列と共に --get (または -G) と --data (または -d) を指定できます。URL またはクエリ文字列を引用符で囲む必要はありません。

以下の例では、adb-1234567890123456.7.azuredatabricks.net を Azure Databricks デプロイのワークスペース URL に置き換えます。 adb- で始まる必要があります。 <azure-region-name> で始まる非推奨のリージョンの URL は使用しないでください。新しいワークスペースでは機能しない可能性があり、信頼性が低く、ワークスペースごとの URL よりパフォーマンスが低下します。

この例では、指定したクラスターに関する情報を出力します。この例では、.netrc ファイルを使用します。

?の使用

curl --netrc 'https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get?cluster_id=1234-567890-patch123'

--get と --data の使用:

curl --netrc --get \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get \
--data cluster_id=1234-567890-batch123

{
  "cluster_id": "1234-567890-batch123",
  "driver": {
    "node_id": "123ab456789012345cd67e8e90123f45",
    "instance_id": "234ab456789012345cd67e8e90123f45",
    "start_timestamp": 1618448261567,
    "host_private_ip": "10.0.0.0",
    "private_ip": "10.0.0.0"
  },
  ...
}

この例では、DBFS ルートの内容を一覧表示します。この例では、.netrc ファイルを使用します。

curl --netrc --get \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/list \
--data path=/

"files": [
  {
    "path": "/tmp",
    "is_dir": true,
    "file_size": 0,
    "modification_time": 1547078156000
  },
  {
    "path": "/my_file.txt",
    "is_dir": false,
    "file_size": 40,
    "modification_time": 1541374426000
  },
  ...
]

Python を使用して Databricks REST API を呼び出す

Python を使用して Databricks REST API を呼び出すには、Databricks CLI パッケージをライブラリとして使用します。このパッケージは Python で記述されており、これを使用すると、Databricks REST API の要求と応答ペイロードを厳密にモデル化する Python クラスを使用して Databricks REST API が呼び出されます。詳細については、Python を使用した Databricks REST API の呼び出しに関する記事を参照してください。

Python requests ライブラリを直接使用する方法もあります。ただし、必要なヘッダーを手動で指定したり、エラーを処理したり、その他の関連する低レベルのコーディングタスクを行ったりして、より低レベルで作業する必要があります。

requests は、Python で HTTP 要求を行うための一般的なライブラリです。この例では、requests ライブラリを使用して、指定された Azure Databricks クラスターに関する情報を一覧表示します。この例では、.netrc ファイルを使用します。

import requests
import json

instance_id = 'adb-1234567890123456.7.azuredatabricks.net'

api_version = '/api/2.0'
api_command = '/clusters/get'
url = f"https://{instance_id}{api_version}{api_command}"

params = {
  'cluster_id': '1234-567890-batch123'
}

response = requests.get(
  url = url,
  params = params
)

print(json.dumps(json.loads(response.text), indent = 2))

{
  "cluster_id": "1234-567890-batch123",
  "driver": {
    ...
  },
  "spark_context_id": 1234567890123456789,
  ...
}

Postman を使用して Databricks REST API を呼び出す

Postman アプリで、新しい HTTP 要求を作成します ([ファイル]>[新規]>[HTTP 要求])。
[HTTP 動詞] ドロップダウンリストで、呼び出す REST API 操作を表す動詞を選択します。たとえば、Azure Databricks クラスターに関する情報を一覧表示するには、[GET] を選択します。
[要求 URL を入力してください] に、まず「https://<databricks-instance-name>」と入力します。ここで、<databricks-instance-name> は Azure Databricks ワークスペースインスタンス名 (例: adb-1234567890123456.7.azuredatabricks.net) です。
要求 URL の最後は、呼び出す REST API 操作を表すパスにします。たとえば、クラスターに関する情報を一覧表示するには、/api/2.0/clusters/get を使用します。
[認可] タブの、[種類] リストで [ベアラートークン] を選択します。
[トークン] には、ワークスペースユーザーの Databricks 個人用アクセストークンを入力します。

ヒント

呼び出しのたびにワークスペースインスタンス名 (adb-1234567890123456.7.azuredatabricks.net など) とワークスペースユーザーの Databricks 個人用アクセストークンを入力する代わりに、変数を定義して Postman で変数を使用できます。
呼び出す REST API 操作に要求本文が必要な場合は、次を行います。
1. [ヘッダー] タブに、Content-Type のキーと値のペアと、REST API 操作に使用できるコンテンツタイプを追加します。たとえば、クラスターに関する情報を一覧表示するには、application/json コンテンツタイプを使用します。
2. [本体] タブで、REST API 操作に使用できる本文の種類を選択します。たとえば、クラスターに関する情報を一覧表示するには、本文の種類として [生]、さらに [JSON] を選択します。
3. 要求本文を入力します。たとえば、指定したクラスターに関する情報を一覧表示するには、次を入力します。
```
{
  "cluster_id": "1234-567890-batch123"
}
```
呼び出す REST API 操作に追加のヘッダーが必要な場合は、[ヘッダー] タブに追加のキーと値のペアとして入力します。たとえば、クラスターに関する情報を一覧表示する場合は、追加のヘッダーは必要ありません。
呼び出す REST API 操作にクエリパラメーターが必要な場合は、[パラメーター] タブにキーと値のペアとして入力します。たとえば、クラスターに関する情報を一覧表示するには、要求本文を使用する代わりに、キーが cluster_id、値が指定したクラスターの ID (1234-567890-batch123 など) であるクエリパラメーターを使用できます。
[送信] をクリックします。応答の詳細は、応答セクションの [本体] タブに表示されます。

HTTPie を使用して Databricks REST API を呼び出す

HTTPie デスクトップアプリまたは HTTPie Web アプリを使用して Databricks REST API を呼び出す

HTTPie デスクトップアプリを開くか、HTTPie Web アプリにアクセスします。
[HTTP 動詞] ドロップダウンリストで、呼び出す REST API 操作を表す動詞を選択します。たとえば、Azure Databricks クラスターに関する情報を一覧表示するには、[GET] を選択します。
[httpie.io/hello] ボックスに、まず「https://<databricks-instance-name>」と入力します。ここで、<databricks-instance-name> は Azure Databricks ワークスペースインスタンス名 (例: adb-1234567890123456.7.azuredatabricks.net) です。
要求 URL の最後は、呼び出す REST API 操作を表すパスにします。たとえば、クラスターに関する情報を一覧表示するには、/api/2.0/clusters/get を使用します。
[認証] タブで、[Bearer Token] (ベアラートークン) をクリックします。
[トークン] には、ワークスペースユーザーの Databricks 個人用アクセストークンを入力します。

ヒント

呼び出しのたびにワークスペースインスタンス名 (adb-1234567890123456.7.azuredatabricks.net など) とワークスペースユーザーの Databricks 個人用アクセストークンを入力する代わりに、環境変数 (DATABRICKS_HOST や DATABRICKS_TOKEN など) を定義し、それらの環境変数 ({{DATABRICKS_HOST}} や {{DATABRICKS_TOKEN}} など) を HTTPie で使用できます。 HTTPie ブログ上の「環境」を参照してください。
呼び出す REST API 操作に要求本文が必要な場合は、次を行います。
1. [ヘッダー] タブに、Content-Type の名前と値のペアと、REST API 操作に使用できるコンテンツタイプを追加します。たとえば、クラスターに関する情報を一覧表示するには、application/json コンテンツタイプを使用します。
2. [本体] タブで、REST API 操作に使用できる本文の種類を選択します。たとえば、クラスターに関する情報を一覧表示するには、本文の種類として [テキスト]、さらに [JSON] を選択します。
3. 要求本文を入力します。たとえば、指定したクラスターに関する情報を一覧表示するには、次を入力します。
```
{
  "cluster_id": "1234-567890-batch123"
}
```
呼び出す REST API 操作に追加のヘッダーが必要な場合は、[ヘッダー] タブに追加の名前と値のペアとして入力します。たとえば、クラスターに関する情報を一覧表示する場合は、追加のヘッダーは必要ありません。
呼び出す REST API 操作にクエリパラメーターが必要な場合は、[パラメーター] タブに名前と値のペアとして入力します。たとえば、クラスターに関する情報を一覧表示するには、要求本文を使用する代わりに、名前が cluster_id、値が指定したクラスターの ID (1234-567890-batch123 など) であるクエリパラメーターを使用できます。
[送信] をクリックします。応答の詳細は、[応答] タブに表示されます。

HTTPie コマンドラインインターフェイスを使用して Databricks REST API を呼び出す

この例では、HTTPie コマンドラインインターフェイスを使用して、指定された Azure Databricks クラスターに関する情報を一覧表示します。この例では、.netrc ファイルを使用します。

https GET adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get cluster_id=1234-567890-batch123

# Or...

https adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get cluster_id==1234-567890-batch123

# Which is equivalent in curl with jq...
# curl --netrc 'https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get' -d '{ "cluster_id": "1234-567890-patch123" }' | jq .\
# Or...
# curl --netrc 'https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get?cluster_id=1234-567890-patch123' | jq .

ヒント

PyPI の CurliPie パッケージや CurliPie Web アプリなどのツールを使用して、curl を HTTPie 構文に変換できます。

PowerShell を使用して Databricks REST API を呼び出す

この例では、PowerShell のInvoke-RestMethod コマンドレットを使用して、指定された Azure Databricks クラスターに関する情報を一覧表示します。

$Token = 'dapia1b2345678901c23456defa7bcde8fa9'
$ConvertedToken = $Token | ConvertTo-SecureString -AsPlainText -Force

$InstanceID = 'adb-1234567890123456.7.azuredatabricks.net'
$APIVersion = '/api/2.0'
$APICommand = '/clusters/get'
$Uri = "https://$InstanceID$APIVersion$APICommand"

$Body = @{
  'cluster_id' = '1234-567890-batch123'
}

$Response = Invoke-RestMethod `
  -Authentication Bearer `
  -Token $ConvertedToken `
  -Method Get `
  -Uri  $Uri `
  -Body $Body

Write-Output $Response

cluster_id       : 1234-567890-batch123
driver           : ...
spark_context_id : 1234567890123456789
...

ランタイムバージョン文字列

多くの API 呼び出しでは、Databricks ランタイムバージョン文字列を指定する必要があります。このセクションでは、Databricks REST API のバージョン文字列の構造について説明します。

<M>.<F>.x[-cpu][-esr][-gpu][-ml][-photon]-scala<scala-version>

where

M: Databricks Runtime メジャーリリース
F: Databricks Runtime 機能リリース
cpu: CPU バージョン (-ml のみを使用)
esr: 延長サポート
gpu: GPU 対応
ml: 機械学習
photon: Photon
scala-version: Spark のコンパイルに使用された Scala のバージョン。2.10、2.11、または 2.12

例:

7.6.x-gpu-ml-scala2.12 は、Machine Learning 用の Databricks Runtime 7.6 を表し、GPU 対応であり、Scala バージョン 2.12 を使用して Spark バージョン 3.0.1 をコンパイルします。

「サポートされている Azure Databricks Runtime リリースとサポートスケジュール」と「サポートされていないリリース」の表では、Databricks Runtime のバージョンが、ランタイムに含まれる Spark のバージョンにマップされます。

ランタイムバージョンの API を呼び出すことによって、使用可能な Azure Databricks ランタイムバージョンの文字列のリストを取得できます。

Databricks Light

apache-spark.<M>.<F>.x-scala<scala-version>

where

M: Apache Spark メジャーリリース
F: Apache Spark 機能リリース
scala-version: Spark のコンパイルに使用された Scala のバージョン。2.10 または 2.11

たとえば、「 apache-spark-2.4.x-scala2.11 」のように入力します。

Databricks REST API リファレンス

認証

転送率の制限

出力を解析する

互換性

curl を使用して Databricks REST API を呼び出す

クエリ文字列を使用して GET を呼び出す

Python を使用して Databricks REST API を呼び出す

Postman を使用して Databricks REST API を呼び出す

HTTPie を使用して Databricks REST API を呼び出す

HTTPie デスクトップアプリまたは HTTPie Web アプリを使用して Databricks REST API を呼び出す

HTTPie コマンドラインインターフェイスを使用して Databricks REST API を呼び出す

PowerShell を使用して Databricks REST API を呼び出す

ランタイムバージョン文字列

Databricks Light

その他のリソース

その他のリソース

Databricks REST API リファレンス

認証

転送率の制限

出力を解析する

互換性

curl を使用して Databricks REST API を呼び出す

クエリ文字列を使用して GET を呼び出す

Python を使用して Databricks REST API を呼び出す

Postman を使用して Databricks REST API を呼び出す

HTTPie を使用して Databricks REST API を呼び出す

HTTPie デスクトップ アプリまたは HTTPie Web アプリを使用して Databricks REST API を呼び出す

HTTPie コマンド ライン インターフェイスを使用して Databricks REST API を呼び出す

PowerShell を使用して Databricks REST API を呼び出す

ランタイム バージョン文字列

Databricks Light

その他のリソース

その他のリソース

HTTPie デスクトップアプリまたは HTTPie Web アプリを使用して Databricks REST API を呼び出す

HTTPie コマンドラインインターフェイスを使用して Databricks REST API を呼び出す

ランタイムバージョン文字列