CLI 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 の詳細については、以下を参照してください。

レガシー 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を更新するには、次の手順を実行します。

  1. 次のいずれかのコマンドを実行して、 databricks がインストールされているパスを一覧表示します。

    which -a databricks
    
    # Or:
    where databricks
    
  2. CLI へのすべての呼び出しへのフルパスを先頭に追加せずに、使用するインストールへのパスを取得します。 これがどのパスであるかわからない場合は、各場所への完全なパスを実行してから、次のように -vを実行します。

    /usr/local/bin/databricks -v
    
  3. 使用するインストールへのパスを PATHの最初に指定するには、次のコマンドを実行し、 /usr/local/bin を使用するパスに置き換えます。 このパスの末尾に databricks を追加しないでください。 例えば:

    export PATH="/usr/local/bin:$PATH"
    
  4. 現在のターミナル セッションに対して PATH が正しく設定されていることを確認するには、 databricks を実行してから -v を実行し、バージョン番号を確認します。

    databricks -v
    
  5. 端末を再起動するたびに PATH をこのように設定するには、ステップ 3 のコマンドをシェル初期化ファイルに追加します。 たとえば、Zshell の場合、このファイルは通常 ~/.zshrcにあります。 Bash の場合、このファイルは通常 ~/.bashrcにあります。 その他のシェルについては、シェルプロバイダーのドキュメントを参照してください。

  6. シェル初期化ファイルを更新した後、端末を再起動して、更新された PATH 値を適用する必要があります。

  1. 使用する databricks のインストールを右クリックし、CLI へのすべての呼び出しの先頭にフルパスを付けずに右クリックします。

  2. [ ファイルの場所を開く] をクリックします。

  3. databricksへのパス (C:\Windowsなど) に注意してください。

  4. [ スタート ] メニューで、 環境変数を検索します。

  5. [ アカウントの環境変数の編集] をクリックします。

  6. [<username>のユーザー変数] セクションで Path 変数を選択します。

  7. [編集] をクリックします。

  8. [ 新規] をクリックします。

  9. 追加するパスを databricks.exe なしで入力します( C:\Windowsなど)。

  10. [ 上へ移動 ] ボタンを使用して、追加したパスをリストの先頭に移動します。

  11. OK をクリックします。

  12. 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 コマンドまたはオプションがリストされています。

コマンドグループ

レガシーコマンドグループ

新しいコマンド グループ

cluster-policies

cluster-policies.すべてのコマンド名は同じです。

clusters

clusters.すべてのコマンド名は同じです。

configure

configure. 「オプションの構成」を参照してください。

fs

fs. fsコマンドを参照してください。

groups

groups. グループコマンドを参照してください。

instance-pools

instance-pools.すべてのコマンド名は同じです。

jobs

jobs.すべてのコマンド名は同じです。

libraries

libraries. listを除いて、すべてのコマンド名は同じです。 list コマンドは使用できなくなりました。代わりに、 all-cluster-statuses または cluster-status コマンドを使用してください。

pipelines

pipelines. パイプラインコマンドを参照してください。

repos

repos.すべてのコマンド名は同じです。

runs

jobs. 実行コマンドを参照してください。

secrets

secrets. シークレットコマンドを参照してください。

stack

新しい CLI では使用できません。 代わりに Databricks Terraform プロバイダー を使用することをお勧めします。

tokens

tokens. トークンコマンドを参照してください。

unity-catalog

諸。 ユニティカタログコマンドグループを参照してください。

workspace

workspace. ワークスペースコマンドを参照してください。

configure オプション

レガシーオプション

新しいオプション

-o

従来のCLIでは、OAuth認証に -o を使用します。 新しいCLIのOAuthについては、「Googleクラウド認証 情報 認証」または 「GoogleクラウドID認証」を参照してください。 新しいCLIは、CLI出力がテキスト形式かJSON形式かを指定するために -o を再利用します。

--oauth

新しいCLIのOAuthについては、「Googleクラウド認証 情報 認証」または 「GoogleクラウドID認証」を参照してください。

-s 又は --scope

新しいCLIのOAuthについては、「Googleクラウド認証 情報 認証」または 「GoogleクラウドID認証」を参照してください。

-t 又は --token

-t または --token (同じ)

-f 又は --token-file

新しい CLI では使用できません。

--host

--host (同じ)

--aad-token

--host を使用し、メッセージが表示されたら、Databricks 個人用アクセス トークンではなく Microsoft Entra ID トークンを指定します。

--insecure

新しい CLI では使用できません。

--jobs-api-version

新しい CLI では使用できません。 新しい CLI は Jobs API 2.1 のみを使用します。 レガシ ジョブ API 2.0 を呼び出すには、レガシ CLI を使用し、「 Databricks 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 コマンド グループ

unity-catalog <command> レガシーCLIでは、新しいCLIで <command> になります。

レガシーコマンドグループ

新しいコマンド グループ

unity-catalog catalogs

catalogs (同じですが、ドロップ unity-catalog)

unity-catalog external-locations

external-locations (同じですが、ドロップ unity-catalog)

unity-catalog lineage

新しい CLI では使用できません。

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 コマンドには、特定の順序で指定する必要があり、付随するオプションがない 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 (指定しない場合のデフォルト)、 tracedebuginfowarn、および 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-catalogruns などのいくつかのレガシー 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 への移行に関するヘルプについては、次のリソースを参照してください。