Freigeben über

Databricks CLI (Legacy)

  • Artikel

Wichtig

Diese Dokumentation wurde eingestellt und wird unter Umständen nicht aktualisiert.

Databricks empfiehlt, die neuere Databricks CLI-Version 0.205 oder höher anstelle der Databricks CLI-Legacy-Version 0.18 oder niedriger zu verwenden. Die Databricks CLI-Version 0.18 oder niedriger wird von Databricks nicht unterstützt. Informationen zu den neuen Databricks CLI-Versionen 0.205 und höher finden Sie unter Was ist die Databricks-CLI?.

Informationen zum Migrieren der Databricks CLI-Version 0.18 oder niedriger zur Databricks CLI-Version 0.205 oder höher finden Sie unter Databricks CLI-Migration.

Die Legacy-Databricks CLI befindet sich im experimentellen Zustand. Databricks plant derzeit keine neue Funktion für die Legacy-Databricks CLI.

Die Legacy-Databricks CLI wird nicht über Databricks-Supportkanäle unterstützt. Verwenden Sie die Registerkarte Probleme im Repository der Befehlszeilenschnittstelle für Databricks in GitHub, um Feedback zu geben, Fragen zu stellen und Probleme zu melden.

Die Legacy-Databricks Befehlszeilenschnittstelle (auch als Legacy-Databricks CLI bezeichnet) ist ein Hilfsprogramm, das eine benutzerfreundliche Schnittstelle zum Automatisieren der Azure Databricks-Plattform über Ihr Terminal, Ihre Eingabeaufforderung oder über Automatisierungsskripts bereitstellt.

Anforderungen

  • Python 3 – 3.6 und höher
  • Python 2 – 2.7.9 und höher

Wichtig

Unter macOS wird bei der Standardinstallation von Python 2 nicht das Protokoll TLSv1_2 implementiert und bei der Ausführung der Legacy-Databricks CLI mit dieser Python-Installation tritt der folgende Fehler auf: AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'. Verwenden Sie Homebrew, um eine Python-Version mit ssl.PROTOCOL_TLSv1_2 zu installieren.

Begrenzungen

Die Verwendung der Legacy-Databricks CLI mit firewallfähigen Speichercontainern wird nicht unterstützt. Databricks empfiehlt die Verwendung von Databricks Connect oder az storage.

Einrichten der CLI

In diesem Abschnitt wird beschrieben, wie Sie die Legacy-Databricks CLI einrichten.

Installieren oder Aktualisieren der CLI

In diesem Abschnitt wird beschrieben, wie Sie Ihren Entwicklungscomputer installieren oder aktualisieren, um die Legacy-Databricks CLI auszuführen.

Installieren der Befehlszeilenschnittstelle

Führen Sie pip install databricks-cli mithilfe der entsprechenden Version von pip für Ihre Python-Installation aus:

pip install databricks-cli

Aktualisieren der CLI

Führen Sie pip install databricks-cli --upgrade mithilfe der entsprechenden Version von pip für Ihre Python-Installation aus:

pip install databricks-cli --upgrade

Führen Sie zum Auflisten der derzeit installierten Legacy-Databricks CLI-Version databricks --version aus:

databricks --version

Einrichten der Authentifizierung

Bevor Sie Legacy-Databricks CLI-Befehle ausführen können, müssen Sie die Authentifizierung zwischen der Legacy-Databricks CLI und Azure Databricks einrichten. In diesem Abschnitt wird beschrieben, wie Sie die Authentifizierung für die Legacy-Databricks CLI einrichten.

Zur Authentifizierung mit der Legacy-Databricks-CLI können Sie ein persönliches Databricks-Zugriffstoken oder ein Microsoft Entra ID-Token (vormals Azure Active Directory) verwenden.

Hinweis

Als bewährte Methode für die Sicherheit empfiehlt Databricks, dass Sie bei der Authentifizierung mit automatisierten Tools, Systemen, Skripten und Anwendungen persönliche Zugriffstoken verwenden, die zu Dienstprinzipalen und nicht zu Benutzern des Arbeitsbereichs gehören. Informationen zum Erstellen von Token für Dienstprinzipale finden Sie unter Verwalten von Token für einen Dienstprinzipal.

