Compartir a través de

Migración de la CLI de Databricks

  • Artículo

En este artículo se describe cómo migrar de la CLI de Databricks, versión 0.18 o anterior, a la CLI de Databricks, versión 0.205 o posterior. Las versiones 0.205 y posteriores de la CLI de Databricks están en Versión preliminar pública.

Por motivos de brevedad, en este artículo se hace referencia a las versiones 0.18 y posteriores de la CLI de Databricks, como la CLI "heredada", y a las versiones 0.205 y posteriores de la CLI de Databricks, como la CLI "nueva".

Para obtener más información sobre las CLI heredadas y nuevas, consulte:

Desinstalación de la CLI heredada

Si tiene instalada la CLI heredada y quiere desinstalarla, use pip (o pip3, según la versión de Python) para ejecutar el comando uninstall, tal como se indica a continuación:

pip uninstall databricks-cli

Instalación de la nueva CLI

Para obtener información sobre cómo instalar la nueva CLI, consulte Instalación o actualización de la CLI de Databricks.

Comprobación de la instalar de la CLI

Si no sabe con certeza si está usando la nueva CLI, siga las instrucciones de esta sección para comprobarlo y hacer los ajustes necesarios. Antes de seguir estas instrucciones, asegúrese de salir de todos los entornos virtuales de Python, entornos conda o entornos similares.

Para comprobar la versión de la instalación predeterminada de la CLI, ejecute el siguiente comando:

databricks -v

Si el número de versión no es lo que esperaba, realice una de las siguientes acciones:

  • Si solo quiere usar una versión de la CLI: desinstale todas la versiones anteriores de la CLI que ya no quiera usar. Es posible que tenga que actualizar la variable PATH del sistema operativo para que aparezca la ruta de acceso a la versión de la CLI que desea usar.
  • Si desea seguir usando varias versiones de la CLI: anteponga la ruta de acceso completa a la versión de la CLI que quiere usar para cada llamada a la CLI.
  • Si desea seguir usando varias versiones de la CLI, pero no quiere anteponer la ruta de acceso completa a la versión de la CLI que usa con más frecuencia: asegúrese de que la ruta de acceso completa a esa versión aparece en primer lugar en la variable PATH del sistema operativo. Tenga en cuenta que todavía deberá anteponer la ruta de acceso completa a las versiones de la CLI que no aparecen en primer lugar en la variable PATH del sistema operativo.

Para actualizar la variable PATH del sistema operativo, haga lo siguiente:

MacOS o Linux

  1. Enumere las rutas de acceso donde está instalado databricks mediante la ejecución de uno de los siguientes comandos:

    which -a databricks

# Or:
where databricks

  2. Obtenga la ruta de acceso a la instalación que desea usar sin tener que anteponer la ruta de acceso completa a cada llamada a la CLI. Si no sabe con certeza qué ruta de acceso es, ejecute la ruta de acceso completa a cada ubicación seguida de -v, por ejemplo:

    /usr/local/bin/databricks -v

  3. Para colocar la ruta de acceso a la instalación que desea usar primero en la variable PATH, ejecute el siguiente comando reemplazando /usr/local/bin por la ruta de acceso que desea usar. No agregue databricks al final de esta ruta de acceso. Por ejemplo:

    export PATH="/usr/local/bin:$PATH"

  4. Para comprobar que la variable PATH ha establecido correctamente para la sesión de terminal actual, ejecute databricks seguido -v y compruebe el número de versión:

    databricks -v

  5. Para que la variable PATH se establezca de esta manera cada vez que reinicie el terminal, agregue el comando del paso 3 al archivo de inicialización del shell. Por ejemplo, para Zshell, este archivo se encuentra normalmente en ~/.zshrc. En el caso de Bash, este archivo se encuentra normalmente en ~/.bashrc. Para otros shells, consulte la documentación del proveedor del shell.

  6. Después de actualizar el archivo de inicialización del shell, debe reiniciar el terminal para aplicar el valor de PATH actualizado.

Windows

  1. Haga clic con el botón derecho en la instalación de databricks que desea usar sin tener que anteponer la ruta de acceso completa a cada llamada a la CLI.

  2. Haga clic en Abrir ubicación del archivo.

  3. Observe la ruta de acceso a databricks, por ejemplo, C:\Windows.

  4. En el menú Inicio, busque Variables de entorno.

  5. Haga clic en Editar las variables de entorno de esta cuenta.

  6. Seleccione la variable Path en la sección Variables de usuario para <username>.

  7. Haga clic en Editar.

  8. Haga clic en Nueva.

  9. Escriba la ruta de acceso que desea agregar, sin databricks.exe (por ejemplo, C:\Windows).

  10. Use el botón Subir para mover la ruta de acceso que acaba de agregar al principio de la lista.

  11. Haga clic en OK.

  12. Para comprobar que se PATH ha establecido correctamente, abra un nuevo símbolo del sistema, ejecute databricks seguido de -v y compruebe el número de versión:

    databricks -v

