Databricks-Befehlszeilenschnittstelle

Die Databricks-Befehlszeilenschnittstelle (Command-Line Interface, CLI) bietet eine benutzerfreundliche Oberfläche für die Azure Databricks-Plattform. Das Open-Source-Projekt wird auf GitHub gehostet. Die CLI basiert auf der Databricks-REST-API 2.0 und ist basierend auf den Clusterrichtlinien-APIs 2.0,Cluster-API 2.0,DBFS-API 2.0,Gruppen-API 2.0,Instanz in Befehlsgruppen organisiert. Pools API 2.0, Jobs API 2.1, Libraries API 2.0, Repos API 2.0, Secrets API 2.0, Token API 2.0und Workspace API 2.0 über , , , , und , , , , , und Befehlsgruppen bzw.

Wichtig

Diese Befehlszeilenschnittstelle befindet sich derzeit noch in der Entwicklung und wird als experimenteller Client veröffentlicht. Das bedeutet, dass Schnittstellen weiterhin geändert werden können.

Einrichten der CLI

In diesem Abschnitt sind die Anforderungen der CLI aufgeführt. Darüber hinaus wird beschrieben, wie Sie Ihre Umgebung für die Ausführung der CLI installieren und konfigurieren.

Requirements (Anforderungen)

  • Python 3: mindestens 3.6

  • Python 2: mindestens 2.7.9

    Wichtig

    Unter macOS wird bei der Standardinstallation von Python 2 nicht das Protokoll TLSv1_2 implementiert, und bei der Ausführung der 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 zu installieren.

Einschränkungen

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

Installieren der Befehlszeilenschnittstelle

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

Aktualisieren der CLI

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

Führen Sie zum Auflisten der derzeit installierten CLI-Version databricks --version (oder databricks -v) aus.

Einrichten der Authentifizierung

Sie müssen die Authentifizierung einrichten, damit Sie CLI-Befehle ausführen können. Zur Authentifizierung bei der CLI können Sie ein persönliches Databricks-Zugriffstoken oder ein Azure Active Directory-Token (Azure AD) verwenden.

Einrichten der Authentifizierung mit einem Azure AD Token

Um die CLI mit einem Azure AD Token zu konfigurieren, generieren Sie das Azure AD Token, und speichern Sie es in der Umgebungsvariablen .

Unix, Linux, macos
export DATABRICKS_AAD_TOKEN=<Azure-AD-token>

Alternativ können Sie jq verwenden:

export DATABRICKS_AAD_TOKEN=$(az account get-access-token | jq .accessToken --raw-output)
Windows
setx DATABRICKS_AAD_TOKEN "<Azure-AD-token>" /M

Alternativ können Sie Windows PowerShell und jq verwenden:

$databricks_aad_token = az account get-access-token | jq .accessToken --raw-output
[System.Environment]::SetEnvironmentVariable('DATABRICKS_AAD_TOKEN', $databricks_aad_token, [System.EnvironmentVariableTarget]::Machine)`

Führen Sie 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 Unix, 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>

Einrichten der Authentifizierung mit einem persönlichen Databricks-Zugriffstoken

Führen Sie databricks configure --token aus, um die CLI für die Verwendung eines persönlichen Zugriffstokens zu konfigurieren. 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 Unix, 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>

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

Unix, Linux, macos

export DATABRICKS_CONFIG_FILE=<path-to-file>

Windows

setx DATABRICKS_CONFIG_FILE "<path-to-file>" /M

Wichtig

Da die CLI auf der REST-API basiert, hat Ihre Authentifizierungskonfiguration in Ihrer NETRC-Datei Vorrang vor Ihrer Konfiguration in .

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

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN
  • DATABRICKS_CONFIG_PROFILE

Eine Umgebungsvariableneinstellung hat Vorrang vor der Einstellung in der Konfigurationsdatei.

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 Databricks-Befehlszeilenschnittstelle 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.

Aliasbefehlsgruppen

Manchmal kann es unpraktisch sein, jedem CLI-Aufruf den Namen einer Befehlsgruppe voranzustellen, beispielsweise databricks workspace ls. Um die Verwendung der 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

Azure Databricks hat für databricks fs bereits den Alias dbfs erstellt. databricks fs ls und dbfs ls sind identisch.

Verwenden der Befehlszeilenschnittstelle

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

Anzeigen der Hilfe zu CLI-Befehlsgruppen

Die Unterbefehle für eine Befehlsgruppe werden mithilfe von databricks <group> --help (oder databricks <group> -h) aufgelistet. Die Unterbefehle der DBFS-CLI listen Sie beispielsweise mit databricks fs -h auf.

Anzeigen der Hilfe zum CLI-Unterbefehl

Sie rufen die Hilfe für einen Unterbefehl durch Ausführung von databricks <group> <subcommand> --help (oder databricks <group> <subcommand> -h) auf. Die Hilfe für den DBFS-Unterbefehl zum Kopieren von Dateien rufen Sie beispielsweise auf, indem Sie databricks fs cp -h ausführen.

Analysieren der CLI-Ausgabe mithilfe von jq

Einige Befehle der Databricks-Befehlszeilenschnittstelle 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 Befehls vom Typ databricks jobs get als Argument für den Befehl databricks jobs create 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'
{
  "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 die Namen und IDs aller verfügbaren Cluster im Arbeitsbereich aus:

databricks clusters list --output JSON | jq '[ .clusters[] | { name: .cluster_name, id: .cluster_id } ]'
[
  {
    "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 (brew install jq) oder unter Windows mithilfe von Chocolatey (choco install jq) installieren. Weitere Informationen zu jq finden Sie im jq

JSON-Zeichenfolgenparameter

Zeichenfolgenparameter werden je nach Betriebssystem unterschiedlich behandelt:

Unix, Linux, macos

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

databricks jobs run-now --job-id 9 --jar-params '["20180505", "alantest"]'

Windows

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

databricks jobs run-now --job-id 9 --jar-params "[\"20180505\", \"alantest\"]"

Problembehandlung

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

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 manuell die host Werte und token.databrickscfg hinzu, wie unter Einrichten der hostbeschrieben.
  • 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