Freigeben über

Legacy-Databricks-CLI

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 Databricks CLI-Versionen 0.205 und höher finden Sie unter 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 momentan keine neuen Arbeiten an der Legacy-Databricks CLI.

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

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

Anforderungen

  • Python 3 - 3,6 und höher
  • Python 2 - 2.7.9 und höher

Wichtig

Unter macOS implementiert die standardmäßige Python 2-Installation nicht das TLSv1_2 Protokoll, und das Ausführen der älteren Databricks CLI mit dieser Python Installation führt zu dem Fehler: AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'. Verwenden Sie Homebrew, um eine Version von Python 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.

Installiere die CLI

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 databricks --version aus, um die derzeit installierte Version der Legacy-Databricks CLI aufzulisten.

databricks --version

Einrichten der Authentifizierung

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

Um sich mit der älteren Databricks CLI zu authentifizieren, können Sie ein Databricks personal access token oder ein Microsoft Entra ID (ehemals Azure Active Directory)-Token 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.

Authentifizierung mithilfe eines Microsoft Entra ID Tokens einrichten

Um die ältere Databricks CLI mit einem Microsoft Entra ID-Token zu konfigurieren, generieren Sie das Microsoft Entra ID (vormals Azure Active Directory)-Token und speichern Sie 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.

Nachdem Sie die Aufforderung abgeschlossen haben, werden Ihre Zugriffsanmeldeinformationen in der Datei ~/.databrickscfg unter Linux oder macOS oder %USERPROFILE%\.databrickscfg auf Windows 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, indem die Eingabeaufforderung ausgegeben wird:

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:

Nachdem Sie die Eingabeaufforderungen abgeschlossen haben, werden Ihre Zugriffsanmeldeinformationen in der Datei ~/.databrickscfg unter Linux oder macOS oder %USERPROFILE%\.databrickscfg auf Windows 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öher unterstützt 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. Die gleiche Installation von älteren Databricks CLI kann verwendet werden, um API-Aufrufe für mehrere Azure Databricks Arbeitsbereiche auszuführen.

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.

Benutze die CLI

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.

Hilfe zu CLI-Befehlsgruppen anzeigen

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

Alias-Befehlsgruppen

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 z. B. unter macOS installieren, indem Sie Homebrew mit brew install jq oder auf Windows verwenden, indem Sie Chocolatey mit choco install jq verwenden. 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 host manuell die Werte token und .databrickscfg 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

  • Last updated on