Databricks CLI (レガシ)

  • [アーティクル]

重要

このドキュメントは廃止され、更新されない可能性があります。

Databricks では、バージョン 0.18 以前のレガシ Databricks CLI ではなく、Databricks CLI バージョン 0.205 以降を使用することをお勧めします。 Databricks ではバージョン 0.18 以前の Databricks CLI をサポートしていません。 Databricks CLI バージョン 0.205 以降の詳細については、「Databricks CLI について」を参照してください。

Databricks CLI バージョン 0.18 以前から Databricks CLI バージョン 0.205 以降に移行するには、「Databricks CLI の移行」を参照してください。

レガシ Databricks CLI は 試験状態です。 現時点では、Databricks でレガシ Databricks CLI の新機能は計画されていません。

Databricks サポート チャネルでは、レガシ Databricks CLI がサポートされていません。 フィードバックの提供、質問、問題の報告を行うには、GitHub の Command Line Interface for Databricks リポジトリの [Issues] タブを使用します。

レガシ Databricks コマンド ライン インターフェイス (レガシ Databricks CLI とも呼ばれます) は、ターミナル、コマンド プロンプト、または自動化スクリプトから Azure Databricks プラットフォームを自動化するための使いやすいインターフェイスを提供するユーティリティです。

必要条件

  • Python 3 - 3.6 以降
  • Python 2 - 2.7.9 以降

重要

macOS の場合、既定の Python 2 インストールでは TLSv1_2 プロトコルが実装されないため、この Python インストールでレガシ Databricks CLI を実行すると、次のエラーが発生します: AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'。 ssl.PROTOCOL_TLSv1_2 のある Python のバージョンをインストールするには、Homebrew を使用してください。

制限事項

ファイアウォールが有効なストレージ コンテナーでレガシ Databricks CLI を使用することはサポートされていません。 Databricks では、Databricks Connect または az storage の使用が推奨されています。

CLI を設定する

このセクションでは、レガシ Databricks CLI を設定する方法について説明します。

CLI をインストールまたは更新する

このセクションでは、レガシ Databricks CLI を実行するために開発用マシンをインストールまたは更新する方法について説明します。

CLI をインストールする

お使いの Python インストールに適したバージョンの pip を使用して、pip install databricks-cli を実行します。

pip install databricks-cli

CLI の更新

お使いの Python インストールに適したバージョンの pip を使用して、pip install databricks-cli --upgrade を実行します。

pip install databricks-cli --upgrade

現在インストールされているレガシ Databricks CLI のバージョンを一覧表示するには databricks --version を実行します。

databricks --version

認証を設定する

レガシ Databricks CLI コマンドを実行する前に、レガシ Databricks CLI と Azure Databricks の間で認証を設定する必要があります。 このセクションでは、レガシ Databricks CLI に対して認証を設定する方法について説明します。

レガシ Databricks CLI を使って認証するには、Databricks 個人用アクセス トークンまたは Microsoft Entra ID (旧称 Azure Active Directory) トークンを使用できます。

Note

セキュリティのベスト プラクティスとして、自動化ツール、システム、スクリプト、アプリを使用して認証する場合、Databricks では、ワークスペース ユーザーではなくサービス プリンシパルに属する個人用アクセス トークンを使用することを推奨しています。 サービス プリンシパルのトークンを作成するには、「サービス プリンシパルのトークンを管理する」をご覧ください。

Microsoft Entra ID (旧称 Azure Active Directory) トークンを使って認証を設定する

Microsoft Entra ID トークンを使用してレガシ Databricks CLI を構成するには、Microsoft Entra ID (旧称 Azure Active Directory) トークンを生成し、それを環境変数 DATABRICKS_AAD_TOKEN 内に保存します。

次のコマンドを実行します。

databricks configure --aad-token

コマンドにより、次のプロンプトが表示されます。

