Freigeben über

Databricks CLI-Migration

  • Artikel

In diesem Artikel wird beschrieben, wie Sie von Version 0.18 oder niedriger zu Version 0.205 oder höher der Databricks-Befehlszeilenschnittstelle migrieren. Die Databricks-CLI-Version 0.205 und höhere Versionen befinden sich in der Public Preview.

Aus Gründen der Übersichtlichkeit werden in diesem Artikel die Versionen der Databricks-Befehlszeilenschnittstelle bis 0.18 als Legacy-CLI und die Versionen ab 0.205 als „neue“ CLI bezeichnet.

Weitere Informationen zur Legacy-CLI und zur neuen CLIs finden Sie hier:

Deinstallieren der Legacy-CLI

Wenn Sie die Legacy-CLI installiert haben und sie deinstallieren möchten, verwenden Sie pip (oder pip3, abhängig von Ihrer Python-Version), um den Befehl uninstall wie folgt auszuführen:

pip uninstall databricks-cli

Installieren der neuen CLI

Informationen zum Installieren der neuen CLI finden Sie unter Installieren oder Aktualisieren der Databricks-CLI.

Überprüfen der CLI-Installation

Wenn Sie nicht sicher sind, ob Sie die neue CLI verwenden, befolgen Sie die Anweisungen in diesem Abschnitt, um dies zu überprüfen und bei Bedarf anzupassen. Bevor Sie diese Anweisungen befolgen, beenden Sie unbedingt alle virtuellen Python-Umgebungen, conda-Umgebungen oder ähnlichen Umgebungen.

Führen Sie den folgenden Befehl aus, um die Version Ihrer Standardinstallation der CLI zu überprüfen:

databricks -v

Wenn die Versionsnummer nicht Ihren Erwartungen entspricht, führen Sie eine der folgenden Aktionen aus:

  • Wenn Sie nur eine Version der CLI verwenden möchten: Deinstallieren Sie alle vorherigen Versionen der CLI, die Sie nicht mehr verwenden möchten. Möglicherweise müssen Sie den Pfad (PATH) Ihres Betriebssystems aktualisieren, damit der Pfad zur verbleibenden Version der CLI, die Sie verwenden möchten, aufgeführt wird.
  • Wenn Sie weiterhin mehrere Versionen der CLI verwenden möchten: Stellen Sie den vollständigen Pfad der Version der CLI voran, die Sie für jeden einzelnen Aufruf der CLI verwenden möchten.
  • Wenn Sie weiterhin mehrere Versionen der CLI verwenden möchten, aber nicht weiterhin den vollständigen Pfad zu der CLI-Version voranstellen möchten, die Sie am häufigsten verwenden: Stellen Sie sicher, dass der vollständige Pfad zu dieser Version im Pfad (PATH) Ihres Betriebssystems als erstes aufgeführt wird. Beachten Sie, dass Sie den vollständigen Pfad weiterhin Versionen der CLI voranstellen müssen, die nicht zuerst in im Pfad (PATH) des Betriebssystems aufgeführt sind.

Führen Sie die folgenden Schritte aus, um den Pfad (PATH) des Betriebssystems zu aktualisieren:

macOS oder Linux

  1. Listen Sie die Pfade auf, in denen databricks installiert ist, indem Sie einen der folgenden Befehle ausführen:

    which -a databricks

# Or:
where databricks

  2. Rufen Sie den Pfad zu der Installation ab, die Sie verwenden möchten, ohne bei jedem einzelnen Aufruf der CLI den vollständigen Pfad voranzustellen. Wenn Sie nicht sicher sind, welcher Pfad dies ist, führen Sie den vollständigen Pfad zu jedem Speicherort aus, gefolgt von -v. Beispiel:

    /usr/local/bin/databricks -v

  3. Wenn Sie den Pfad zu der Installation, die Sie verwenden möchten, im Pfad (PATH) als erstes angeben möchten, führen Sie den folgenden Befehl aus. Ersetzen Sie dabei /usr/local/bin durch den zu verwendenden Pfad. Fügen Sie am Ende dieses Pfads nicht databricks an. Beispiel:

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

  4. Um zu überprüfen, ob PATH für die aktuelle Terminalsitzung richtig festgelegt wurde, führen Sie databricks gefolgt von -v aus, und überprüfen Sie die Versionsnummer:

    databricks -v

  5. Fügen Sie den Befehl aus Schritt 3 der Shell-Initialisierungsdatei hinzu, damit PATH bei jedem Neustart des Terminals auf diese Weise festgelegt wird. Für Zshell befindet sich diese Datei z. B. in der Regel unter ~/.zshrc. Für Bash befindet sich diese Datei z. B. in der Regel unter ~/.bashrc. Informationen zu anderen Shells finden Sie in der Dokumentation des Shell-Anbieters.

  6. Nachdem Sie die Shell-Initialisierungsdatei aktualisiert haben, müssen Sie das Terminal neu starten, um den aktualisierten PATH-Wert anzuwenden.