Uso de tipos de autenticación adicionales

La CLI heredada y la nueva CLI admiten la autenticación de tokens de acceso personal de Azure Databricks. Sin embargo, Databricks recomienda usar otros tipos de autenticación de Azure Databricks si es posible, que solo la nueva CLI admite.

Si debe usar la autenticación de tokens de acceso personal de Azure Databricks, Databricks recomienda usar una asociada a una entidad de servicio en lugar de a un usuario de área de trabajo o una cuenta de Azure Databricks. Consulte: Administración de entidades de servicio.

La nueva CLI admite tokens de Microsoft Entra ID además de tokens de acceso personal de Azure Databricks. Estos tokens adicionales son más seguros, ya que suelen caducar en el plazo de una hora, mientras que los tokens de acceso personal de Azure Databricks pueden ser válidos desde un día hasta indefinidamente. Esto es particularmente importante si un token se registra accidentalmente en sistemas de control de versiones a los que pueden acceder otros usuarios. Además, la nueva CLI puede actualizar automáticamente estos tokens adicionales cuando expiren, mientras que la actualización de los tokens de acceso personal de Azure Databricks es un proceso manual o puede ser difícil de automatizar.

Para obtener más información, consulte Autenticación para la CLI de Databricks.

Comparaciones de comandos y grupos de comandos

En la siguiente tabla se muestran los grupos de comandos de la CLI heredada y los equivalentes de la nueva CLI. En los casos en los que existen diferencias significativas entre las CLI, en las tablas adicionales se indican los comandos u opciones de la CLI heredada y los equivalentes de la nueva CLI.

Grupos de comandos

Grupo de comandos heredado Nuevo grupo de comandos
cluster-policies cluster-policies. Los nombres de los comandos son los mismos.
clusters clusters. Los nombres de los comandos son los mismos.
configure configure. Consulte las opciones de configuración.
fs fs. Consulte los comandos fs.
groups groups. Consulte los comandos de grupos.
instance-pools instance-pools. Los nombres de los comandos son los mismos.
jobs jobs. Los nombres de los comandos son los mismos.
libraries libraries. Los nombres de los comandos son los mismos, excepto list. El comando list ya no está disponible; use los comandos all-cluster-statuses o cluster-status en su lugar.
pipelines pipelines. Consulte los comandos de canalizaciones.
repos repos. Los nombres de los comandos son los mismos.
runs jobs. Consulte los comandos de ejecución.
secrets secrets. Consulte los comandos de secretos.
stack No disponible en la nueva CLI. Databricks recomienda usar en su lugar el Proveedor de Databricks Terraform.
tokens tokens. Consulte los comandos de tokens.
unity-catalog Varios. Consulte los grupos de comandos unity-catalog.
workspace workspace. Consulte los comandos de área de trabajo.

Opciones de configure

Opción heredada Nueva opción
-o La CLI heredada usa -o para la autenticación de OAuth. La nueva CLI reutiliza -o para especificar si la salida de la CLI está en formato de texto o JSON. No se aplica a Azure Databricks.
--oauth No se aplica a Azure Databricks.
-s o --scope No se aplica a Azure Databricks.
-t o --token -t o --token (igual)
-f o --token-file No disponible en la nueva CLI.
--host --host (igual)
--aad-token Use --host y, cuando se le solicite, especifique un token de Microsoft Entra ID en lugar de un token de acceso personal de Azure Databricks.
--insecure No disponible en la nueva CLI.
--jobs-api-version No disponible en la nueva CLI. La nueva CLI solo usa la API Jobs 2.1. Para llamar a la API Jobs 2.0 heredada, use la CLI heredada y consulte CLI de trabajos (heredada).
--debug Para la depuración y el registro en la nueva CLI, consulte Modo de depuración.
--profile --profile (igual) o -p
-h o --help -h o --help (igual)

Comandos de fs

Todos los comandos fs de la CLI heredada son los mismos en la nueva CLI, excepto fs mv, que no está disponible en la nueva CLI.

Comando heredado Nuevo comando
fs cat fs cat (igual)
fs cp fs cp (igual)
fs ls fs ls (igual)
fs mkdirs fs mkdir
fs mv No disponible en la nueva CLI.
fs rm fs rm (igual)

Comandos de groups