Databricks Host (should begin with https://):

ワークスペースごとの URL を https://adb-<workspace-id>.<random-number>.azuredatabricks.net の形式で入力します。 ワークスペースごとの URL を取得するには、「ワークスペースごとの URL」を参照してください。

プロンプトを完了すると、アクセス資格情報は、Linux または macOS では ~/.databrickscfg、Windows では %USERPROFILE%\.databrickscfg というファイルに保存されます。 このファイルには、既定のプロファイル エントリが含まれています。

[DEFAULT]
host = <workspace-URL>
token = <Azure-AD-token>

.databrickscfg ファイルが既に存在する場合、そのファイルの DEFAULT 構成プロファイルは新しいデータで上書きされます。 代わりに別の名前で構成プロファイルを作成するには、「接続プロファイル」を参照してください。

Databricks 個人用アクセス トークンを使用して認証を設定する

個人用アクセス トークンを使用するようにレガシ Databricks CLI を構成するには、次のコマンドを実行します。

databricks configure --token

このコマンドは、プロンプトを発行して開始します。

Databricks Host (should begin with https://):

ワークスペースごとの URL を https://adb-<workspace-id>.<random-number>.azuredatabricks.net の形式で入力します。 ワークスペースごとの URL を取得するには、「ワークスペースごとの URL」を参照してください。

このコマンドは、個人用アクセス トークンを入力するプロンプトを発行して続行します。

Token:

プロンプトを完了すると、アクセス資格情報は、Linux または macOS では ~/.databrickscfg、Windows では %USERPROFILE%\.databrickscfg というファイルに保存されます。 このファイルには、既定のプロファイル エントリが含まれています。

[DEFAULT]
host = <workspace-URL>
token = <personal-access-token>

.databrickscfg ファイルが既に存在する場合、そのファイルの DEFAULT 構成プロファイルは新しいデータで上書きされます。 代わりに別の名前で構成プロファイルを作成するには、「接続プロファイル」を参照してください。

CLI 0.8.1 以降では、環境変数 DATABRICKS_CONFIG_FILE を設定することによって、このファイルのパスを変更できます。

Linux または MacOS
export DATABRICKS_CONFIG_FILE=<path-to-file>
Windows
setx DATABRICKS_CONFIG_FILE "<path-to-file>" /M

重要

CLI 0.17.2 以降の CLI は、.netrc ファイルでは動作しません。 .netrc ファイルを他の目的でご利用の環境に含めることができますが、CLI ではその .netrc ファイルは使用されません。

CLI 0.8.0 以降では、以下の Azure Databricks 環境変数がサポートされています。

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN

環境変数の設定は、構成ファイルの設定よりも優先されます。

認証セットアップのテスト

認証が正しく設定されているかどうかを確認するには、次のようなコマンドを実行します。

databricks fs ls dbfs:/

成功した場合、このコマンドは、DEFAULT プロファイルに関連付けられているワークスペースの DBFS ルート内のファイルとディレクトリを一覧表示します。

接続プロファイル

レガシ Databricks CLI 構成では、複数の接続プロファイルがサポートされています。 レガシ Databricks CLI の同じインストールを使用して、複数の Azure Databricks ワークスペースで API 呼び出しを行うことができます。

接続プロファイルを追加するには、プロファイルに一意の名前を指定します。

databricks configure [--token | --aad-token] --profile <profile-name>

この .databrickscfg ファイルには、対応するプロファイル エントリが含まれています。

[<profile-name>]
host = <workspace-URL>
token = <token>

接続プロファイルを使用するには:

databricks <group> <command> --profile <profile-name>

--profile <profile-name> が指定されていない場合、既定のプロファイルが使用されます。 既定のプロファイルが見つからない場合は、既定のプロファイルを使用して CLI を構成するように求められます。

接続プロファイルをテストする

接続プロファイルが正しく設定されているかどうかを確認するには、接続プロファイル名のいずれかを指定して次のようなコマンドを実行します。

databricks fs ls dbfs:/ --profile <profile-name>

成功した場合、このコマンドは、指定された接続プロファイルのワークスペースの DBFS ルート内のファイルとディレクトリを一覧表示します。 テストする接続プロファイルごとに、このコマンドを実行します。

使用可能なプロファイルを表示するには、.databrickscfg ファイルを参照してください。

CLI の使用

このセクションでは、レガシ Databricks CLI ヘルプの取得方法、レガシ Databricks CLI 出力の解析方法、および各コマンド グループのコマンドの呼び出し方法について説明します。

CLI コマンド グループのヘルプを表示する

--help または -h オプションを使用すると、任意のコマンド グループのサブコマンドが一覧表示されます。 たとえば、DBFS CLI サブコマンドを一覧表示するには、次のようにします。

databricks fs -h

CLI サブコマンドのヘルプを表示する

サブコマンドのヘルプを一覧表示する場合は、--help または -h オプションを使用します。 たとえば、DBFS のファイルのコピー サブコマンドのヘルプを表示します。

databricks fs cp -h

alias コマンド グループ

場合によっては、各レガシ Databricks CLI 呼び出しの前にコマンド グループの名前を付けるのは不便です (例: レガシ Databricks CLI の databricks workspace ls)。 レガシ Databricks CLI を簡単に使用できるようにするために、コマンド グループに短いコマンドの別名を付けることができます。 たとえば、Bourne Again シェルで databricks workspace ls を dw ls に短縮し、適切な bash プロファイルに alias dw="databricks workspace" を追加できます。 通常、このファイルは ~/.bash_profile にあります。

ヒント

レガシ Databricks CLI では既に、databricks fs に dbfs という別名が付けられており、databricks fs ls と dbfs ls は同等です。

jq を使用して CLI 出力を解析する

一部のレガシ Databricks CLI コマンドは、API エンドポイントからの JSON 応答を出力します。 場合によっては、JSON の一部を解析して他のコマンドにパイプすると便利です。 たとえば、ジョブ定義をコピーするには、ジョブ取得コマンドの settings フィールドを取得し、それをジョブ作成コマンドの引数として使用する必要があります。 このような場合は、jq ユーティリティを使用することをお勧めします。

たとえば、次のコマンドは、ID が 233 のジョブの設定を出力します。

databricks jobs list --output JSON | jq '.jobs[] | select(.job_id == 233) | .settings'

出力:

{
  "name": "Quickstart",
  "new_cluster": {
    "spark_version": "7.5.x-scala2.12",
    "spark_env_vars": {
      "PYSPARK_PYTHON": "/databricks/python3/bin/python3"
    },
    "num_workers": 8,
    ...
  },
  "email_notifications": {},
  "timeout_seconds": 0,
  "notebook_task": {
    "notebook_path": "/Quickstart"
  },
  "max_concurrent_runs": 1
}

別の例として、次のコマンドは、ワークスペース内の使用可能なすべてのクラスターの名前と ID のみを出力します。

databricks clusters list --output JSON | jq '[ .clusters[] | { name: .cluster_name, id: .cluster_id } ]'

出力:

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

jq は、たとえば macOS では Homebrew を使用して brew install jq で、Windows では Chocolatey を使用して choco install jq でインストールできます。 jq の詳細については、jq のマニュアルを参照してください。

JSON 文字列パラメーター

文字列パラメーターの処理は、オペレーティング システムによって異なります。

Linux または MacOS

JSON 文字列パラメーターは、単一引用符で囲む必要があります。 次に例を示します。

'["20180505", "alantest"]'

Windows

JSON 文字列パラメーターは二重引用符で囲む必要があり、文字列内の引用符文字の前に \ を付ける必要があります。 次に例を示します。

"[\"20180505\", \"alantest\"]"

トラブルシューティング

以下のセクションでは、レガシ Databricks CLI に関する一般的な問題のトラブルシューティングに関するヒントを提供します。

databricks configure での EOF の使用が機能しない

Databricks CLI 0.12.0 以降では、databricks configure コマンドにパラメーターを渡すために、スクリプトでファイル終了 (EOF) シーケンスを使用することはできません。 たとえば、次のスクリプトを実行すると、Databricks CLI はパラメーターを無視し、エラー メッセージはスローされません。

# Do not do this.
databricksUrl=<per-workspace-url>
databricksToken=<personal-access-token-or-Azure-AD-token>

databricks configure --token << EOF
$databricksUrl
$databricksToken
EOF

この問題を解決するには、次のいずれかの操作を行います。

  • 「認証の設定」で説明されているように、その他のプログラム構成オプションのいずれかを使用します。
  • 「認証の設定」で説明されているように、.databrickscfg ファイルに host と token の値を手動で追加します。
  • Databricks CLI のインストールを 0.11.0 以下にダウングレードし、スクリプトを再実行します。

CLI コマンド