Amazon
Web Services
Microsoft Azure
Google Cloud PlatformCLI Databricks 移行
この記事では、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 用。
レガシー CLI をアンインストールする
レガシーCLIがインストールされていて、それをアンインストールする場合は、次のように pip (またはPythonのバージョンによっては pip3)を使用して uninstall コマンドを実行します。
pip uninstall databricks-cli
新しい CLI をインストールする
新しい CLI をインストールする方法については、「 Databricks CLI のインストールまたは更新」を参照してください。
CLI のインストールを確認する
新しい CLI を使用しているかどうかわからない場合は、このセクションの手順に従って確認し、必要に応じて調整します。 これらの手順を実行する前に、Python 仮想環境、 conda 環境、または同様の環境を終了してください。
CLI のデフォルト インストールのバージョンを確認するには、次のコマンドを実行します。
databricks -v
バージョン番号が予期したとおりでない場合は、次のいずれかの操作を行います。
CLI の 1 つのバージョンのみを使用する場合: 使用しなくなった以前のバージョンの CLI をすべてアンインストールします。使用する CLI の残りのバージョンへのパスがリストされるように、オペレーティング・システムの
PATHを更新する必要がある場合があります。複数のバージョンの CLI を引き続き使用する場合: CLI へのすべての呼び出しに使用する CLI のバージョンへのフル パスを先頭に追加します。
複数のバージョンの CLI を引き続き使用するが、最も頻繁に使用する CLI のバージョンへのフルパスを先頭に付けたままにしたくない場合は、そのバージョンへのフルパスがオペレーティングシステムの
PATHの最初にリストされていることを確認します。 オペレーティング システムのPATHの最初にリストされていないバージョンの CLI へのフル パスを先頭に追加する必要があることに注意してください。
オペレーティングシステムの PATHを更新するには、次の手順を実行します。
次のいずれかのコマンドを実行して、
databricksがインストールされているパスを一覧表示します。which -a databricks # Or: where databricks
CLI へのすべての呼び出しへのフルパスを先頭に追加せずに、使用するインストールへのパスを取得します。 これがどのパスであるかわからない場合は、各場所への完全なパスを実行してから、次のように
-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値を適用する必要があります。
使用する
databricksのインストールを右クリックし、CLI へのすべての呼び出しの先頭にフルパスを付けずに右クリックします。[ ファイルの場所を開く] をクリックします。
databricksへのパス (C:\Windowsなど) に注意してください。[ スタート ] メニューで、 環境変数を検索します。
[ アカウントの環境変数の編集] をクリックします。
[
<username>のユーザー変数] セクションで Path 変数を選択します。[編集] をクリックします。
[ 新規] をクリックします。
追加するパスを
databricks.exeなしで入力します(C:\Windowsなど)。[ 上へ移動 ] ボタンを使用して、追加したパスをリストの先頭に移動します。
OK をクリックします。
PATHが正しく設定されたことを確認するには、新しいコマンド プロンプトを開き、databricksを実行してから-vを実行し、バージョン番号を確認します。databricks -v
追加の認証の種類を使用する
レガシ CLI と新しい CLI はどちらも Databricks 個人用アクセス トークン認証をサポートします。 ただし、Databricks では、可能であれば、新しい CLI のみがサポートする他の Databricks 認証の種類を使用することをお勧めします。
Databricks個人用アクセス トークン認証を使用する必要がある場合、 Databricks 、 Databricksまたはワークスペース ユーザーではなく、サービス プリンシパルに関連付けられた認証を使用することをお勧めします。 「サービスプリンシパルの管理」を参照してください。
新しい CLI では、Databricks 個人用アクセストークンに加えて OAuth トークンがサポートされています。 これらの追加トークンは、通常 1 時間で期限切れになるため、より安全ですが、Databricks 個人用アクセストークンは 1 日から無期限まで有効です。 これは、トークンが誤って他のユーザーがアクセスできるバージョン管理システムにチェックインされた場合に特に重要です。 また、新しい CLI では、有効期限が切れたときにこれらの追加トークンを自動的に更新できますが、Databricks 個人用アクセストークンの更新は手動プロセスであるか、自動化が困難な場合があります。
詳細については、「 Databricks CLI の認証」を参照してください。
コマンド・グループとコマンドの比較
次の表に、レガシー CLI コマンドグループとそれに対応する新しい CLI コマンドグループを示します。 CLI 間に大きな違いがある場合は、追加の表に、レガシー CLI コマンドまたはオプションと、それに相当する新しい CLI コマンドまたはオプションがリストされています。
コマンドグループ
レガシーコマンドグループ |
新しいコマンド グループ |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
新しい CLI では使用できません。 代わりに 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 はレガシ 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 APIsを完全にカバーしています。 レガシー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 を実行できます。