Comando heredado Nuevo comando
groups add-member groups patch
groups create groups create (igual)
groups delete groups delete (igual)
groups list groups list (igual)
groups list-members groups list
groups list-parents groups list
groups remove-member groups patch

Comandos de pipelines

Comando heredado Nuevo comando
pipelines create pipelines create (igual)
pipelines delete pipelines delete (igual)
pipelines deploy pipelines create
pipelines edit pipelines update
pipelines get pipelines get (igual)
pipelines list pipelines list-pipeline-events, pipelines list-pipelines o pipelines list-updates
pipelines reset pipelines reset (igual)
pipelines start pipelines start update
pipelines stop pipelines stop (igual)
pipelines update pipelines update (igual)

Comandos de runs

Comando heredado Nuevo comando
runs cancel jobs cancel-run
runs get jobs get-run
runs get-output jobs get-run-output
runs list jobs list-runs
runs submit jobs submit

Comandos de secrets

Comando heredado Nuevo comando
secrets create-scope secrets create-scope (igual)
secrets delete secrets delete-secret
secrets delete-acl secrets delete-acl (igual)
secrets delete-scope secrets delete-scope (igual)
secrets get-acl secrets get-acl (igual)
secrets list secrets list-secrets
secrets list-acls secrets list-acls (igual)
secrets list-scopes secrets list-scopes (igual)
secrets put secrets put-secret
secrets put-acl secrets put-acl (igual)
secrets write secrets put-secret
secrets write-acl secrets put-acl

Comandos de tokens

Comando heredado Nuevo comando
tokens create tokens create (igual)
tokens list tokens list (igual)
tokens revoke tokens delete

Grupos de comandos unity-catalog

unity-catalog <command> de la CLI heredada se convierte en <command> en la nueva CLI.

Grupo de comandos heredado Nuevo grupo de comandos
unity-catalog catalogs catalogs (igual, pero quitando unity-catalog)
unity-catalog external-locations external-locations (igual, pero quitando unity-catalog)
unity-catalog lineage No disponible en la nueva CLI. Consulte Recuperación del linaje mediante la API de REST de linaje de datos.
unity-catalog metastores metastores (igual, pero quitando unity-catalog)
unity-catalog permissions grants
unity-catalog providers providers (igual, pero quitando unity-catalog)
unity-catalog recipients recipients (igual, pero quitando unity-catalog)
unity-catalog schemas schemas (igual, pero quitando unity-catalog)
unity-catalog shares shares (igual, pero quitando unity-catalog)
unity-catalog storage-credentials storage-credentials (igual, pero quitando unity-catalog)
unity-catalog tables tables (igual, pero quitando unity-catalog)

Comandos de workspace

Comando heredado Nuevo comando
workspace delete workspace delete (igual)
workspace export workspace export (igual)
workspace export-dir workspace export
workspace import workspace import (igual)
workspace import-dir workspace import
workspace list workspace list (igual)
workspace ls workspace list
workspace mkdirs workspace mkdirs (igual)
workspace rm workspace delete

Argumentos posicionales y predeterminados

La mayoría de los nuevos comandos de la CLI tienen al menos un argumento predeterminado que no tiene una opción complementaria. Algunos de los comandos de la CLI nueva tienen dos o más argumentos posicionales que se deben especificar en un orden determinado y que no tienen opciones complementarias. Esto no ocurre en la CLI heredada, donde la mayoría de los comandos requieren que se especifiquen opciones para todos los argumentos. Por ejemplo, el comando clusters get de la nueva CLI toma un identificador de clúster como argumento predeterminado. Sin embargo, el comando clusers get de la CLI heredada requiere que especifique una opción --cluster-id junto con el identificador del clúster. Por ejemplo:

Para la CLI heredada:

# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d

# This does **not** work with the legacy CLI - "Error:
#   Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d

Para la nueva CLI:

# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d

# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d

Como otro ejemplo, el comando grants get de la nueva CLI toma dos argumentos predeterminados: el tipo protegible seguido del nombre completo del elemento protegible. Sin embargo, el comando unity-catalog permissions get de la CLI heredada requiere que especifique una opción --<securable-type> junto con el nombre completo del elemento protegible. Por ejemplo:

Para la CLI heredada:

databricks unity-catalog permissions get --schema main.default

Para la nueva CLI:

# This works with the new CLI.
databricks grants get schema main.default

# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default

Modo de depuración

