Grupo de comandos de bundle

Nota:

Esta información se aplica a las versiones 0.218.0 y posteriores de la CLI de Databricks. Para encontrar su versión de la CLI de Databricks, ejecute databricks -v.

El grupo de comandos bundle de la CLI de Databricks permite validar, implementar y ejecutar flujos de trabajo de Azure Databricks mediante programación, como trabajos de Azure Databricks, canalizaciones de Delta Live Tables y pilas de MLOps. Consulte ¿Qué son las agrupaciones de recursos de Databricks?

Importante

Para instalar la CLI de Databricks, consulte Instalación o actualización de la CLI de Databricks. Para configurar la autenticación de la CLI de Databricks, consulte Autenticación de la CLI de Databricks.

Ejecute los comandos bundle anexándolos a databricks bundle. Para mostrar la ayuda para el comando bundle, ejecute databricks bundle -h.

Crear una agrupación a partir de una plantilla de proyecto

Para crear una agrupación de recursos de Databricks mediante la plantilla predeterminada de agrupación de recursos de Databricks para Python, ejecute el comando bundle init de la siguiente manera y, a continuación, responda a los mensajes en pantalla:

databricks bundle init

Para crear una agrupación de recursos de Databricks mediante una plantilla de agrupación de recursos de Databricks no predeterminada, ejecute el comando bundle init de la siguiente manera:

databricks bundle init <project-template-local-path-or-url> \
--project-dir="</local/path/to/project/template/output>"

Consulte también:

• Plantillas de proyecto de agrupación de recursos de Databricks
• Desarrollo de un trabajo en Azure Databricks mediante conjuntos de recursos de Databricks
• Desarrollo de canalizaciones de Delta Live Tables mediante conjuntos de recursos de Databricks
• Conjuntos de recursos de Databricks para pilas MLOps

Mostrar el esquema de configuración de agrupación

Para mostrar el esquema de configuración de la agrupación de recursos de Databricks, ejecute el comando bundle schema de la siguiente manera:

databricks bundle schema

Para generar el esquema de configuración de Asset Bundle de Databricks como un archivo JSON, ejecute el comando bundle schema y redirija la salida a un archivo JSON. Por ejemplo, puede generar un archivo denominado bundle_config_schema.json dentro del directorio actual, como se indica a continuación:

databricks bundle schema > bundle_config_schema.json

Validar un lote

Para validar que los archivos de configuración de agrupación son sintácticamente correctos, ejecute el comando bundle validate desde la raíz del proyecto de agrupación, como se indica a continuación:

databricks bundle validate

De forma predeterminada, este comando devuelve un resumen de la identidad del lote:

Name: MyBundle
Target: dev
Workspace:
  Host: https://my-host.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/MyBundle/dev

Validation OK!

Nota:

El comando bundle validate genera advertencias si las propiedades de recursos se definen en los archivos de configuración de agrupación que no se encuentran en el esquema del objeto correspondiente.

Sincronizar un árbol de una agrupación en un área de trabajo

Use el comando bundle sync para realizar la sincronización unidireccional de los cambios de archivo de una agrupación en un directorio del sistema de archivos local en un directorio dentro de un área de trabajo remota de Azure Databricks.

Nota:

Los comandos bundle sync no pueden sincronizar los cambios de archivo desde un directorio dentro de un área de trabajo remota de Azure Databricks, dentro de un directorio dentro de un sistema de archivos local.

Los comandos databricks bundle sync funcionan de la misma manera que los comandos databricks sync y se proporcionan como una conveniencia de productividad. Para obtener información sobre el uso de comandos, consulte Grupo de comandos de sincronización.

Generar un archivo de configuración de agrupación

Puede usar el comando bundle generate para generar la configuración de recursos de un trabajo o canalización que ya existe en el área de trabajo de Databricks. Este comando genera un archivo *.yml para el trabajo o la canalización en la carpeta resources del proyecto de agrupación y también descarga los cuadernos a los que se hace referencia en la configuración del trabajo o la canalización. Actualmente, este comando solo admite trabajos con tareas de cuaderno.

Importante

El comando bundle generate se proporciona como una comodidad para generar automáticamente la configuración de recursos. Sin embargo, cuando esta configuración se incluye en la agrupación y se implementa, crea un nuevo recurso y no actualiza el recurso existente a menos que se haya usado primero bundle deployment bind en el recurso.

Ejecute el comando bundle generate de la siguiente manera:

databricks bundle generate [job|pipeline] --existing-[job|pipeline]-id [job-id|pipeline-id]

Por ejemplo, el siguiente comando genera un nuevo archivo de hello_job.yml en la carpeta del proyecto de agrupación de resources que contiene el código YAML siguiente y descarga el simple_notebook.py en la carpeta del proyecto de src.

databricks bundle generate job --existing-job-id 6565621249

# This is the contents of the resulting hello_job.yml file.
resources:
  jobs:
    6565621249:
      name: Hello Job
      format: MULTI_TASK
      tasks:
        - task_key: run_notebook
          existing_cluster_id: 0704-xxxxxx-yyyyyyy
          notebook_task:
            notebook_path: ./src/simple_notebook.py
            source: WORKSPACE
          run_if: ALL_SUCCESS
      max_concurrent_runs: 1

Enlazar recursos de agrupación

