Grupo de comandos de bundle

Nota:

Esta información se aplica a las versiones 0.205 y posteriores de la CLI de Databricks. La CLI de Databricks está en versión preliminar pública.

El uso de la CLI de Databricks está sujeto a la licencia de Databricks y al aviso de privacidad de Databricks, incluidas las disposiciones de datos de uso.

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?

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 un conjunto de recursos de Databricks mediante la plantilla predeterminada de Conjunto de recursos de Databricks para Python, ejecute el bundle init comando como se indica a continuación y, a continuación, responda a las indicaciones en pantalla:

databricks bundle init

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

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 agrupación, ejecute el comando de la bundle schema 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.

Si solo desea generar un resumen de la identidad y los recursos del lote, use el resumen de agrupación.

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 bundle generate comando para generar la configuración de recursos de un trabajo, una canalización o un panel que ya existe en el área de trabajo de Databricks. Este comando genera un *.yml archivo para el trabajo, la canalización o el panel en la resources carpeta del proyecto de agrupación y también descarga los archivos, como cuadernos, a los que se hace referencia en la configuración.

Generación de una configuración de trabajo o canalización

Importante

El comando bundle generate se proporciona como una comodidad para generar automáticamente la configuración de recursos. Sin embargo, cuando este trabajo o configuración de canalización se incluye en la agrupación e implementa, crea un nuevo recurso y no actualiza el recurso existente a menos bundle deployment bind que se haya usado por primera vez. Consulte Enlazar recursos de agrupación.

Para generar la configuración de un trabajo o canalización, ejecute el comando de la bundle generate siguiente manera:

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

Nota:

Actualmente, este comando solo admite trabajos con tareas de cuaderno.

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

Generación de la configuración del panel

Para generar la configuración de un panel existente en el área de trabajo, ejecute bundle generatey especifique el identificador o la ruta de acceso del área de trabajo para el panel:

databricks bundle generate dashboard --existing-id [dashboard-id]

databricks bundle generate dashboard --existing-path [dashboard-workspace-path]

Puede copiar la ruta de acceso del área de trabajo de un panel desde la interfaz de usuario del área de trabajo.

Por ejemplo, el siguiente comando genera un nuevo baby_gender_by_county.dashboard.yml archivo en la carpeta del resources proyecto de agrupación que contiene el archivo YAML siguiente y descarga el baby_gender_by_county.lvdash.json archivo en la carpeta del src proyecto.

databricks bundle generate dashboard --existing-path "/Workspace/Users/someone@example.com/baby_gender_by_county.lvdash.json"

# This is the contents of the resulting baby_gender_by_county.dashboard.yml file.
resources:
  dashboards:
    baby_gender_by_county:
      display_name: "Baby gender by county"
      warehouse_id: aae11o8e6fe9zz79
      file_path: ../src/baby_gender_by_county.lvdash.json

Sugerencia

Para actualizar el .lvdash.json archivo después de que ya haya implementado un panel, use la --resource opción al ejecutar bundle generate dashboard para generar ese archivo para el recurso de panel existente. Para sondear y recuperar continuamente las actualizaciones de un panel, use las --force opciones y --watch .

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]

Salida de un resumen de agrupación

El bundle summary comando genera un resumen de la identidad y los recursos de un lote, incluidos los vínculos profundos de los recursos para que pueda navegar fácilmente al recurso en el área de trabajo de Databricks.

databricks bundle summary

La salida del ejemplo siguiente es el resumen de un paquete denominado my_pipeline_bundle que define un trabajo y una canalización:

Name: my_pipeline_bundle
Target: dev
Workspace:
  Host: https://myworkspace.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/my_pipeline/dev
Resources:
  Jobs:
    my_project_job:
      Name: [dev someone] my_project_job
      URL:  https://myworkspace.cloud.databricks.com/jobs/206000809187888?o=6051000018419999
  Pipelines:
    my_project_pipeline:
      Name: [dev someone] my_project_pipeline
      URL:  https://myworkspace.cloud.databricks.com/pipelines/7f559fd5-zztz-47fa-aa5c-c6bf034b4f58?o=6051000018419999

Sugerencia

También puede usar bundle open para navegar a un recurso en el área de trabajo de Databricks. Consulte Abrir un recurso de agrupación.

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.

Ejecución de un trabajo o una canalización

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

Apertura de un recurso de agrupación

Para ir a un recurso de agrupación en el área de trabajo, ejecute el bundle open comando desde la raíz del proyecto de agrupación y especifique el recurso que se va a abrir. Si no se especifica una clave de recurso, este comando genera una lista de los recursos de la agrupación desde los que elegir.

databricks bundle open [resource-key]

Por ejemplo, el siguiente comando inicia un explorador y navega al panel de baby_gender_by_county del lote en el área de trabajo de Databricks que está configurada para la agrupación:

databricks bundle open baby_gender_by_county

Destruir un lote

Advertencia

Al destruir una agrupación, se eliminan permanentemente los trabajos, canalizaciones y artefactos implementados previamente de un lote. Esta operación no se puede deshacer.

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.