メインコンテンツまでスキップ

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 をアンインストールする​

レガシー CLI がインストールされていて、それをアンインストールする場合は、次のように pip (Python のバージョンによっては pip3を使用) して uninstall コマンドを実行します。

Bash
pip uninstall databricks-cli

新しいCLIのインストール​

新しい CLI をインストールする方法については、「 Databricks CLI のインストールまたは更新」を参照してください。

CLI のインストールを確認する​

新しい CLI を使用しているかどうかわからない場合は、このセクションの手順に従って確認し、必要に応じて調整します。 これらの手順を実行する前に、Python 仮想環境、 conda 環境、または同様の環境を終了してください。

CLI のデフォルト・インストールのバージョンを確認するには、次のコマンドを実行します。

Bash
databricks -v

バージョン番号が期待どおりでない場合は、次のいずれかを実行してください。

  • CLI の 1 つのバージョンのみを使用する場合 : 使用しなくなった以前のバージョンの CLI をすべてアンインストールします。 オペレーティング・システムの PATH を更新して、使用する CLI の残りのバージョンへのパスがリストされるようにすることが必要な場合があります。
  • 複数のバージョンの CLI を引き続き使用する場合 : CLI へのすべての呼び出しに、使用する CLI のバージョンへのフルパスを付加します。
  • 複数のバージョンの CLI を引き続き使用するが、最も頻繁に使用する CLI のバージョンへのフルパスを先頭に付けたくない場合は 、そのバージョンへのフルパスがオペレーティングシステムの PATHの最初にリストされていることを確認してください。 オペレーティングシステムの PATHで最初にリストされていないCLIのバージョンへのフルパスを先頭に追加する必要があることに注意してください。

オペレーティング システムの PATHを更新するには、次の手順を実行します。

  1. List the paths where databricks is installed by running one of the following commands:

    Bash
    which -a databricks

    # Or:
    where databricks

  2. 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

  3. 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 add databricks to the end of this path. For example:

    Bash
    export PATH="/usr/local/bin:$PATH"

  4. To verify that the PATH was set correctly for the current terminal session, run databricks followed by -v and check the version number:

    Bash
    databricks -v

  5. 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.

  6. After you update your shell initialization file, you must restart your terminal to apply the updated PATH value.

追加の認証タイプを使用する​

従来の 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 コマンドまたはオプションが一覧表示されます。

コマンド グループ​

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

新しいコマンドグループ

cluster-policies

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

clusters

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

configure

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 の OAuth については、 OAuth マシン間 (M2M) 認証 または OAuth ユーザー間 (U2M) 認証を参照してください。 新しい CLI では、CLI 出力がテキスト形式か JSON 形式かを指定するために -o を再利用します。

--oauth

新しい CLI の OAuth については、 OAuth マシン間 (M2M) 認証 または OAuth ユーザー間 (U2M) 認証を参照してください。

-s または --scope

新しい CLI の OAuth については、 OAuth マシン間 (M2M) 認証 または OAuth ユーザー間 (U2M) 認証を参照してください。

-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 では使用できません。 データリネージ 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 コマンドには、特定の順序で指定する必要があり、付随するオプションがない 2 つ以上の位置引数があります。 これは、ほとんどのコマンドですべての引数にオプションを指定する必要がある従来の CLI とは異なります。 たとえば、新しい CLIの clusters get コマンドは、クラスター ID をデフォルト引数として受け取ります。 ただし、従来の CLIの clusers get コマンドでは、クラスター ID と共に --cluster-id オプションを指定する必要があります。 例えば：

従来の CLI の場合:

Bash
# 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 の場合:

Bash
# 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 の場合:

Bash
databricks unity-catalog permissions get --schema main.default

新しい CLI の場合:

Bash
# 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 の場合、次の例はエラー時のフルスタックトレースを示しています。

Bash
databricks fs ls / --debug

# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"

新しい CLI の場合、次の例では、フルスタックトレースを現在の作業ディレクトリ内の new-cli-errors.log という名前のファイルに記録します。 スタックトレースは JSON 形式でファイルに書き込まれます。

Bash
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 への移行に関するヘルプについては、次のリソースを参照してください。

に最終更新