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 の詳細については、以下を参照してください。
- レガシ CLI 用の Databricks CLI (レガシ)。
- Databricks CLI とは何ですか? 新しい CLI の場合。
従来の CLI をアンインストールする
レガシー CLI がインストールされていて、それをアンインストールする場合は、次のように pip
(Python のバージョンによっては pip3
を使用) して uninstall
コマンドを実行します。
pip uninstall databricks-cli
新しいCLIのインストール
新しい CLI をインストールする方法については、「 Databricks CLI のインストールまたは更新」を参照してください。
CLI のインストールを確認する
新しい CLI を使用しているかどうかわからない場合は、このセクションの手順に従って確認し、必要に応じて調整します。 これらの手順を実行する前に、Python 仮想環境、 conda
環境、または同様の環境を終了してください。
CLI のデフォルト・インストールのバージョンを確認するには、次のコマンドを実行します。
databricks -v
バージョン番号が期待どおりでない場合は、次のいずれかを実行してください。
- CLI の 1 つのバージョンのみを使用する場合 : 使用しなくなった以前のバージョンの CLI をすべてアンインストールします。 オペレーティング・システムの
PATH
を更新して、使用する CLI の残りのバージョンへのパスがリストされるようにすることが必要な場合があります。 - 複数のバージョンの CLI を引き続き使用する場合 : CLI へのすべての呼び出しに、使用する CLI のバージョンへのフルパスを付加します。
- 複数のバージョンの CLI を引き続き使用するが、最も頻繁に使用する CLI のバージョンへのフルパスを先頭に付けたくない場合は 、そのバージョンへのフルパスがオペレーティングシステムの
PATH
の最初にリストされていることを確認してください。 オペレーティングシステムのPATH
で最初にリストされていないCLIのバージョンへのフルパスを先頭に追加する必要があることに注意してください。
オペレーティング システムの PATH
を更新するには、次の手順を実行します。
- MacOS or Linux
- Windows
-
List the paths where
databricks
is installed by running one of the following commands:Bashwhich -a databricks
# Or:
where databricks -
Get the path to the installation that you want to use without prepending the full path to each and every call to the CLI. If you are not sure which path this is, run the full path to each location, followed by
-v
, for example:Bash/usr/local/bin/databricks -v
-
To put the path to the installation that you want to use first in your
PATH
, run the following command, replacing/usr/local/bin
with the path that you want to use. Do not adddatabricks
to the end of this path. For example:Bashexport PATH="/usr/local/bin:$PATH"
-
To verify that the
PATH
was set correctly for the current terminal session, rundatabricks
followed by-v
and check the version number:Bashdatabricks -v
-
To have the
PATH
set this way every time you restart your terminal, add the command from step 3 to your shell initialization file. For example, for Zshell, this file is typically located at~/.zshrc
. For Bash, this file is typically located at~/.bashrc
. For other shells, see your shell provider’s documentation. -
After you update your shell initialization file, you must restart your terminal to apply the updated
PATH
value.
-
Right-click the installation of
databricks
that you want to use without prepending the full path to each and every call to the CLI. -
Click Open file location.
-
Note the path to
databricks
, for exampleC:\Windows
. -
On the Start menu, search for Environment variables.
-
Click Edit environment variables for your account.
-
Select the Path variable in the User variables for
<username>
section. -
Click Edit.
-
Click New.
-
Enter the path that you want to add, without
databricks.exe
(such asC:\Windows
). -
Use the Move Up button to move the path that you just added to the beginning of the list.
-
Click OK.
-
To verify that the
PATH
was set correctly, open a new Command Prompt, rundatabricks
followed by-v
, and check the version number:Bashdatabricks -v
追加の認証タイプを使用する
従来の CLI と新しい CLI はどちらも Databricks パーソナル アクセス トークン認証をサポートしています。 ただし、Databricks では、可能であれば、新しい CLI のみがサポートする他の Databricks 認証の種類を使用することをお勧めします。
Databricks個人用アクセス トークン認証を使用する必要がある場合は、Databricks アカウントまたはワークスペース ユーザーではなく、サービスプリンシパルに関連付けられている認証を使用することをお勧めしますDatabricks。Manage サービスプリンシパルを参照してください。
新しい CLI では、Databricks の個人用アクセス トークンに加えて、OAuth トークンがサポートされています。 これらの追加トークンは、通常 1 時間で期限切れになるため、より安全ですが、Databricks の個人用アクセス トークンは 1 日から無期限まで有効です。 これは、トークンが誤ってバージョン管理システムにチェックインされ、他のユーザーがアクセスできる場合に特に重要です。 また、新しい CLI では、これらの追加のトークンの有効期限が切れたときに自動的に更新できますが、Databricks の個人用アクセス トークンの更新は手動のプロセスであるか、自動化が難しい場合があります。
詳細については、Databricks CLIの認証を参照してください。
コマンド グループとコマンドの比較
次の表に、従来の CLI コマンド グループと、それに対応する新しい CLI コマンド グループの一覧を示します。 CLI 間に大きな違いがある場合は、追加の表に、従来の CLI コマンドまたはオプションと、それらに匹敵する新しい CLI コマンドまたはオプションが一覧表示されます。
コマンド グループ
レガシーコマンドグループ | 新しいコマンドグループ |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 新しい CLI では使用できません。 Databricks では、代わりに Databricks Terraform プロバイダー を使用することをお勧めします。 |
|
|
| 諸。 |
|
|
configure
オプション
レガシーオプション | 新しいオプション |
---|---|
| 従来の CLI では、OAuth 認証に |
| 新しい CLI の OAuth については、 OAuth マシン間 (M2M) 認証 または OAuth ユーザー間 (U2M) 認証を参照してください。 |
| 新しい CLI の OAuth については、 OAuth マシン間 (M2M) 認証 または OAuth ユーザー間 (U2M) 認証を参照してください。 |
|
|
| 新しい CLI では使用できません。 |
|
|
|
|
| 新しい CLI では使用できません。 |
| 新しい CLI では使用できません。 新しい CLI は Jobs API 2.1 のみを使用します。 レガシ ジョブ API 2.0 を呼び出すには、レガシ CLI を使用し、「 Databricks CLI (レガシ)」を参照してください。 |
| 新しい CLI でのデバッグとロギングについては、 デバッグモードを参照してください。 |
|
|
|
|
fs
コマンド
従来の CLI の fs
コマンドは、新しい CLI で使用できない fs mv
を除き、新しい CLI でも同じです。
レガシーコマンド | 新しいコマンド |
---|---|
|
|
|
|
|
|
|
|
| 新しい CLI では使用できません。 |
|
|
groups
コマンド
レガシーコマンド | 新しいコマンド |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
pipelines
コマンド
レガシーコマンド | 新しいコマンド |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
runs
コマンド
レガシーコマンド | 新しいコマンド |
---|---|
|
|
|
|
|
|
|
|
|
|
secrets
コマンド
レガシーコマンド | 新しいコマンド |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
tokens
コマンド
レガシーコマンド | 新しいコマンド |
---|---|
|
|
|
|
|
|
unity-catalog
コマンド グループ
unity-catalog <command>
従来の CLI では、新しい CLI では <command>
になります。
レガシーコマンドグループ | 新しいコマンドグループ |
---|---|
|
|
|
|
| 新しい CLI では使用できません。 データリネージ REST APIを使用したリネージの取得を参照してください。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
workspace
コマンド
レガシーコマンド | 新しいコマンド |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
デフォルト引数と位置引数
新しい CLI コマンドのほとんどには、オプションが付属しないデフォルトの引数が少なくとも 1 つあります。 一部の新しい CLI コマンドには、特定の順序で指定する必要があり、付随するオプションがない 2 つ以上の位置引数があります。 これは、ほとんどのコマンドですべての引数にオプションを指定する必要がある従来の 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
オプションは認識されません。 代わりに、次のオプションを使用してください。
--log-file <path>
を使用して、<path>
で指定されたファイルにログ情報を書き込みます。このオプションを指定しない場合、ログ情報は stderr に出力されます。--log-level
を指定せずに--log-file
を指定すると、ログ情報はファイルに書き込まれません。--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 は引き続き使用できますが、重要でない更新は受信されていません。 従来の CLI ドキュメントには、このことが反映されています。Databricks では、できるだけ早く新しい CLI に移行することをお勧めします。
CLIレガシーDatabricks CLICLIは常に 実験的な 状態にあり、レガシー の新機能は機能しない予定 という免責事項があり、レガシー はDatabricks サポートチャンネルを通じてサポートされていません。
従来の CLI はいつ廃止されますか?
CLIレガシーDatabricks CLICLIは常に 実験的な 状態にあり、レガシー の新機能は機能しない予定 という免責事項があり、レガシー はDatabricks サポートチャンネルを通じてサポートされていません。
Databricks は、従来の CLI を廃止する日付やタイムラインを確立していません。 ただし、Databricks では、できるだけ早く新しい CLI に移行することをお勧めします。
新しい CLI はいつ一般提供 (GA) としてリリースされますか?
新しい CLI を GA としてリリースするリリース日やスケジュールは未定です。 これは、Databricks がパブリック プレビュー中にユーザーから受け取るフィードバックによって異なります。
レガシーCLIと新しいCLIの主な違いは何ですか?
- 従来の CLI は Python パッケージとしてリリースされました。 新しい CLI はスタンドアロンの実行可能ファイルとしてリリースされ、ランタイム依存関係をインストールする必要はありません。
- 新しい CLI は、 Databricks REST APIsを完全にカバーしています。 従来の CLI ではそうではありません。
- 新しい CLI は、パブリック プレビューとして利用できます。 レガシー CLI は Experimental 状態のままです。
新しいCLIは、従来のCLIと同等の機能を備えていますか?
新しい CLI は、従来の CLI のほぼすべてのコマンドに対応しています。 ただし、新しい CLI には特に欠けているのは、従来の CLI の stacks
コマンド グループです。 また、 unity-catalog
や runs
などのいくつかのレガシー 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 への移行に関するヘルプについては、次のリソースを参照してください。