Antigua CLI de Databricks

La interfaz de línea de comandos heredada de Databricks (también conocida como la CLI heredada de Databricks) 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 - 3.6 y versiones posteriores
• Python 2- 2.7.9 y versiones posteriores

Limitaciones

No se admite el uso de la CLI de Databricks heredada cuando los contenedores de almacenamiento tienen 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.

Instalar la CLI

Ejecute pip install databricks-cli mediante 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 mediante 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 heredados de la CLI de Databricks, debe configurar la autenticación entre la CLI heredada de Databricks 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 heredada de Databricks, puede usar un token de acceso personal de Databricks o un token de Microsoft Entra ID (anteriormente Azure Active Directory).

Set up authentication using a Microsoft Entra ID token

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

Ejecute el siguiente comando:

databricks configure --aad-token

El comando genera 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.

Después de completar el mensaje, 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 .databrickscfg archivo ya existe, el perfil de configuración del DEFAULT archivo se sobrescribe con los nuevos datos. 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:

Después de completar las indicaciones, 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 .databrickscfg archivo ya existe, el perfil de configuración del DEFAULT archivo se sobrescribe con los nuevos datos. 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

LA CLI 0.8.0 y versiones posteriores admiten las siguientes variables de entorno Azure Databricks:

• 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. La misma instalación de la CLI heredada de Databricks se puede usar 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

Mostrar 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, agrega alias dw="databricks workspace" al perfil de Bash adecuado. Normalmente, este archivo se encuentra en ~/.bash_profile.

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 del JSON para pasarlas a otros comandos. Por ejemplo, para copiar una definición de trabajo, debe tomar el campo settings de un comando get job y usarlo como argumento en el comando create job. 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

• Cluster Policies CLI (heredada)
• CLI de clústeres (heredada)
• CLI de DBFS (heredada)
• CLI de canalizaciones declarativas de Spark de Lakeflow (heredada)
• CLI de grupos (heredada)
• CLI de grupos de instancias (heredada)
• CLI de trabajos (heredada)
• CLI de bibliotecas (legado)
• Repos CLI (antigua)
• Ejecuta la CLI (heredada)
• CLI de secretos (obsoleta)
• Stack CLI (legado)
• Tokens CLI (legado)
• CLI de Unity Catalog (obsoleta)
• CLI del área de trabajo (heredada)