Windows

  1. Klicken Sie mit der rechten Maustaste auf die Installation von databricks, die Sie verwenden möchten, ohne bei jedem einzelnen Aufruf der CLI den vollständigen Pfad voranzustellen.

  2. Klicken Sie auf Dateispeicherort öffnen.

  3. Notieren Sie sich den Pfad zu databricks, z. B. C:\Windows.

  4. Suchen Sie im Menü Start nach Umgebungsvariablen.

  5. Klicken Sie auf Umgebungsvariablen für Ihr Konto bearbeiten.

  6. Wählen Sie im Abschnitt Benutzervariablen für <username> die Variable Path aus.

  7. Klicken Sie auf Bearbeiten.

  8. Klicken Sie auf Neu.

  9. Geben Sie den Pfad, den Sie hinzufügen möchten, ohne databricks.exe ein (z. B. C:\Windows).

  10. Verwenden Sie die Schaltfläche Nach oben, um den Pfad, den Sie gerade am Anfang der Liste hinzugefügt haben, zu verschieben.

  11. Klicken Sie auf OK.

  12. Um zu überprüfen, ob PATH richtig festgelegt wurde, öffnen Sie eine neue Eingabeaufforderung, führen Sie databricks gefolgt von -v aus, und überprüfen Sie die Versionsnummer:

    databricks -v

Verwenden zusätzlicher Authentifizierungstypen

Die Legacy-CLI und die neue CLI unterstützen die Authentifizierung mit persönlichem Zugriffstoken von Azure Databricks. Databricks empfiehlt jedoch, nach Möglichkeit andere Azure Databricks-Authentifizierungstypen zu verwenden, die nur von der neuen CLI unterstützt werden.

Wenn Sie die Authentifizierung mit persönlichem Zugriffstoken von Azure Databricks verwenden müssen, empfiehlt Databricks, ein Token zu verwenden, das einem Dienstprinzipal und nicht einem Azure Databricks-Konto oder einem*r Arbeitsbereichsbenutzer*in zugeordnet ist. Siehe Verwalten von Dienstprinzipalen.

Die neue CLI unterstützt neben den persönlichen Azure Databricks-Zugriffstoken auch Microsoft Entra ID-Token. Diese zusätzlichen Token sind sicherer, da sie in der Regel nach einer Stunde ablaufen, während persönliche Azure Databricks-Zugriffstoken eine Gültigkeit von einem Tag haben oder eine unbestimmte Zeit lang gültig sein können. Dies ist besonders wichtig, wenn ein Token versehentlich in Versionskontrollsysteme eingecheckt wird, auf die andere Personen zugreifen können. Außerdem kann die neue CLI diese zusätzlichen Token automatisch aktualisieren, wenn sie ablaufen. Das Aktualisieren von persönlichen Azure Databricks-Zugriffstoken ist hingegen entweder ein manueller Prozess oder schwer zu automatisieren.

Weitere Informationen finden Sie unter Authentifizierung für die Databricks-CLI.

Vergleich von Befehlsgruppen und Befehlen

In der folgenden Tabelle sind die Befehlsgruppen der Legacy-CLI und die Entsprechungen der neuen CLI-Befehlsgruppen aufgeführt. Wenn erhebliche Unterschiede zwischen CLIs bestehen, sind in zusätzlichen Tabellen Legacy-CLI-Befehle oder -Optionen und die Entsprechungen der Befehle oder Optionen der neuen CLI aufgeführt.

Befehlsgruppen

