Compartir a través de

CLI de Databricks (heredada)

  • Artículo

Importante

Esta documentación se ha retirado y es posible que no se actualice.

Databricks recomienda usar la versión 0.205 o posterior de la CLI de Databricks, en lugar de la versión heredada de la CLI de Databricks 0.18 o anterior. La versión 0.18 o inferior de la CLI de Databricks no es compatible con Databricks. Para obtener información sobre las versiones 0.205 y superiores de la CLI de Databricks, consulte ¿Qué es la CLI de Databricks?.

Para migrar de la versión 0.18 o inferior a la versión 0.205 o superior de la CLI de Databricks, consulte Migración de la CLI de Databricks.

La CLI de Databricks heredada está en un estado Experimental. Databricks no planea ninguna característica nueva para la CLI de Databricks heredada en este momento.

La CLI de Databricks heredada no se admite a través de los canales de soporte técnico de Databricks. Si quiere hacer comentarios, formular preguntas y notificar problemas, use la pestaña Problemas en el repositorio Interfaz de línea de comandos para Databricks en GitHub.

La interfaz de línea de comandos de Databricks heredada (también conocida como CLI de Databricks heredada) es una utilidad que proporciona una interfaz fácil de usar para automatizar la plataforma de Azure Databricks desde el terminal, el símbolo del sistema o los scripts de automatización.

Requisitos

  • Python 3 a 3.6 y versiones posteriores
  • Python 2 a 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 de Databricks heredada 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 heredada con contenedores de almacenamiento con el firewall habilitado. Databricks recomienda usar Databricks Connect o az storage.

Configuración de la CLI

En esta sección se describe cómo configurar la CLI de Databricks heredada.

Instalación o actualización de la CLI

En esta sección se describe cómo instalar o actualizar la máquina de desarrollo para ejecutar la CLI de Databricks heredada.

Instalación de la CLI de Azure

Ejecute pip install databricks-cli usando 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 usando 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 de Databricks heredada que está instalada actualmente, ejecute databricks --version:

databricks --version

Configuración de la autenticación

Para poder ejecutar comandos de la CLI de Databricks heredada, debe configurar la autenticación entre la CLI de Databricks heredada y Azure Databricks. En esta sección se describe cómo configurar la autenticación para la CLI de Databricks heredada.

Para autenticarse con la CLI de Databricks heredada, puede usar un token de acceso personal de Databricks o un token de Microsoft Entra ID (anteriormente Azure Active Directory).

Nota:

Como procedimiento recomendado de seguridad, cuando se autentique con herramientas, sistemas, scripts y aplicaciones automatizados, Databricks recomienda usar los tokens de acceso personal pertenecientes a las entidades de servicio en lugar de a los usuarios del área de trabajo. Para crear tókenes para entidades de servicio, consulte Administración de tokens de acceso para una entidad de servicio.

Configuración de la autenticación mediante un token de Microsoft Entra ID (anteriormente Azure Active Directory)

Para configurar la CLI de Databricks heredada mediante un token de Microsoft Entra ID, generar el token de Microsoft Entra ID (anteriormente Azure Active Directory) y almacenarlo en la variable de entorno DATABRICKS_AAD_TOKEN.

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 Linux o macOS, o %USERPROFILE%\.databrickscfg en Windows. El archivo contiene una entrada de perfil predeterminada:

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

Si el archivo .databrickscfg ya existe, el perfil de configuración DEFAULT de ese archivo se sobrescribe con los datos nuevos. En su lugar, para crear un perfil de configuración con un nombre diferente, consulte Perfiles de conexión.

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

Para configurar la CLI de Databricks heredada 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 Linux o macOS, o %USERPROFILE%\.databrickscfg en Windows. El archivo contiene una entrada de perfil predeterminada:

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

Si el archivo .databrickscfg ya existe, el perfil de configuración DEFAULT de ese archivo se sobrescribe con los datos nuevos. En su lugar, para crear un perfil de configuración con un nombre diferente, consulte Perfiles de conexión.

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.

Linux o 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 superiores) admite las variables de entorno de Azure Databricks siguientes:

  • 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:

databricks fs ls dbfs:/

Si se ejecuta correctamente, este comando enumera los archivos y directorios de la raíz de DBFS del área de trabajo asociada al perfil DEFAULT.

Perfiles de conexión

La configuración de la CLI de Databricks heredada admite varios perfiles de conexión. Se puede usar la misma instalación de la CLI de Databricks heredada 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 configura correctamente los perfiles de conexión, puede ejecutar un comando como el siguiente con uno de los nombres de perfil de conexión:

databricks fs ls dbfs:/ --profile <profile-name>

Si se ejecuta correctamente, este comando enumera los archivos y directorios de la raíz de DBFS del área de trabajo para el perfil de conexión especificado. Ejecute este comando para cada perfil de conexión que quiera probar.

Para ver los perfiles disponibles, consulte el archivo .databrickscfg.

Uso de la CLI

En esta sección se muestra cómo obtener ayuda de la CLI de Databricks heredada, analizar la salida de la CLI de Databricks heredada 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 la opción --help o -h. Por ejemplo, para enumerar los subcomandos de la CLI de DBFS:

databricks fs -h

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

Enumere la ayuda de un subcomando mediante la opción --help o -h. Por ejemplo, para enumerar la ayuda para el subcomando de copia de archivos DBFS:

databricks fs cp -h

Creación de alias de grupos de comandos

A veces puede resultar inconveniente prefijar cada invocación de la CLI de Databricks heredada con el nombre de un grupo de comandos, por ejemplo databricks workspace ls en la CLI de Databricks heredada. Para facilitar el uso de la CLI de Databricks heredada, 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

La CLI de Databricks heredada ya ha acortado databricks fs como dbfs; databricks fs ls y dbfs ls son equivalentes.

Uso de jq para analizar la salida de la CLI

Algunos comandos de la CLI de Databricks heredada 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 de obtener trabajo y usarlo como argumento en el comando de crear trabajo. 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'

Salida:

{
  "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 solo 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 } ]'

Salida:

[
  {
    "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:

Linux o macOS

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

'["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:

"[\"20180505\", \"alantest\"]"

Solución de problemas

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

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