El comando bundle deployment bind permite vincular trabajos y canalizaciones definidos por la agrupación a trabajos y canalizaciones existentes en el área de trabajo de Azure Databricks para que se administren con los conjuntos de recursos de Databricks. Si enlaza un recurso, los recursos de Azure Databricks existentes en el área de trabajo se actualizan en función de la configuración definida en la agrupación a la que se enlaza después del siguiente bundle deploy.

Sugerencia

Es recomendable confirmar el área de trabajo de agrupación antes de ejecutar el enlace.

databricks bundle deployment bind [resource-key] [resource-id]

Por ejemplo, el comando siguiente enlaza el recurso hello_job a su homólogo remoto en el área de trabajo. El comando genera una diferencia y permite denegar el enlace de recursos, pero si se confirma, las actualizaciones de la definición de trabajo de la agrupación se aplican al trabajo remoto correspondiente cuando se implementa la agrupación a continuación.

databricks bundle deployment bind hello_job 6565621249

Use bundle deployment unbind si quiere eliminar el vínculo entre el trabajo o canalización en un paquete y su homólogo remoto en un área de trabajo.

databricks bundle deployment unbind [resource-key]

Implementación de una agrupación

Para implementar una agrupación en el área de trabajo remota, ejecute el comando bundle deploy desde la raíz del proyecto de agrupación. Si no se especifica ninguna opción de comando, se usa el destino predeterminado declarado dentro de los archivos de configuración de agrupación.

databricks bundle deploy

Para implementar la agrupación en un destino específico, establezca la opción -t (o --target) junto con el nombre del destino tal como se declara en los archivos de configuración del lote. Por ejemplo, para un destino declarado con el nombre dev:

databricks bundle deploy -t dev

Una agrupación se puede implementar en varias áreas de trabajo, como el desarrollo, el almacenamiento provisional y las áreas de trabajo de producción. Fundamentalmente, la propiedad root_path es lo que determina una identidad única del lote, que tiene como valor predeterminado ~/.bundle/${bundle.name}/${bundle.target}. Por lo tanto, de forma predeterminada, una identidad de agrupación consta de la identidad del implementador, el nombre del lote y el nombre de destino del lote. Si estos son idénticos en diferentes agrupaciones, la implementación de estos conjuntos interferirá entre sí.

Además, una implementación de agrupación realiza un seguimiento de los recursos que crea en el área de trabajo de destino por sus identificadores como un estado que se almacena en el sistema de archivos del área de trabajo. Los nombres de recursos no se usan para correlacionar entre una implementación de agrupación y una instancia de recurso, por lo que:

• Si un recurso de la configuración de agrupación no existe en el área de trabajo de destino, se crea.
• Si existe un recurso en la configuración de agrupación en el área de trabajo de destino, se actualiza en el área de trabajo.
• Si se quita un recurso de la configuración de agrupación, se quita del área de trabajo de destino si se ha implementado previamente.
• Solo se puede olvidar la asociación de un recurso con una agrupación si cambia el nombre del lote, el destino del lote o el área de trabajo. Puede ejecutar bundle validate para generar un resumen que contenga estos valores.

Ejecutar un lote

Para ejecutar un trabajo o una canalización específicos, ejecute el comando bundle run. Debe especificar la clave de recurso del trabajo o la canalización declaradas en los archivos de configuración de agrupación. De forma predeterminada, se usa el entorno declarado en los archivos de configuración de agrupación. Por ejemplo, para ejecutar un trabajo hello_job en el entorno predeterminado, ejecute el siguiente comando:

databricks bundle run hello_job

Para ejecutar un trabajo con una clave hello_job dentro del contexto de un destino declarado con el nombre dev:

databricks bundle run -t dev hello_job

Si desea realizar una ejecución de validación de canalización, use la opción --validate-only, como se muestra en el ejemplo siguiente:

databricks bundle run --validate-only my_pipeline

Para pasar parámetros de trabajo, use la opción --params, seguida de pares clave-valor separados por comas, donde la clave es el nombre del parámetro. Por ejemplo, el comando siguiente establece el parámetro con el nombre message en HelloWorld para el trabajo hello_job:

databricks bundle run --params message=HelloWorld hello_job

Nota:

Puede pasar parámetros a tareas de trabajo mediante las opciones de tarea de trabajo, pero la opción --params es el método recomendado para pasar parámetros de trabajo. Se produce un error si se especifican parámetros de trabajo para un trabajo que no tiene parámetros de trabajo definidos o si se especifican parámetros de tarea para un trabajo que tiene parámetros de trabajo definidos.

Para cancelar y reiniciar una ejecución de trabajo existente o una actualización de canalización, use la opción --restart:

databricks bundle run --restart hello_job

Destruir un lote

Para eliminar trabajos, canalizaciones y artefactos que se implementaron anteriormente, ejecute el comando bundle destroy. El siguiente comando elimina todos los trabajos, canalizaciones y artefactos implementados anteriormente que se definen en los archivos de configuración de agrupación:

databricks bundle destroy

Nota:

Una identidad de agrupación consta del nombre del lote, el destino del lote y el área de trabajo. Si ha cambiado cualquiera de estos y, a continuación, intenta destruir un lote antes de la implementación, se producirá un error.

De forma predeterminada, se le pedirá que confirme la eliminación permanente de los trabajos, canalizaciones y artefactos implementados anteriormente. Para omitir estas solicitudes y realizar una eliminación permanente automática, agregue la opción --auto-approve al comando bundle destroy.