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 basa en la API de REST de Databricks y se organiza en grupos de comandos basados en puntos de conexión primarios.

Por ejemplo, puede usar la CLI de Databricks para hacer cosas como:

  • Aprovisionar recursos de proceso en áreas de trabajo de Azure Databricks.
  • Ejecutar tareas de procesamiento de datos y análisis de datos.
  • Enumerar, importar y exportar cuadernos y carpetas en áreas de trabajo.

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:

pip install databricks-cli

Actualización de la CLI

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

pip install databricks-cli --upgrade

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

databricks --version

# Or...

databricks -v

Configuración de la autenticación

Nota:

Como procedimiento recomendado de seguridad, al autenticarse con herramientas, sistemas, scripts y aplicaciones automatizadas, Databricks recomienda usar tokens de acceso que pertenezcan a entidades de servicio en lugar de usuarios del área de trabajo. Para obtener más información, consulte Administración de entidades de servicio.

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 --resource 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d | 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 --resource 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d | jq .accessToken --raw-output
[System.Environment]::SetEnvironmentVariable('DATABRICKS_AAD_TOKEN', $databricks_aad_token, [System.EnvironmentVariableTarget]::Machine)`

Ejecute el siguiente comando:

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 el comando siguiente:

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 si establece 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

A partir de la CLI 0.17.2, la CLI no funciona con un archivo .netrc. Puede tener un archivo .netrc en su entorno para otros fines, pero la CLI no usará ese archivo .netrc.

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

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN

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

Pruebe la configuración de autenticación

Para comprobar si ha configurado correctamente la autenticación, puede ejecutar un comando como el siguiente, reemplazando <someone@example.com> por el nombre de usuario del área de trabajo de Azure Databricks:

databricks workspace ls /Users/<someone@example.com>

Si se ejecuta correctamente, este comando enumera los objetos de la ruta de acceso del área de trabajo especificada.

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.

Prueba de los perfiles de conexión

Para comprobar si ha configurado correctamente los perfiles de conexión, puede ejecutar un comando como el siguiente, reemplazando <someone@example.com> por el nombre de usuario del área de trabajo de Azure Databricks y <DEFAULT> por uno de los nombres de perfil de conexión:

databricks workspace ls /Users/<someone@example.com> --profile <DEFAULT>

Si se ejecuta correctamente, este comando enumera los objetos de la ruta de acceso del área de trabajo especificada en el área de trabajo para el perfil de conexión especificado. Ejecute este comando para cada perfil de conexión que quiera probar.

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:

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:

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

Solucionar problemas

En las siguientes secciones se proporcionan sugerencias para solucionar problemas comunes con la CLI de Databricks.

El uso de EOF con databricks configure no funciona

En el caso de la versión 0.12.0 de la CLI de Databricks y posteriores, el uso de la secuencia de fin de archivo (EOF) en un script para pasar parámetros al comando databricks configure no funciona. Por ejemplo, el siguiente script hace que la CLI de Databricks ignore los parámetros y que no se genere ningún mensaje de error:

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

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

Para solucionar este problema, realice una de las acciones siguientes:

  • Use una de las otras opciones de configuración mediante programación, como se describe en Configuración de la autenticación.
  • Agregue manualmente los valores host y token al archivo .databrickscfg, como se describe en Configuración de la autenticación.
  • Cambie la instalación de la CLI de Databricks a la versión 0.11.0, o una versión inferior, y vuelva a ejecutar el script.

Comandos de la CLI