Databricks-BefehlszeilenschnittstelleDatabricks CLI

Die Databricks-Befehlszeilenschnittstelle (Command-Line Interface, CLI) bietet eine benutzerfreundliche Oberfläche für die Azure Databricks-Plattform.The Databricks command-line interface (CLI) provides an easy-to-use interface to the Azure Databricks platform. Das Open-Source-Projekt wird auf GitHub gehostet.The open source project is hosted on GitHub. Die CLI basiert auf der Databricks-REST-API 2.0 und ist auf der Grundlage der Arbeitsbereichs-API, Cluster-API, API für Instanzenpools, DBFS-API, Gruppen-API, Auftrags-API, Bibliotheks-API und Geheimnis-API in Befehlsgruppen unterteilt: workspace, clusters, instance-pools, fs, groups, jobs, runs, libraries und secrets.The CLI is built on top of the Databricks REST API 2.0 and is organized into command groups based on the Workspace API, Clusters API, Instance Pools API, DBFS API, Groups API, Jobs API, Libraries API, and Secrets API: workspace, clusters, instance-pools, fs, groups, jobs, runs, libraries, and secrets.

Wichtig

Diese Befehlszeilenschnittstelle befindet sich derzeit noch in der Entwicklung und wird als experimenteller Client veröffentlicht.This CLI is under active development and is released as an Experimental client. Das bedeutet, dass Schnittstellen weiterhin geändert werden können.This means that interfaces are still subject to change.

Einrichten der CLISet up the 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.This section lists CLI requirements and describes how to install and configure your environment to run the CLI.

Requirements (Anforderungen)Requirements

  • Python 3: mindestens 3.6Python 3 - 3.6 and above

  • Python 2: mindestens 2.7.9Python 2 - 2.7.9 and above

    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'.On MacOS, the default Python 2 installation does not implement the TLSv1_2 protocol and running the CLI with this Python installation results in the error: AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'. Verwenden Sie Homebrew, um eine Python-Version mit ssl.PROTOCOL_TLSv1_2 zu installieren.Use Homebrew to install a version of Python that has ssl.PROTOCOL_TLSv1_2.

EinschränkungenLimitations

Die Verwendung der Databricks-CLI mit firewallfähigen Speichercontainern wird nicht unterstützt.Using the Databricks CLI with firewall enabled storage containers is not supported. Databricks empfiehlt die Verwendung von Databricks Connect oder az storage.Databricks recommends you use Databricks Connect or az storage.

Installieren der BefehlszeilenschnittstelleInstall the CLI

Führen Sie pip install databricks-cli mit der entsprechenden Version von pip für Ihre Python-Installation aus.Run pip install databricks-cli using the appropriate version of pip for your Python installation.

Einrichten der Authentifizierung Set up authentication

Sie müssen die Authentifizierung einrichten, damit Sie CLI-Befehle ausführen können.Before you can run CLI commands, you must set up authentication. Zur Authentifizierung bei der CLI können Sie ein persönliches Databricks-Zugriffstoken oder ein Azure Active Directory-Token (Azure AD) verwenden.To authenticate to the CLI you can use a Databricks personal access token or an Azure Active Directory (Azure AD) token.

Einrichten der Authentifizierung mit einem Azure AD TokenSet up authentication using an Azure AD token

Zum Konfigurieren der CLI mithilfe eines Azure AD-Tokens generieren Sie das Azure AD-Token, und speichern Sie es der Umgebungsvariablen DATABRICKS_AAD_TOKEN.To configure the CLI using an Azure AD token, generate the Azure AD token and store it in the environment variable DATABRICKS_AAD_TOKEN.

export DATABRICKS_AAD_TOKEN=<azure-ad-token>

Führen Sie aus databricks configure --aad-token.Run databricks configure --aad-token. Der Befehl gibt die Eingabeaufforderung aus:The command issues the prompt:

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

Geben Sie die URL für den Arbeitsbereich im Format adb-<workspace-id>.<random-number>.azuredatabricks.net ein. Informationen zum Abrufen den Arbeitsbereich-URL finden Sie unter URL pro Arbeitsbereich.Enter your per-workspace URL, with the format adb-<workspace-id>.<random-number>.azuredatabricks.net To get the per-workspace URL, see Per-workspace URL.

Nach Ihrer Eingabe werden die Anmeldeinformationen für den Zugriff in der Datei ~/.databrickscfg gespeichert.After you complete the prompt, your access credentials are stored in the file ~/.databrickscfg. Die Datei sollte etwa folgende Einträge enthalten:The file should contain entries like:

host = https://<databricks-instance>
token =  <azure-ad-token>

Einrichten der Authentifizierung mit einem persönlichen Databricks-ZugriffstokenSet up authentication using a Databricks personal access token

Führen Sie databricks configure --token aus, um die CLI für die Verwendung des persönlichen Zugriffstoken zu konfigurieren.To configure the CLI to use the personal access token, run databricks configure --token. Der Befehl gibt die folgenden Eingabeaufforderungen aus:The command issues the prompts:

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

Nach Ihrer Eingabe werden die Anmeldeinformationen für den Zugriff in der Datei ~/.databrickscfg gespeichert.After you complete the prompts, your access credentials are stored in the file ~/.databrickscfg. Die Datei sollte etwa folgende Einträge enthalten:The file should contain entries like:

host = https://<databricks-instance>
token =  <personal-access-token>

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.For CLI 0.8.1 and above, you can change the path of this file by setting the environment variable DATABRICKS_CONFIG_FILE.

Wichtig

Da die CLI auf der REST-API aufbaut, hat die Authentifizierungskonfiguration in der NETRC-Datei Vorrang vor der Konfiguration in .databrickscfg.Because the CLI is built on top of the REST API, your authentication configuration in your .netrc file takes precedence over your configuration in .databrickscfg.

CLI 0.8.0 und höhere Versionen unterstützen die folgenden Umgebungsvariablen:CLI 0.8.0 and above supports the following environment variables:

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN

Eine Umgebungsvariableneinstellung hat Vorrang vor der Einstellung in der Konfigurationsdatei.An environment variable setting takes precedence over the setting in the configuration file.

Verbindungsprofile Connection profiles

Die Konfiguration der Databricks-Befehlszeilenschnittstelle unterstützt mehrere Verbindungsprofile.The Databricks CLI configuration supports multiple connection profiles. Für API-Aufrufe für mehrere Azure Databricks-Arbeitsbereiche kann die gleiche Installation der Databricks-Befehlszeilenschnittstelle verwendet werden.The same installation of Databricks CLI can be used to make API calls on multiple Azure Databricks workspaces.

So fügen Sie ein Verbindungsprofil hinzu:To add a connection profile:

databricks configure [--profile <profile>]

So verwenden Sie das Verbindungsprofil:To use the connection profile:

databricks workspace ls --profile <profile>

Aliasbefehlsgruppen Alias command groups

Manchmal kann es unpraktisch sein, jedem CLI-Aufruf den Namen einer Befehlsgruppe voranzustellen, beispielsweise databricks workspace ls.Sometimes it can be inconvenient to prefix each CLI invocation with the name of a command group, for example databricks workspace ls. Um die Verwendung der CLI zu vereinfachen, können Sie Aliasbefehlsgruppen für kürzere Befehle verwenden.To make the CLI easier to use, you can alias command groups to shorter commands. 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.For example to shorten databricks workspace ls to dw ls in the Bourne again shell, you can add alias dw="databricks workspace" to the appropriate bash profile. Diese Datei befindet sich in der Regel unter ~/.bash_profile.Typically, this file is located at ~/.bash_profile.

Tipp

Azure Databricks hat für databricks fs den Alias dbfs erstellt. databricks fs ls und dbfs ls sind identisch.Azure Databricks has already aliased databricks fs to dbfs; databricks fs ls and dbfs ls are equivalent.

Verwenden der BefehlszeilenschnittstelleUse the CLI

In diesem Abschnitt erfahren Sie, wie Sie die CLI-Hilfe aufrufen, die CLI-Ausgabe analysieren und Befehle in jeder Befehlsgruppe aufrufen.This section shows you how to get CLI help, parse CLI output, and invoke commands in each command group.

Anzeigen der Hilfe zu CLI-BefehlsgruppenDisplay CLI command group help

Die Unterbefehle für eine Befehlsgruppe werden mithilfe von databricks <group> -h aufgelistet.You list the subcommands for any command group by running databricks <group> -h. Die Unterbefehle der DBFS-CLI listen Sie beispielsweise mit databricks fs -h auf.For example, you list the DBFS CLI subcommands by running databricks fs -h.

Analysieren der CLI-Ausgabe mithilfe von jq Use jq to parse CLI output

Einige Befehle der Databricks-Befehlszeilenschnittstelle geben die JSON-Antwort vom API-Endpunkt aus.Some Databricks CLI commands output the JSON response from the API endpoint. Manchmal kann es hilfreich sein, Teile des JSON-Codes zu analysieren, um sie an andere Befehle zu übergeben.Sometimes it can be useful to parse out parts of the JSON to pipe into other commands. Zum Kopieren einer Auftragsdefinition müssen Sie beispielsweise das Feld settings von /api/2.0/jobs/get als Argument für den Befehl databricks jobs create verwenden.For example, to copy a job definition, you must take the settings field of /api/2.0/jobs/get and use that as an argument to the databricks jobs create command.

In diesen Fällen empfiehlt es sich, das Hilfsprogramm jq zu verwenden.In these cases, we recommend you to use the utility jq. Sie können jq unter MacOS mit Homebrew und brew install jq installieren.You can install jq on MacOS using Homebrew with brew install jq.

Weitere Informationen zu jq finden Sie im Leitfaden zu jq.For more information on jq, see the jq Manual.

JSON-ZeichenfolgenparameterJSON string parameters

Zeichenfolgenparameter werden je nach Betriebssystem unterschiedlich behandelt:String parameters are handled differently depending on your operating system:

  • Unix: JSON-Zeichenfolgenparameter müssen in einfache Anführungszeichen eingeschlossen werden.Unix: You must enclose JSON string parameters in single quotes. Beispiel:For example:

    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.Windows: You must enclose JSON string parameters in double quotes, and the quote characters inside the string must be preceded by \. Beispiel:For example:

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

CLI-BefehleCLI commands