Legacybefehlsgruppe Neue Befehlsgruppe
cluster-policies cluster-policies. Alle Befehlsnamen sind identisch.
clusters clusters. Alle Befehlsnamen sind identisch.
configure configure. Weitere Informationen finden Sie unter Konfigurationsoptionen.
fs fs. Weitere Informationen finden Sie unter fs-Befehle.
groups groups. Weitere Informationen finden Sie unter groups-Befehle.
instance-pools instance-pools. Alle Befehlsnamen sind identisch.
jobs jobs. Alle Befehlsnamen sind identisch.
libraries libraries. Alle Befehlsnamen sind identisch mit Ausnahme von list. Der Befehl list ist nicht mehr verfügbar. Verwenden Sie stattdessen die Befehle all-cluster-statuses oder cluster-status.
pipelines pipelines. Weitere Informationen finden Sie unter pipelines-Befehle.
repos repos. Alle Befehlsnamen sind identisch.
runs jobs. Weitere Informationen finden Sie unter runs-Befehle.
secrets secrets. Weitere Informationen finden Sie unter secrets-Befehle.
stack In der neuen CLI nicht verfügbar. Databricks empfiehlt, stattdessen den Databricks Terraform-Anbieter zu verwenden.
tokens tokens. Weitere Informationen finden Sie unter tokens-Befehle.
unity-catalog Verschiedene. Weitere Informationen finden Sie unter unity-catalog-Befehlsgruppen.
workspace workspace. Weitere Informationen finden Sie unter workspace-Befehle.

configure-Optionen

Legacyoption Neue Option
-o Die Legacy-CLI verwendet -o für die OAuth-Authentifizierung. Die neue CLI funktioniert -o um, um anzugeben, ob die CLI-Ausgabe im Text- oder JSON-Format vorliegt. Gilt nicht für Azure Databricks.
--oauth Gilt nicht für Azure Databricks.
-s oder --scope Gilt nicht für Azure Databricks.
-t oder --token -t oder --token (identisch)
-f oder --token-file In der neuen CLI nicht verfügbar.
--host --host (identisch)
--aad-token Sie können --host verwenden und, wenn Sie dazu aufgefordert werden, ein Microsoft Entra ID-Token anstelle eines persönlichen Azure Databricks-Zugriffstokens eingeben.
--insecure In der neuen CLI nicht verfügbar.
--jobs-api-version In der neuen CLI nicht verfügbar. Die neue CLI verwendet nur die Auftrags-API 2.1. Um die Legacyauftrags-API 2.0 aufzurufen, verwenden Sie die Legacy-CLI, und lesen Sie die Informationen unter Auftrags-CLI (Legacy).
--debug Informationen zum Debuggen und Protokollieren in der neuen CLI finden Sie unter Debugmodus.
--profile --profile (identisch) oder -p
-h oder --help -h oder --help (identisch)

fs-Befehle

Alle fs-Befehle in der Legacy-CLI sind in der neuen CLI identisch, mit Ausnahme des Befehls fs mv, der in der neuen CLI nicht verfügbar ist.

Legacybefehl Neuer Befehl
fs cat fs cat (identisch)
fs cp fs cp (identisch)
fs ls fs ls (identisch)
fs mkdirs fs mkdir
fs mv In der neuen CLI nicht verfügbar.
fs rm fs rm (identisch)

groups-Befehle

Legacybefehl Neuer Befehl
groups add-member groups patch
groups create groups create (identisch)
groups delete groups delete (identisch)
groups list groups list (identisch)
groups list-members groups list
groups list-parents groups list
groups remove-member groups patch

pipelines-Befehle

Legacybefehl Neuer Befehl
pipelines create pipelines create (identisch)
pipelines delete pipelines delete (identisch)
pipelines deploy pipelines create
pipelines edit pipelines update
pipelines get pipelines get (identisch)
pipelines list pipelines list-pipeline-events oder pipelines list-pipelines oder pipelines list-updates
pipelines reset pipelines reset (identisch)
pipelines start pipelines start update
pipelines stop pipelines stop (identisch)
pipelines update pipelines update (identisch)

runs-Befehle

Legacybefehl Neuer Befehl
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-Befehle

Legacybefehl Neuer Befehl
secrets create-scope secrets create-scope (identisch)
secrets delete secrets delete-secret
secrets delete-acl secrets delete-acl (identisch)
secrets delete-scope secrets delete-scope (identisch)
secrets get-acl secrets get-acl (identisch)
secrets list secrets list-secrets
secrets list-acls secrets list-acls (identisch)
secrets list-scopes secrets list-scopes (identisch)
secrets put secrets put-secret
secrets put-acl secrets put-acl (identisch)
secrets write secrets put-secret
secrets write-acl secrets put-acl

