Databricks CLI の移行
この記事では、Databricks CLI バージョン 0.18 以前から Databricks CLI バージョン 0.205 以降に移行する方法について説明します。 Databricks CLI バージョン 0.205 以降はパブリック プレビュー段階です。
簡潔にするために、この記事では、Databricks CLI バージョン 0.18 以前を "レガシ" CLI、Databricks CLI バージョン 0.205 以降を "新しい" CLI と呼びます。
レガシおよび新しい CLI の詳細については、次を参照してください。
- レガシ CLI については、「Databricks CLI (レガシ)」を参照してください。
- 新しい CLI については、「Databricks CLI とは」を参照してください。
レガシ CLI をアンインストールする
レガシ CLI がインストールされていて、それをアンインストールする場合は、pip (または、Python のバージョンに応じて pip3) を使用して、次のように uninstall コマンドを実行します。
pip uninstall databricks-cli
新しい CLI をインストールする
新しい CLI をインストールする方法については、「Databricks CLI のインストールまたは更新」を参照してください。
CLI のインストールを確認する
新しい CLI を使用しているかどうかがわからない場合は、このセクションの手順に従って確認し、必要に応じて調整します。 これらの手順を実行する前に、Python 仮想環境、conda 環境、または同様の環境をすべて終了してください。
CLI の既定のインストールのバージョンをチェックするには、次のコマンドを実行します。
databricks -v
バージョン番号が予想したものでない場合は、次のいずれかを実行します。
- 1 つのバージョンの CLI のみを使用する場合: 使用しない以前のバージョンの CLI をすべてアンインストールします。 使用する、残りのバージョンの CLI へのパスがリストされるように、オペレーティング システムの
PATHを更新する必要がある場合があります。 - 複数のバージョンの CLI を引き続き使用する場合: CLI を呼び出すたびに、使用するバージョンの CLI への完全パスを先頭に付加します。
- 複数のバージョンの CLI を引き続き使用するが、最も頻繁に使用するバージョンの CLI への完全パスを毎回先頭に付加しなくても済むようにしたい場合: そのバージョンへの完全パスがオペレーティング システムの
PATHの最初にリストされていることを確認してください。 オペレーティング システムのPATHの最初にリストされていないバージョンの CLI への完全パスは、引き続き先頭に追加する必要があることに注意してください。
オペレーティング システムの PATH を更新するには、次の操作を行います。
macOS または Linux
次のいずれかのコマンドを実行して、
databricksがインストールされているパスをリストします。which -a databricks # Or: where databricksCLI を呼び出すたびに完全パスを先頭に指定せずに使用できるようにしたいインストールへのパスを取得します。 これがどのパスかわからない場合は、各場所への完全パスの後に
-vを付けて実行します。次に例を示します。/usr/local/bin/databricks -v使用するインストールへのパスを
PATHの最初に配置するには、/usr/local/binを使用するパスに置き換えて、次のコマンドを実行します。 このパスの末尾にdatabricksを追加しないでください。 次に例を示します。export PATH="/usr/local/bin:$PATH"現在のターミナル セッションに対して
PATHが正しく設定されたことを確認するには、databricksの後に-vを付けて実行し、バージョン番号をチェックします。databricks -vターミナルを再起動するたびに
PATHでこの設定を行うには、手順 3 の コマンドをシェル初期化ファイルに追加します。 たとえば、Zshell の場合、このファイルは通常~/.zshrcにあります。 Bash の場合、このファイルは通常~/.bashrcにあります。 その他のシェルについては、シェル プロバイダーのドキュメントを参照してください。シェル初期化ファイルを更新した後、更新された
PATH値を適用するには、ターミナルを再起動する必要があります。
Windows
CLI を呼び出すたびに完全パスを先頭に指定せずに使用できるようにしたい
databricksのインストールを右クリックします。[ファイルの場所を開く] をクリックします。
databricksへのパスをメモします (例:C:\Windows)。[スタート] メニューで、「環境変数」を検索します。
[Edit environment variables for your account](アカウントの環境変数の編集) をクリックします。
[User variables for](のユーザー変数)
<username>セクションで Path 変数を選択します。[編集] をクリックします。
新規を選択します。
databricks.exe(C:\Windowsなど) を指定せずに、追加するパスを入力します。[上へ] ボタンを使用して、追加したパスをリストの先頭に移動します。
[OK] をクリックします。
PATHが正しく設定されていることを確認するには、新しいコマンド プロンプトを開き、databricksの後に-vを付けて実行し、バージョン番号をチェックします。databricks -v
追加の認証タイプを使用する
レガシ CLI と新しい CLI では、どちらも Azure Databricks 個人用アクセス トークン認証がサポートされています。 ただし、Databricks では、可能な場合には新しい CLI のみがサポートする他の Azure Databricks 認証タイプを使用することをお勧めします。
Azure Databricks 個人用アクセス トークン認証を使用する必要がある場合、Databricks では、Azure Databricks アカウントまたはワークスペース ユーザーではなく、サービス プリンシパルに関連付けられている認証を使用することをお勧めします。 「サービス プリンシパルを管理する」を参照してください。
新しい CLI では、Azure Databricks 個人用アクセス トークンに加えて、Microsoft Entra ID トークンをサポートします。 Azure Databricks の個人用アクセス トークンの有効期限が 1 日から無期限の間であるのに対して、これらの追加のトークンは、通常は 1 時間で有効期限が切れるので安全性が高くなります。 これは、他のユーザーがアクセスできるバージョン管理システムにトークンが誤ってチェックインされた場合に特に重要です。 また、新しい CLI では、有効期限が切れたときにこれらの追加のトークンを自動的に更新できますが、Azure Databricks 個人用アクセス トークンの更新は手動プロセスであるか、自動化が困難な場合があります。
詳細については、「Databricks CLI の認証」を参照してください。
コマンド グループとコマンドの比較
次の表に、レガシ CLI のコマンド グループと、それに相当する新しい CLI のコマンド グループをリストしています。 CLI 間に大きな違いが存在する場合は、追加の表に、レガシ CLI のコマンドまたはオプションと、それに相当する新しい CLI のコマンドまたはオプションをリストしています。
コマンド グループ
| レガシ コマンド グループ | 新しいコマンド グループ |
|---|---|
cluster-policies |
cluster-policies= すべてのコマンド名は同じです。 |
clusters |
clusters= すべてのコマンド名は同じです。 |
configure |
configure= 「オプションの構成」を参照してください。 |
fs |
fs= 「fs コマンド」を参照してください。 |
groups |
groups= 「groups コマンド」を参照してください。 |
instance-pools |
instance-pools= すべてのコマンド名は同じです。 |
jobs |
jobs= すべてのコマンド名は同じです。 |
libraries |
libraries= list を除くすべてのコマンド名は同じです。 list コマンドは使用できなくなりました。代わりに all-cluster-statuses または cluster-status コマンドを使用してください。 |
pipelines |
pipelines= 「pipelines コマンド」参照してください。 |
repos |
repos= すべてのコマンド名は同じです。 |
runs |
jobs= 「runs コマンド」を参照してください。 |
secrets |
secrets= 「secrets コマンド」を参照してください。 |
stack |
新しい CLI では使用できません。 Databricks では、代わりに Databricks Terraform プロバイダーを使用することをお勧めします。 |
tokens |
tokens= 「tokens コマンド」を参照してください。 |
unity-catalog |
各種。 「unity-catalog コマンド グループ」を参照してください。 |
workspace |
workspace= 「workspace コマンド」を参照してください。 |
configure オプション
| レガシ オプション | 新しいオプション |
|---|---|
-o |
レガシ CLI では、OAuth 認証に -o が使用されます。 新しい CLI では、-o を再利用して、CLI 出力がテキスト形式か JSON 形式かを指定します。 Azure Databricks には適用されません。 |
--oauth |
Azure Databricks には適用されません。 |
-s または --scope |
Azure Databricks には適用されません。 |
-t または --token |
-t または --token (同じ) |
-f または --token-file |
新しい CLI では使用できません。 |
--host |
--host (同じ) |
--aad-token |
--host を使用して、プロンプトが表示されたら、Azure Databricks 個人用アクセス トークンではなく Microsoft Entra ID トークンを指定します。 |
--insecure |
新しい CLI では使用できません。 |
--jobs-api-version |
新しい CLI では使用できません。 新しい CLI では、Jobs API 2.1 のみが使用されます。 レガシ Jobs API 2.0 を呼び出すには、レガシ CLI を使用し、「ジョブ CLI (レガシ)」を参照してください。 |
--debug |
新しい CLI でのデバッグとログ記録については、「デバッグ モード」を参照してください。 |
--profile |
--profile (同じ) または -p |
-h または --help |
-h または --help (同じ) |
fs コマンド
レガシ CLI の fs コマンドはすべて新しい CLI でも同じですが、fs mv を除きます。これは、新しい CLI では使用できません。
| レガシ コマンド | 新しいコマンド |
|---|---|
fs cat |
fs cat (同じ) |
fs cp |
fs cp (同じ) |
fs ls |
fs ls (同じ) |
fs mkdirs |
fs mkdir |
fs mv |
新しい CLI では使用できません。 |
fs rm |
fs rm (同じ) |
groups コマンド
| レガシ コマンド | 新しいコマンド |
|---|---|
groups add-member |
groups patch |
groups create |
groups create (同じ) |
groups delete |
groups delete (同じ) |
groups list |
groups list (同じ) |
groups list-members |
groups list |
groups list-parents |
groups list |
groups remove-member |
groups patch |
pipelines コマンド
| レガシ コマンド | 新しいコマンド |
|---|---|
pipelines create |
pipelines create (同じ) |
pipelines delete |
pipelines delete (同じ) |
pipelines deploy |
pipelines create |
pipelines edit |
pipelines update |
pipelines get |
pipelines get (同じ) |
pipelines list |
pipelines list-pipeline-events または pipelines list-pipelines または pipelines list-updates |
pipelines reset |
pipelines reset (同じ) |
pipelines start |
pipelines start update |
pipelines stop |
pipelines stop (同じ) |
pipelines update |
pipelines update (同じ) |
runs コマンド
| レガシ コマンド | 新しいコマンド |
|---|---|
runs cancel |
jobs cancel-run |
runs get |
jobs get-run |
runs get-output |
jobs get-run-output |
runs list |
jobs list-runs |
runs submit |
jobs submit |
secrets コマンド
| レガシ コマンド | 新しいコマンド |
|---|---|
secrets create-scope |
secrets create-scope (同じ) |
secrets delete |
secrets delete-secret |
secrets delete-acl |
secrets delete-acl (同じ) |
secrets delete-scope |
secrets delete-scope (同じ) |
secrets get-acl |
secrets get-acl (同じ) |
secrets list |
secrets list-secrets |
secrets list-acls |
secrets list-acls (同じ) |
secrets list-scopes |
secrets list-scopes (同じ) |
secrets put |
secrets put-secret |
secrets put-acl |
secrets put-acl (同じ) |
secrets write |
secrets put-secret |
secrets write-acl |
secrets put-acl |
tokens コマンド
| レガシ コマンド | 新しいコマンド |
|---|---|
tokens create |
tokens create (同じ) |
tokens list |
tokens list (同じ) |
tokens revoke |
tokens delete |
unity-catalog コマンド グループ
レガシ CLI の unity-catalog <command> は、新しい CLI では <command> だけになります。
| レガシ コマンド グループ | 新しいコマンド グループ |
|---|---|
unity-catalog catalogs |
catalogs (同じ、ただし unity-catalog は削除) |
unity-catalog external-locations |
external-locations (同じ、ただし unity-catalog は削除) |
unity-catalog lineage |
新しい CLI では使用できません。 「Data Lineage REST API を使用して系列を取得する」を参照してください。 |
unity-catalog metastores |
metastores (同じ、ただし unity-catalog は削除) |
unity-catalog permissions |
grants |
unity-catalog providers |
providers (同じ、ただし unity-catalog は削除) |
unity-catalog recipients |
recipients (同じ、ただし unity-catalog は削除) |
unity-catalog schemas |
schemas (同じ、ただし unity-catalog は削除) |
unity-catalog shares |
shares (同じ、ただし unity-catalog は削除) |
unity-catalog storage-credentials |
storage-credentials (同じ、ただし unity-catalog は削除) |
unity-catalog tables |
tables (同じ、ただし unity-catalog は削除) |
workspace コマンド
| レガシ コマンド | 新しいコマンド |
|---|---|
workspace delete |
workspace delete (同じ) |
workspace export |
workspace export (同じ) |
workspace export-dir |
workspace export |
workspace import |
workspace import (同じ) |
workspace import-dir |
workspace import |
workspace list |
workspace list (同じ) |
workspace ls |
workspace list |
workspace mkdirs |
workspace mkdirs (同じ) |
workspace rm |
workspace delete |
既定の引数と位置引数
ほとんどの新しい CLI コマンドには、付随するオプションがない、既定の引数が少なくとも 1 つあります。 一部の新しい CLI コマンドには、特定の順序で指定する必要があり、付随するオプションがない複数の位置引数があります。 これは、ほとんどのコマンドですべての引数にオプションを指定する必要があるレガシ CLI とは異なります。 たとえば、新しい CLI の clusters get コマンドは、クラスター ID を既定の引数として受け取ります。 しかし、レガシ CLI の clusers get コマンドでは、クラスター ID とともに --cluster-id オプションを指定する必要があります。 次に例を示します。
レガシ CLI の場合:
# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d
# This does **not** work with the legacy CLI - "Error:
# Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d
新しい CLI の場合:
# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d
# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d
別の例として、新しい CLI の grants get コマンドは、2 つの既定の引数を受け取ります。セキュリティ保護可能な型と、その後に続くセキュリティ保護可能なフル ネームです。 しかし、レガシ CLI の unity-catalog permissions get コマンドでは、セキュリティ保護可能なフル ネームとともに --<securable-type> オプションを指定する必要があります。 次に例を示します。
レガシ CLI の場合:
databricks unity-catalog permissions get --schema main.default
新しい CLI の場合:
# This works with the new CLI.
databricks grants get schema main.default
# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default
デバッグ モード
レガシ CLI には、エラー時に完全なスタック トレースを表示するための --debug オプションが用意されています。 新しい CLI の場合、--debug オプションは認識されません。 代わりに、次の手順を使用します。
<path>で指定されたファイルにログ情報を書き込むには、--log-file <path>を使用します。 このオプションを指定しない場合、ログ情報は stderr に出力されます。--log-fileだけを指定して--log-levelを指定しない場合、ログ情報はファイルに書き込まれなくなります。- ログに記録する情報の形式を指定するには、
--log-format <type>を使用します。<type>には、text(指定しない場合の既定値) またはjsonを指定できます。 - ログに記録される情報のレベルを指定するには、
--log-level <format>を使用します。 使用できる値はdisabled(指定しない場合の既定値)、trace、debug、info、warn、およびerrorです。
レガシ CLI の場合、次の例は、エラー時の完全なスタック トレースを示しています。
databricks fs ls / --debug
# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"
新しい CLI の場合、次の例では、完全なスタック トレースを現在の作業ディレクトリ内の new-cli-errors.log という名前のファイルに記録します。 スタック トレースは、JSON 形式でファイルに書き込まれます。
databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace
# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)
一般的な質問
このセクションでは、レガシから新しい CLI への移行に関する一般的な質問をリストしています。
レガシ CLI はどのような状況ですか?
レガシ CLI は引き続き使用できますが、重要な更新プログラム以外は提供されません。 レガシ CLI のドキュメントには、これが反映されています。 Databricks では、ユーザーができるだけ早く新しい CLI に移行することをお勧めします。
レガシ CLI は常に試験段階の状態であり、Databricks はレガシ CLI の新機能に取り組む予定はなく、レガシ CLI は Databricks のサポート チャネルではサポートされません。
レガシ CLI はいつ非推奨になりますか?
レガシ CLI は常に試験段階の状態であり、Databricks はレガシ CLI の新機能に取り組む予定はなく、レガシ CLI は Databricks のサポート チャネルではサポートされません。
Databricks は、レガシ CLI を非推奨にする日付やタイムラインを設定していません。 ただし、Databricks では、ユーザーができるだけ早く新しい CLI に移行することをお勧めします。
新しい CLI が一般提供 (GA) としてリリースされるのはいつですか?
新しい CLI を GA としてリリースするリリース日やタイムラインは設定されていません。 これは、パブリック プレビュー中に Databricks がユーザーから受け取るフィードバックによって変わります。
レガシ CLI と新しい CLI の主な違いは何ですか?
- レガシ CLI は Python パッケージとしてリリースされました。 新しい CLI はスタンドアロンの実行可能ファイルとしてリリースされ、ランタイムの依存関係をインストールする必要はありません。
- 新しい CLI では、Databricks REST API が完全にカバーされています。 レガシ CLI ではされていません。
- 新しい CLI は、パブリック プレビューとして使用できます。 レガシ CLI は試験段階状態のままです。
新しい CLI には、レガシ CLI と完全に同等の機能が備わっていますか?
新しい CLI では、レガシ CLI のほぼすべてのコマンドをカバーしています。 ただし、新しい CLI には、レガシ CLI の stacks コマンド グループがないので注意してください。 また、unity-catalog や runs などのいくつかのレガシ CLI コマンド グループは、新しい CLI で新しいコマンド グループにリファクタリングされています。 移行ガイダンスについては、この記事で前述した情報を参照してください。
レガシ CLI から新しい CLI への移行方法
移行ガイダンスについては、この記事で前述した情報を参照してください。 新しい CLI はレガシ CLI のドロップイン置換ではなく、レガシ CLI から新しい CLI に移行するには、いくつかのセットアップが必要であることに注意してください。
レガシ CLI と新しい CLI を同じマシン上にインストールすることはできますか?
はい。 レガシ CLI と新しい CLI を同じマシン上にインストールすることはできますが、異なるディレクトリに配置する必要があります。 実行可能ファイルの名前はどちらも databricks であるため、マシンの PATH を構成して、どの実行可能ファイルが既定で実行されるかを制御する必要があります。 新しい CLI を実行する必要があるにもかかわらず、何らかの理由で誤って代わりにレガシ CLI を実行した場合、既定では、レガシ CLI は同じ引数を使用して新しい CLI を実行し、次の警告メッセージを表示します。
Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>
Because both are installed and available in PATH,
I assume you are trying to run the newer version.
If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.
Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>
上記の警告メッセージに示すように、DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION 環境変数を 1 に設定することで、この動作を無効にし、代わりにレガシ CLI を実行できます。
ヘルプを参照する
レガシ CLI から新しい CLI への移行に関するヘルプが必要な場合は、次のリソースを参照してください。