Einrichten der Authentifizierung mithilfe von Microsoft Entra ID-Token

Zum Konfigurieren der Legacy-CLI von Databricks mithilfe eines Microsoft Entra ID-Tokens generieren Sie das Microsoft Entra ID-Token (ehemals Azure Active Directory) und speichern es in der Umgebungsvariable DATABRICKS_AAD_TOKEN.

Führen Sie den folgenden Befehl aus:

databricks configure --aad-token

Der Befehl gibt die Eingabeaufforderung aus:

Databricks Host (should begin with https://):

Geben Sie die arbeitsbereichsspezifische URL im Format https://adb-<workspace-id>.<random-number>.azuredatabricks.net ein. Informationen zum Abrufen der arbeitsbereichsspezifischen URL finden Sie unter URL pro Arbeitsbereich.

Nach dem Befolgen der Eingabeaufforderung werden Ihre Zugriffsanmeldeinformationen unter Linux oder macOS in der Datei ~/.databrickscfg bzw. unter Windows in der Datei %USERPROFILE%\.databrickscfg gespeichert. Die Datei enthält einen Standardprofileintrag:

[DEFAULT]
host = <workspace-URL>
token = <Azure-AD-token>

Wenn die .databrickscfg-Datei bereits vorhanden ist, wird das DEFAULT-Konfigurationsprofil dieser Datei mit den neuen Daten überschrieben. Informationen zum Erstellen eines Konfigurationsprofils mit einem anderen Namen finden Sie unter Verbindungsprofile.

Einrichten der Authentifizierung mit einem persönlichen Databricks-Zugriffstoken

Führen Sie den folgenden Befehl aus, um die Legacy-Databricks CLI so zu konfigurieren, dass sie ein persönliches Zugriffstoken verwendet:

databricks configure --token

Der Befehl beginnt durch Ausgabe der Eingabeaufforderung:

Databricks Host (should begin with https://):

Geben Sie die arbeitsbereichsspezifische URL im Format https://adb-<workspace-id>.<random-number>.azuredatabricks.net ein. Informationen zum Abrufen der arbeitsbereichsspezifischen URL finden Sie unter URL pro Arbeitsbereich.

Der Befehl wird fortgesetzt, indem die Eingabeaufforderung zum Eingeben Ihres persönlichen Zugriffstokens ausgegeben wird:

Token:

Nach dem Befolgen der Eingabeaufforderungen werden Ihre Zugriffsanmeldeinformationen unter Linux oder macOS in der Datei ~/.databrickscfg bzw. unter Windows in der Datei %USERPROFILE%\.databrickscfg gespeichert. Die Datei enthält einen Standardprofileintrag:

[DEFAULT]
host = <workspace-URL>
token = <personal-access-token>

Wenn die .databrickscfg-Datei bereits vorhanden ist, wird das DEFAULT-Konfigurationsprofil dieser Datei mit den neuen Daten überschrieben. Informationen zum Erstellen eines Konfigurationsprofils mit einem anderen Namen finden Sie unter Verbindungsprofile.

Für CLI 0.8.1 und höhere Versionen können Sie den Pfad dieser Datei ändern, indem Sie die Umgebungsvariable DATABRICKS_CONFIG_FILE festlegen.

Linux oder macOS
export DATABRICKS_CONFIG_FILE=<path-to-file>
Windows
setx DATABRICKS_CONFIG_FILE "<path-to-file>" /M

Wichtig

Ab CLI 0.17.2 funktioniert die CLI nicht mit einer .netrc-Datei. Sie können eine .netrc-Datei in Ihrer Umgebung für andere Zwecke verwenden, aber die Befehlszeilenschnittstelle verwendet diese .netrc-Datei nicht.

CLI 0.8.0 und höhere Versionen unterstützen die folgenden Azure Databricks-Umgebungsvariablen:

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN

Eine Umgebungsvariableneinstellung hat Vorrang vor der Einstellung in der Konfigurationsdatei.

Testen Ihres Authentifizierungssetups

Um zu überprüfen, ob Sie die Authentifizierung ordnungsgemäß eingerichtet haben, können Sie einen Befehl wie den folgenden ausführen:

databricks fs ls dbfs:/

Bei erfolgreicher Ausführung listet dieser Befehl die Dateien und Verzeichnisse im DBFS-Stamm des Arbeitsbereichs auf, der dem Profil DEFAULT zugeordnet ist.

Verbindungsprofile

Die Konfiguration der Databricks-Befehlszeilenschnittstelle unterstützt mehrere Verbindungsprofile. Für API-Aufrufe für mehrere Azure Databricks-Arbeitsbereiche kann die gleiche Installation der Legacy-Databricks CLI verwendet werden.

Geben Sie zum Hinzufügen eines Verbindungsprofils einen eindeutigen Namen für das Profil an:

databricks configure [--token | --aad-token] --profile <profile-name>

Die Datei .databrickscfg enthält einen entsprechenden Profileintrag:

[<profile-name>]
host = <workspace-URL>
token = <token>

So verwenden Sie das Verbindungsprofil:

databricks <group> <command> --profile <profile-name>

Wird --profile <profile-name> nicht angegeben, wird das Standardprofil verwendet. Wenn kein Standardprofil gefunden wird, werden Sie aufgefordert, die Befehlszeilenschnittstelle mit einem Standardprofil zu konfigurieren.

Testen der Verbindungsprofile

Um zu überprüfen, ob Sie Verbindungsprofile ordnungsgemäß eingerichtet haben, können Sie einen Befehl wie den folgenden mit einem Ihrer Verbindungsprofilnamen ausführen:

databricks fs ls dbfs:/ --profile <profile-name>

Bei erfolgreicher Ausführung listet dieser Befehl die Dateien und Verzeichnisse im DBFS-Stamm des Arbeitsbereichs für das angegebene Verbindungsprofil auf. Führen Sie diesen Befehl für jedes Verbindungsprofil aus, das Sie testen möchten.

Um Ihre verfügbaren Profile anzuzeigen, sehen Sie sich Ihre .databrickscfg-Datei an.

Verwenden der Befehlszeilenschnittstelle

In diesem Abschnitt erfahren Sie, wie Sie die Legacy-Databricks CLI-Hilfe aufrufen, die Legacy-Databricks CLI-Ausgabe analysieren und Befehle in jeder Befehlsgruppe aufrufen.

Anzeigen der Hilfe zu CLI-Befehlsgruppen

Die Unterbefehle für eine Befehlsgruppe werden mithilfe der Option --help oder -h aufgelistet. So listen Sie beispielsweise die DBFS CLI-Unterbefehle auf:

databricks fs -h

Anzeigen der Hilfe zum CLI-Unterbefehl

Sie listen die Hilfe für einen Unterbefehl mithilfe der Option --help oder -h auf. So listen Sie beispielsweise die Hilfe für den DBFS-Unterbefehl zum Kopieren von Dateien auf:

databricks fs cp -h

Aliasbefehlsgruppen

Manchmal kann es unpraktisch sein, jedem Legacy-Databricks CLI-Aufruf den Namen einer Befehlsgruppe voranzustellen, beispielsweise databricks workspace ls in der Legacy-Databricks CLI. Um die Verwendung der Legacy-Databricks CLI zu vereinfachen, können Sie Aliasbefehlsgruppen für kürzere Befehle verwenden. Wenn Sie beispielsweise databricks workspace ls zu dw ls in der Bourne Again Shell kürzen möchten, können Sie dem entsprechenden Bash-Profil alias dw="databricks workspace" hinzufügen. Diese Datei befindet sich in der Regel unter ~/.bash_profile.

Tipp

Die Legacy-Databricks CLI hat für databricks fs bereits den Alias dbfs erstellt. databricks fs ls und dbfs ls sind identisch.

Verwenden Sie jq zum Analysieren der CLI-Ausgabe

Einige Befehle der Legacy-Databricks CLI geben die JSON-Antwort vom API-Endpunkt aus. Manchmal kann es hilfreich sein, Teile des JSON-Codes zu analysieren, um sie an andere Befehle zu übergeben. Zum Kopieren einer Auftragsdefinition müssen Sie beispielsweise das Feld settings eines Get-Job-Befehls als Argument für den Create-Job-Befehl verwenden. In diesen Fällen empfiehlt es sich, das Hilfsprogramm jq zu verwenden.

Der folgende Befehl gibt beispielsweise die Einstellungen des Auftrags mit der ID 233 aus.

databricks jobs list --output JSON | jq '.jobs[] | select(.job_id == 233) | .settings'

Ausgabe:

{
  "name": "Quickstart",
  "new_cluster": {
    "spark_version": "7.5.x-scala2.12",
    "spark_env_vars": {
      "PYSPARK_PYTHON": "/databricks/python3/bin/python3"
    },
    "num_workers": 8,
    ...
  },
  "email_notifications": {},
  "timeout_seconds": 0,
  "notebook_task": {
    "notebook_path": "/Quickstart"
  },
  "max_concurrent_runs": 1
}

Als weiteres Beispiel gibt der folgende Befehl nur die Namen und IDs aller verfügbaren Cluster im Arbeitsbereich aus:

databricks clusters list --output JSON | jq '[ .clusters[] | { name: .cluster_name, id: .cluster_id } ]'

Ausgabe:

[
  {
    "name": "My Cluster 1",
    "id": "1234-567890-grip123"
  },
  {
    "name": "My Cluster 2",
    "id": "2345-678901-patch234"
  }
]

Sie können jq beispielsweise unter macOS mithilfe von Homebrew mit brew install jq oder unter Windows mithilfe von Chocolatey mit choco install jq installieren. Weitere Informationen zu jq finden Sie im Leitfaden zu jq.

JSON-Zeichenfolgenparameter

Zeichenfolgenparameter werden je nach Betriebssystem unterschiedlich behandelt:

Linux oder macOS

JSON-Zeichenfolgenparameter müssen in einfache Anführungszeichen eingeschlossen werden. Beispiele:

'["20180505", "alantest"]'

Windows

JSON-Zeichenfolgenparameter müssen in doppelte Anführungszeichen eingeschlossen werden, und den Anführungszeichen innerhalb der Zeichenfolge muss \ vorangestellt werden. Beispiele:

"[\"20180505\", \"alantest\"]"

Problembehandlung

Die folgenden Abschnitte enthalten Tipps zur Behandlung allgemeiner Probleme mit der Legacy-Databricks CLI.

Die Verwendung von EOF mit databricks configure funktioniert nicht.

In Version 0.12.0 der Databricks-Befehlszeilenschnittstelle und höheren Versionen kann die Sequenz für das Dateiende (EOF) in einem Skript zum Übergeben von Parametern an den Befehl databricks configure nicht verwendet werden. Das folgende Skript bewirkt beispielsweise, dass die Databricks-Befehlszeilenschnittstelle die Parameter ignoriert, und es wird keine Fehlermeldung ausgelöst:

# Do not do this.
databricksUrl=<per-workspace-url>
databricksToken=<personal-access-token-or-Azure-AD-token>

databricks configure --token << EOF
$databricksUrl
$databricksToken
EOF

Um dieses Problem zu beheben, führen Sie einen der folgenden Schritte aus:

  • Verwenden Sie eine der anderen programmgesteuerten Konfigurationsoptionen, wie unter Einrichten der Authentifizierung beschrieben.
  • Fügen Sie der Datei .databrickscfg manuell die Werte host und token hinzu, wie unter Einrichten der Authentifizierung beschrieben.
  • Stufen Sie Ihre Installation der Databricks-Befehlszeilenschnittstelle auf 0.11.0 oder eine niedrigere Version herab, und führen Sie das Skript erneut aus.

CLI-Befehle