tokens-Befehle

Legacybefehl Neuer Befehl
tokens create tokens create (identisch)
tokens list tokens list (identisch)
tokens revoke tokens delete

unity-catalog-Befehlsgruppen

unity-catalog <command> in der Legacy-CLI wird in der neuen CLI einfach <command>.

Legacybefehlsgruppe Neue Befehlsgruppe
unity-catalog catalogs catalogs (identisch, aber unity-catalog wird weggelassen)
unity-catalog external-locations external-locations (identisch, aber unity-catalog wird weggelassen)
unity-catalog lineage In der neuen CLI nicht verfügbar. Weitere Informationen unter Abrufen der Herkunft mithilfe der REST-API für Datenherkunft.
unity-catalog metastores metastores (identisch, aber unity-catalog wird weggelassen)
unity-catalog permissions grants
unity-catalog providers providers (identisch, aber unity-catalog wird weggelassen)
unity-catalog recipients recipients (identisch, aber unity-catalog wird weggelassen)
unity-catalog schemas schemas (identisch, aber unity-catalog wird weggelassen)
unity-catalog shares shares (identisch, aber unity-catalog wird weggelassen)
unity-catalog storage-credentials storage-credentials (identisch, aber unity-catalog wird weggelassen)
unity-catalog tables tables (identisch, aber unity-catalog wird weggelassen)

workspace-Befehle

Legacybefehl Neuer Befehl
workspace delete workspace delete (identisch)
workspace export workspace export (identisch)
workspace export-dir workspace export
workspace import workspace import (identisch)
workspace import-dir workspace import
workspace list workspace list (identisch)
workspace ls workspace list
workspace mkdirs workspace mkdirs (identisch)
workspace rm workspace delete

Standardargumente und positionelle Argumente

Die meisten neuen CLI-Befehle verfügen über mindestens ein Standardargument, das keine zugehörige Option enthält. Einige neue CLI-Befehle verfügen über zwei oder mehr positionelle Argumente, die in einer bestimmten Reihenfolge angegeben werden müssen und keine zugehörigen Optionen haben. Dies unterscheidet sich von der Legacy-CLI, bei der für die meisten Befehle Optionen für alle Argumente angegeben werden müssen. Der Befehl clusters get der neuen CLI verwendet beispielsweise eine Cluster-ID als Standardargument. Für den Befehl clusers get der Legacy CLI müssen Sie jedoch eine Option vom Typ --cluster-id zusammen mit der Cluster-ID angeben. Beispiel:

Legacy 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

Neue 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

Als weiteres Beispiel verwendet der Befehl grants get der neuen CLI zwei Standardargumente: den sicherungsfähigen Typ gefolgt vom vollständigen Namen des sicherungsfähigen Typ. Für den Befehl unity-catalog permissions get der Legacy-CLI müssen Sie jedoch eine Option vom Typ --<securable-type> zusammen mit dem vollständigen Namen des sicherungsfähigen Typs angeben. Beispiel:

Legacy CLI:

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

Neue 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

Debugmodus

Die Legacy-CLI bietet eine --debug-Option zum Anzeigen der vollständigen Stapelüberwachung bei einem Fehler. Bei der neuen CLI wird die Option --debug nicht erkannt. Verwenden Sie stattdessen die folgenden Optionen:

  • Verwenden Sie --log-file <path> zum Schreiben von Protokollinformationen in die Datei, die in <path> angegeben ist. Wenn diese Option nicht bereitgestellt wird, werden Protokollinformationen an stderr ausgegeben. Wenn Sie --log-file angeben, ohne auch --log-level anzugeben, führt das dazu, dass keine Protokollinformationen in die Datei geschrieben werden.
  • Verwenden Sie --log-format <type>, um das Format der protokollierten Informationen anzugeben. <type> kann text (Standardwert, falls keine Angabe gemacht wird) oder json sein.
  • Verwenden Sie --log-level <format>, um die Ebene der protokollierten Informationen anzugeben. Zulässige Werte sind disabled (Standardwert, falls keine Angabe gemacht wird), trace, debug, info, warn und error.

Für die Legacy-CLI zeigt das folgende Beispiel die vollständige Stapelüberwachung bei einem Fehler:

databricks fs ls / --debug

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

Für die neue CLI protokolliert das folgende Beispiel die vollständige Stapelüberwachung in einer Datei mit dem Namen new-cli-errors.log im aktuellen Arbeitsverzeichnis. Die Stapelüberwachung wird im JSON-Format in die Datei geschrieben:

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