La CLI heredada proporciona una opción --debug para mostrar el seguimiento completo de la pila en caso de error. En el caso de la nueva CLI, no se reconoce la opción --debug. Use las siguientes opciones en su lugar:

  • Use --log-file <path> para escribir la información de registro en el archivo especificado en <path>. Si no se proporciona esta opción, la información de registro se genera en stderr. Si se especifica --log-file sin especificar --log-level, tampoco se escribirá la información de registro en el archivo.
  • Use --log-format <type> para especificar el formato de la información registrada. <type> puede ser text (valor predeterminado, si no se especifica) o json.
  • Use --log-level <format> para especificar el nivel de información registrada. Los valores permitidos son disabled (el valor predeterminado, si no se especifica), trace, debug, info, warn y error.

En el caso de la CLI heredada, en el ejemplo siguiente se muestra el seguimiento completo de la pila en caso de error:

databricks fs ls / --debug

# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"

En el caso de la nueva CLI, en el ejemplo siguiente se registra el seguimiento completo de la pila en un archivo denominado new-cli-errors.log en el directorio de trabajo actual. El seguimiento de la pila se escribe en el archivo en formato JSON:

databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace

# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)

Preguntas frecuentes

En esta sección se enumeran las preguntas comunes sobre la migración de la versión heredada a la nueva CLI.

¿Qué ocurre con la CLI heredada?

La CLI heredada sigue estando disponible, pero no recibirá ninguna actualización no crítica. Así se refleja en la documentación de la CLI heredada. Databricks recomienda que los usuarios migren a la nueva CLI lo antes posible.

La CLI heredada siempre se ha encontrado en un estado experimental, con la advertencia de que Databricks no tiene previsto trabajar en nuevas características para la CLI heredada, y de que la CLI heredada no recibe soporte a través de los canales de soporte técnico de Databricks.

¿Cuándo quedará en desuso la CLI heredada?

La CLI heredada siempre se ha encontrado en un estado experimental, con la advertencia de que Databricks no tiene previsto trabajar en nuevas características para la CLI heredada, y de que la CLI heredada no recibe soporte a través de los canales de soporte técnico de Databricks.

Databricks no ha establecido una fecha o escala de tiempo para poner en desuso la CLI heredada. Sin embargo, Databricks recomienda que los usuarios migren a la nueva CLI lo antes posible.

¿Cuándo se publicará la nueva CLI con disponibilidad general?

No se ha establecido una fecha o escala de tiempo de publicación de la nueva CLI, ya que no se ha establecido la disponibilidad general. Dependerá de los comentarios que Databricks reciba de los usuarios durante la Versión preliminar pública.

¿Cuáles son las principales diferencias entre las CLI heredadas y nuevas?

  • La CLI heredada se publicó como un paquete de Python. La nueva CLI se publica como un ejecutable independiente y no necesita ninguna dependencia en tiempo de ejecución instalada.
  • La nueva CLI tiene una cobertura completa de las API de REST de Databricks. La CLI heredada no la tiene.
  • La nueva CLI está disponible como Versión preliminar pública. La CLI heredada permanece en un estado experimental.

¿La nueva CLI tiene paridad de características completa con la CLI heredada?

La nueva CLI tiene cobertura para casi todos los comandos de la CLI heredada. Sin embargo, hay que destacar la ausencia en la nueva CLI del grupo de comandos de stacks de la CLI heredada. Además, algunos de los grupos de comandos de la CLI heredada, como unity-catalog y runs, se han reutilizado en nuevos grupos de comandos en la nueva CLI. Para ver las instrucciones de migración, consulte la información proporcionada anteriormente en este artículo.

¿Cómo puedo migrar de CLI heredada a la nueva?

Para ver las instrucciones de migración, consulte la información proporcionada anteriormente en este artículo. Tenga en cuenta que la nueva CLI no es un sustituto directo de la CLI heredada y que se requiere cierta configuración para pasar de la CLI heredada a la nueva.

¿Puede haber instalaciones de la CLI heredada y de la nueva en la misma máquina?

Sí. Puede haber instalaciones de la CLI heredada y de la nueva en la misma máquina, pero deberán encontrarse en directorios diferentes. Dado que los dos archivos ejecutables se denominan databricks, deberá configurar la variable PATH de la máquina para controlar cuál de ellos se ejecuta de forma predeterminada. Si quiere ejecutar la nueva CLI, pero de algún modo se ejecuta accidentalmente la CLI heredada, la CLI heredada ejecutará de forma predeterminada la nueva CLI con los mismos argumentos y mostrará el siguiente mensaje de advertencia:

Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>

Because both are installed and available in PATH,
I assume you are trying to run the newer version.

If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.

Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>

Como se muestra en el mensaje de advertencia anterior, puede establecer la variable de entorno DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION en 1 para deshabilitar este comportamiento y ejecutar la CLI heredada.

Obtener ayuda

Para obtener ayuda con la migración de la CLI heredada a la nueva CLI, consulte los siguientes recursos: