CLI de Databricks

La interfaz de la línea de comandos (CLI) de Databricks proporciona una interfaz fácil de usar para la plataforma de Azure Databricks. El proyecto de código abierto se hospeda en GitHub. La CLI se crea sobre la API REST 2.0 de Databricks y se organiza en grupos de comandos basados en Cluster Policies API, Clusters API, DBFS API, Groups API, Instance Pools API, Jobs API, Libraries API, Secrets API, Token API y Workspace API, a través de los grupos de comandos cluster-policies, clusters, fs, groups, instance-pools, jobs, runs, libraries, secrets, tokens y workspace respectivamente.

Importante

Esta CLI se encuentra en desarrollo activo y se publica como un cliente Experimental. Esto significa que las interfaces siguen estando sujetas a cambios.

Configuración de la CLI

En esta sección se enumeran los requisitos de la CLI y se describe cómo instalar y configurar un entorno para ejecutar la CLI.

Requisitos

  • Python 3: 3.6 y versiones posteriores

  • Python 2: 2.7.9 y versiones posteriores

    Importante

    En macOS, la instalación predeterminada de Python 2 no implementa el protocolo TLSv1_2 y si la CLI se ejecuta con esta instalación de Python, se produce el error: AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'. Use Homebrew para instalar una versión de Python que tenga ssl.PROTOCOL_TLSv1_2.

Limitaciones

No se admite el uso de la CLI de Databricks CLI con contenedores de almacenamiento con el firewall habilitado. Databricks recomienda usar Databricks Connect o az storage.

Instalación de la CLI de Azure

Ejecute pip install databricks-cli con la versión adecuada de pip para la instalación de Python.

Actualización de la CLI

Ejecute pip install databricks-cli --upgrade con la versión adecuada de pip para la instalación de Python.

Para mostrar la versión de la CLI que está instalada actualmente, ejecute databricks --version (o databricks -v).

Configuración de la autenticación

Antes de poder ejecutar los comandos de la CLI, debe configurar la autenticación. Para autenticarse en la CLI puede usar un token de acceso personal de Databricks o un token de Azure Active Directory (Azure AD).

Configuración de la autenticación mediante un token de Azure AD

Para configurar la CLI mediante un token de Azure AD, genérelo y almacénelo en la variable de entorno DATABRICKS_AAD_TOKEN.

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

O bien, mediante jq:

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

o bien, mediante Windows PowerShell y jq:

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

Ejecute databricks configure --aad-token. El comando genera la solicitud:

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

Escriba la dirección URL por área de trabajo, con el formato https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Para obtener la dirección URL por área de trabajo, consulte Dirección URL por área de trabajo.

Una vez completada la solicitud, las credenciales de acceso se almacenan en el archivo ~/.databrickscfg en Unix, Linux o macOS, o %USERPROFILE%\.databrickscfg en Windows. El archivo contiene una entrada de perfil predeterminada:

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

Configuración de la autenticación mediante un token de acceso personal de Databricks

Para configurar la CLI para que use un token de acceso, ejecute databricks configure --token. El comando comienza emitiendo el mensaje:

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

Escriba la dirección URL por área de trabajo, con el formato https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Para obtener la dirección URL por área de trabajo, consulte Dirección URL por área de trabajo.

El comando continúa emitiendo el mensaje para que especifique el token de acceso personal:

Token:

Una vez completadas las solicitudes, las credenciales de acceso se almacenan en el archivo ~/.databrickscfg en Unix, Linux o macOS, o %USERPROFILE%\.databrickscfg en Windows. El archivo contiene una entrada de perfil predeterminada:

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

En el caso de la CLI 0.8.1 y versiones posteriores, puede cambiar la ruta de acceso de este archivo estableciendo la variable de entorno DATABRICKS_CONFIG_FILE.

Unix, linux, macos

export DATABRICKS_CONFIG_FILE=<path-to-file>

Windows

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

Importante

Como la CLI se ha creado sobre la API REST, la configuración de autenticación en el archivo .netrc tiene prioridad sobre la configuración de .databrickscfg.

La CLI 0.8.0 (o versiones posteriores) admite las siguientes variables de entorno:

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN
  • DATABRICKS_CONFIG_PROFILE

La configuración de una variable de entorno tiene prioridad sobre la configuración del archivo de configuración.

Perfiles de conexión

La configuración de la CLI de Databricks admite varios perfiles de conexión. Se puede usar la misma instalación de la CLI de Databricks para realizar llamadas API en varias áreas de trabajo de Azure Databricks.

Para agregar un perfil de conexión, especifique un nombre único para el perfil:

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

El archivo .databrickscfg contiene una entrada de perfil correspondiente:

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

Para utilizar el perfil de conexión:

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

Si no se especifica --profile <profile-name>, se utiliza el perfil predeterminado. Si no se encuentra ningún perfil predeterminado, se le pedirá que configure la CLI con un perfil predeterminado.

Creación de alias de grupos de comandos

A veces puede resultar inconveniente prefijar cada invocación de CLI con el nombre de un grupo de comandos, por ejemplo databricks workspace ls. Para facilitar el uso de la CLI, puede asignar alias a los grupos de comandos para hacer los comandos más cortos. Por ejemplo, para acortar databricks workspace ls a dw ls en el shell de Bourne-Again Shell (Bash), puede agregar alias dw="databricks workspace" al perfil de Bash adecuado. Normalmente, este archivo se encuentra en ~/.bash_profile.

Sugerencia

Azure Databricks ya ha acortado databricks fs como dbfs; databricks fs ls y dbfs ls son equivalentes.

Uso de la CLI

En esta sección se muestra cómo obtener ayuda de la CLI, analizar la salida de la CLI e invocar comandos en cada grupo de comandos.

Mostrar la ayuda del grupo de comandos de la CLI

Para enumerar los subcomandos de cualquier grupo de comandos, ejecute databricks <group> --help (o databricks <group> -h). Por ejemplo, para mostrar los subcomandos de la CLI de DBFS, puede ejecutar databricks fs -h.

Visualización de la ayuda de un subcomando de la CLI

Para mostrar la ayuda de un subcomando, ejecute databricks <group> <subcommand> --help (o databricks <group> <subcommand> -h). Por ejemplo, puede enumerar la ayuda para el subcomando de copia de archivos DBFS mediante la ejecución de databricks fs cp -h.

Uso de jq para analizar la salida de la CLI

Algunos comandos de la CLI de Databricks generan una respuesta JSON desde el punto de conexión de la API. A veces puede resultar útil analizar partes de esta respuesta JSON para canalizar en otros comandos. Por ejemplo, para copiar una definición de trabajo, debe tomar el campo settings de un comando databricks jobs get y usarlo como argumento en el comando databricks jobs create. En estos casos, se recomienda usar la utilidad jq.

Por ejemplo, el comando siguiente imprime la configuración del trabajo con el identificador 233.

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
}

En otro ejemplo, el comando siguiente imprime los nombres y los identificadores de todos los clústeres disponibles del área de trabajo:

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"
  }
]

Puede instalar jq, por ejemplo en macOS, mediante Homebrew con brew install jq o en Windows mediante Chocolatey con choco install jq. Para más información sobre jq, consulte el manual de jq.

Parámetros de cadena JSON

Los parámetros de cadena se utilizan de forma diferente, en función del sistema operativo:

Unix, linux, macos

los parámetros de cadena JSON deben escribirse entre comillas simples. Por ejemplo:

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

Windows

los parámetros de cadena JSON deben escribirse entre comillas dobles y los caracteres de cita que haya dentro de la cadena deben ir precedidos de \. Por ejemplo:

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

Comandos de la CLI