Häufig gestellte Fragen

Dieser Abschnitt enthält häufig gestellte Fragen zur Migration von der Legacy-CLI zur neuen CLI.

Was geschieht mit der Legacy-CLI?

Die Legacy-CLI ist weiterhin verfügbar, für sie werden aber keine nicht kritischen Updates mehr bereitgestellt. Dies ist in der Dokumentation der Legacy-CLI widergespiegelt. Databricks empfiehlt Benutzer*innen, baldmöglichst zur neuen CLI zu migrieren.

Die Legacy-CLI befand sich immer in einem experimentellen Zustand und hatte den Hinweis, dass Databricks keine neuen Funktionen für die Legacy-CLI plant und die Legacy-CLI nicht durch Databricks-Supportkanäle unterstützt wird.

Wann wird die Legacy CLI als veraltet gekennzeichnet?

Die Legacy-CLI befand sich immer in einem experimentellen Zustand und hatte den Hinweis, dass Databricks keine neuen Funktionen für die Legacy-CLI plant und die Legacy-CLI nicht durch Databricks-Supportkanäle unterstützt wird.

Databricks hat kein Datum und keine Zeitachse für die Kennzeichnung der Legacy-CLI als veraltet festgelegt. Databricks empfiehlt Benutzer*innen jedoch, baldmöglichst zur neuen CLI zu migrieren.

Wann wird die neue CLI als allgemein verfügbar (GA) veröffentlicht?

Ein Veröffentlichungsdatum oder eine Zeitachse für die Veröffentlichung der neuen CLI als GA wurde nicht festgelegt. Es hängt vom Feedback ab, das Databricks während der Public Preview von Benutzer*innen erhält.

Was sind die wichtigsten Unterschiede zwischen der Legacy-CLI und der neuen CLI?

  • Die Legacy-CLI wurde als Python-Paket veröffentlicht. Die neue CLI wird als eigenständige ausführbare Datei veröffentlicht und erfordert keine Installation von Laufzeitabhängigkeiten.
  • Die neue CLI deckt die Databricks-REST-APIs vollständig ab. Die Legacy-CLI hingegen nicht.
  • Die neue CLI ist als Public Preview verfügbar. Die Legacy-CLI verbleibt im experimentellen Zustand.

Verfügt die neue CLI über vollständige Featureparität mit der Legacy-CLI?

Die neue CLI deckt fast alle Befehle aus der Legacy-CLI ab. In der neuen CLI fehlt jedoch insbesondere die Befehlsgruppe stacks der Legacy CLI. Darüber hinaus wurden einige Legacy-CLI-Befehlsgruppen wie unity-catalog und runs in neue Befehlsgruppen in der neuen CLI umgestaltet. Einen Migrationsleitfaden finden Sie in den Informationen weiter oben in diesem Artikel.

Wie migriere ich von der Legacy-CLI zur neuen CLI?

Einen Migrationsleitfaden finden Sie in den Informationen weiter oben in diesem Artikel. Beachten Sie, dass die neue CLI kein direkter Ersatz für die Legacy-CLI ist und einige Setupschritte erfordert, damit Sie von der Legacy-CLI zur neuen CLI wechseln können.

Können Installationen der Legacy-CLI und der neuen CLI auf demselben Computer vorhanden sein?

Ja. Installationen der Legacy-CLI und der neuen CLI können auf demselben Computer vorhanden sein, müssen sich jedoch in unterschiedlichen Verzeichnissen befinden. Da die ausführbaren Dateien beide den Namen databricks haben, müssen Sie steuern, welche ausführbare Datei standardmäßig ausgeführt wird. Konfigurieren Sie dazu den Pfad (PATH) Ihres Computers. Wenn Sie die neue CLI ausführen möchten, aber stattdessen versehentlich die Legacy-CLI ausführen, führt die Legacy-CLI standardmäßig die neue CLI mit denselben Argumenten aus und zeigt die folgende Warnmeldung an:

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>

Wie in der vorherigen Warnmeldung gezeigt, können Sie die Umgebungsvariable DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION auf 1 festlegen, um dieses Verhalten zu deaktivieren und stattdessen die Legacy-CLI auszuführen.

Hilfe erhalten

Hilfe bei der Migration von der Legacy-CLI zur neuen CLI finden Sie in den folgenden Ressourcen: