Desarrollo de un trabajo en Azure Databricks mediante conjuntos de recursos de Databricks

Artículo
10/14/2024

Los conjuntos de recursos de Databricks, también conocidos simplemente como agrupaciones, contienen los artefactos que desea implementar y la configuración de recursos de Azure Databricks, como trabajos que desea ejecutar, y le permiten validarlos, implementarlos y ejecutarlos mediante programación. Consulte ¿Qué son las agrupaciones de recursos de Databricks?

En este artículo se describe cómo crear una agrupación para administrar un trabajo mediante programación. Consulte Programación y orquestación de flujos de trabajo. La agrupación se crea mediante la plantilla de agrupación predeterminada de recursos de Databricks para Python, que consta de un cuaderno emparejado con la definición de un trabajo para ejecutarlo. A continuación, valide, implemente y ejecute el trabajo implementado en el área de trabajo de Azure Databricks.

Sugerencia

Si tiene trabajos existentes creados mediante la interfaz de usuario o la API de trabajos de Azure Databricks que desea mover a agrupaciones, debe volver a crearlos como archivos de configuración de agrupación. Databricks recomienda crear primero una agrupación mediante los pasos siguientes y a continuación validar si la agrupación funciona. A continuación, puede agregar definiciones de trabajo, cuadernos y otros orígenes adicionales a la agrupación. Consulte Agregar una definición de trabajo existente a una agrupación.

Requisitos

CLI de Databricks, versión 0.218.0 o posterior. Para comprobar la versión de la CLI de Databricks instalada, ejecute el comando databricks -v. Para instalar la CLI de Databricks, consulte Instalación o actualización de la CLI de Databricks.
El área de trabajo remota de Databricks debe tener habilitados los archivos del área de trabajo. Consulte ¿Qué son los archivos del área de trabajo?

Crear una agrupación mediante una plantilla de proyecto

En primer lugar, cree una agrupación mediante la plantilla predeterminada de Python de conjuntos de recursos de Databricks. Para obtener más información sobre las plantillas de agrupaciones, consulte Plantillas de proyecto de agrupación de recursos de Databricks.

Si desea crear una agrupación desde cero, consulte Creación de una agrupación manualmente.

Paso 1 Configuración de la autenticación

En este paso, configurará la autenticación entre la CLI de Databricks en la máquina de desarrollo y el área de trabajo de Azure Databricks. En este artículo se asume que quiere usar la autenticación de usuario a máquina (U2M) de OAuth y un perfil de configuración de Azure Databricks correspondiente denominado DEFAULT para la autenticación.

Nota:

La autenticación U2M es adecuada para probar estos pasos en tiempo real. Para flujos de trabajo totalmente automatizados, Databricks recomienda usar la autenticación de máquina a máquina (M2M) de OAuth en su lugar. Consulte las instrucciones de configuración de autenticación de M2M en Autenticación.

Use el CLI de Databricks para iniciar la administración de tokens de OAuth localmente mediante la ejecución del siguiente comando para cada área de trabajo de destino.

En el comando siguiente, reemplace <workspace-url> por la dirección URL de Azure Databricks por área de trabajo, por ejemplo, https://adb-1234567890123456.7.azuredatabricks.net.
```
databricks auth login --host <workspace-url>
```
La CLI de Databricks le pide que guarde la información que especificó como un perfil de configuración de Azure Databricks. Presione Enter para aceptar el nombre del perfil sugerido o escriba el nombre de un perfil nuevo o existente. Cualquier perfil existente con el mismo nombre se sobrescribe con la información que especificó. Puede usar perfiles para cambiar rápidamente el contexto de autenticación entre varias áreas de trabajo.

Para obtener una lista de los perfiles existentes, en un terminal o símbolo del sistema independiente, use la CLI de Databricks para ejecutar el comando databricks auth profiles. Para ver la configuración existente de un perfil específico, ejecute el comando databricks auth env --profile <profile-name>.
En el explorador web, complete las instrucciones en pantalla para iniciar sesión en el área de trabajo de Azure Databricks.
Para ver el valor actual del token de OAuth de un perfil y la próxima marca de tiempo de expiración del token’, ejecute uno de los siguientes comandos:
- databricks auth token --host <workspace-url>
- databricks auth token -p <profile-name>
- databricks auth token --host <workspace-url> -p <profile-name>
Si tiene varios perfiles con el mismo valor de --host, es posible que tenga que especificar las opciones --host y -p para ayudar a la CLI de Databricks a encontrar la información correcta del token de OAuth coincidente.

Paso 2: Inicializar la agrupación

Inicialice una agrupación mediante la plantilla de proyecto de agrupación de Python predeterminada.

Use el terminal o el símbolo del sistema para cambiar a un directorio de la máquina de desarrollo local que contendrá la agrupación generada de la plantilla.
Use la CLI de Databricks para ejecutar el comando bundle init:
```
databricks bundle init
```
En Template to use, deje el valor predeterminado de default-python presionando Enter.
En Unique name for this project, deje el valor predeterminado de my_project o escriba un valor diferente y, a continuación, presione Enter. Con ello se determina el nombre del directorio raíz de esta agrupación. Este directorio raíz se crea en el directorio de trabajo actual.
Para Include a stub (sample) notebook, seleccione yes y presione Enter.
Para Include a stub (sample) DLT pipeline, seleccione no y presione Enter. Con ello se indica a la CLI de Databricks que no defina una canalización de Delta Live Tables de ejemplo en la agrupación.
Para Include a stub (sample) Python package, seleccione no y presione Enter. Con ello se indica a la CLI de Databricks que no agregue archivos de paquete wheel de Python de ejemplo ni instrucciones de compilación relacionadas a la agrupación.

Paso 3: exploración de la agrupación

Para ver los archivos que generó la plantilla, cambie al directorio raíz de la agrupación recién creada. Entre los tipos de especial interés se incluyen los siguientes:

databricks.yml: este archivo especifica el nombre de programación de la agrupación, incluye una referencia a la definición de trabajo y especifica la configuración sobre el área de trabajo de destino.
resources/<project-name>_job.yml: este archivo especifica la configuración del trabajo, incluida una tarea de cuaderno predeterminada.
src/notebook.ipynb: este archivo es un cuaderno de ejemplo que, cuando se ejecuta, simplemente inicializa una RDD que contiene los números del 1 al 10.

Para personalizar los trabajos, las asignaciones dentro de una declaración de trabajo corresponden a la carga de solicitud, expresada en formato YAML, de la operación de creación del trabajo, tal y como se documenta en POST /api/2.1/jobs/create en la referencia de API REST.

Sugerencia

Puede definir, combinar e invalidar la configuración de los nuevos clústeres de trabajos en agrupaciones mediante las técnicas descritas en Invalidación de la configuración del clúster en agrupaciones de recursos de Databricks.

Paso 4: Validación del archivo de configuración de la agrupación del proyecto

En este paso, comprobará si la configuración de la agrupación es válida.

En el directorio raíz, use la CLI de Databricks para ejecutar el comando bundle validate de la siguiente manera:
```
databricks bundle validate
```
Si se devuelve un resumen de la configuración de la agrupación, indica que la validación se ha realizado correctamente. Si se devuelven errores, corrija los errores y repita este paso.

Si realiza algún cambio en la agrupación después de este paso, debe repetir el paso para comprobar si la configuración de la agrupación sigue siendo válida.

Paso 5: Implementación del proyecto local en el área de trabajo remota

En este paso, implementará el cuaderno local en el área de trabajo remota de Azure Databricks y creará el trabajo de Azure Databricks en el área de trabajo.

En la raíz de la agrupación, use la CLI de Databricks para ejecutar el comando bundle deploy de la siguiente manera:
```
databricks bundle deploy -t dev
```
Compruebe si se implementó el cuaderno local: en la barra lateral del área de trabajo de Azure Databricks, haga clic en Área de trabajo.
Haga clic en la carpeta Usuarios ><your-username>> .bundle ><project-name>> dev > archivos > src. El cuaderno debería estar en esta carpeta.
Compruebe si se creó el trabajo: en la barra lateral del área de trabajo de Azure Databricks, haga clic en Flujos de trabajo.
En la pestaña Trabajos, haga clic en [dev <your-username>] <project-name>_job.
Haga clic en la pestaña Tareas. Debe haber una tarea: notebook_task.

Si realiza algún cambio en la agrupación después de este paso, debe repetir los pasos 4 y 5 para comprobar si la configuración de la agrupación sigue siendo válida y volver a implementar el proyecto.

Paso 6: ejecución del proyecto implementado

En este paso, desencadenará una ejecución del trabajo de Azure Databricks en el área de trabajo desde la línea de comandos.

En el directorio raíz, use la CLI de Databricks para ejecutar el comando bundle run, tal y como se indica a continuación, reemplazando <project-name> por el nombre del proyecto del paso 2:
```
databricks bundle run -t dev <project-name>_job
```
Copie el valor de Run URL que aparece en el terminal y pegue este valor en el explorador web para abrir el área de trabajo de Azure Databricks. Consulte Visualización y ejecución de un trabajo creado con un conjunto de recursos de Databricks.
En el área de trabajo de Azure Databricks, una vez que se complete correctamente la tarea de trabajo y aparezca una barra de título verde, haga clic en la tarea de trabajo para ver los resultados.

Si realiza algún cambio en la agrupación después de este paso, debe repetir los pasos del 4 al 6 para comprobar si la configuración de la agrupación sigue siendo válida, volver a implementar el proyecto y ejecutarlo.

Paso 7: Limpieza

En este paso, eliminará el cuaderno implementado y el trabajo del área de trabajo.

En el directorio raíz, use la CLI de Databricks para ejecutar el comandobundle destroy de la siguiente manera:
```
databricks bundle destroy -t dev
```
Confirme la solicitud de eliminación del trabajo: cuando se le pida que destruya permanentemente los recursos, escriba y y presione Enter.
Confirme la solicitud de eliminación del cuaderno: cuando se le pida que destruya permanentemente la carpeta implementada previamente y todos sus archivos, escriba y y presione Enter.
Si también se desea eliminar la agrupación de la máquina de desarrollo, ahora se puede eliminar el directorio local del paso 2.

Agregar una definición de trabajo existente a una agrupación

Puede usar un trabajo existente como base para definir un trabajo en un archivo de configuración de agrupación. Para obtener una definición de trabajo existente, puede recuperarla manualmente mediante la interfaz de usuario o puede generarla mediante programación mediante la CLI de Databricks.

Para obtener información sobre la definición del trabajo en agrupaciones, consulte trabajo.

Obtención de una definición de trabajo existente mediante la interfaz de usuario

Para obtener la representación YAML de una definición de trabajo existente a partir de la interfaz de usuario del área de trabajo de Azure Databricks:

En la barra lateral del área de trabajo de Azure Databricks, haga clic en Flujos de trabajo.
En la pestaña Trabajos, haga clic en el vínculo Nombre del trabajo.
Junto al botón Ejecutar ahora, haga clic en el kebab y, a continuación, haga clic en Cambiar al código (YAML).
Agregue el YAML que copió al archivo de la agrupación databricks.yml o cree un archivo de configuración para el trabajo en el directorio resources del proyecto de agrupación y haga referencia a él desde el archivo databricks.yml. Consulte (/dev-tools/bundles/settings.md#resources).
Descargue y agregue los archivos y cuadernos de Python a los que se hace referencia en el trabajo existente en el origen del proyecto de agrupación. Normalmente, los artefactos de agrupación están en el directorio src de una agrupación.

Sugerencia

Puede exportar un cuaderno existente desde un área de trabajo de Azure Databricks al formato .ipynb haciendo clic en Archivo > Exportar > Cuaderno de IPython desde la interfaz de usuario del cuaderno de Azure Databricks.

Después de agregar los cuadernos, los archivos de Python y otros artefactos a la agrupación, asegúrese de que la definición del trabajo hace referencia a ellos correctamente. Por ejemplo, para un cuaderno denominado hello.ipynb que se encuentra en el directorio src de la agrupación:
```
resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
      - task_key: hello-task
        notebook_task:
          notebook_path: ../src/hello.ipynb
```

Generación de una definición de trabajo existente mediante la CLI de Databricks

Para generar mediante programación la configuración de agrupación para un trabajo existente:

Recupere el identificador del trabajo existente en el panel lateral Detalles del trabajo del trabajo en la interfaz de usuario de trabajos o use el comando de la CLI databricks jobs list de Databricks.
Ejecute el comando de la CLI de Databricks bundle generate job y establezca el identificador de trabajo:
```
databricks bundle generate job --existing-job-id 6565621249
```
Este comando crea un archivo de configuración de agrupación para el trabajo en la carpeta de la agrupación resources y descarga los artefactos a los que se hace referencia en la carpeta src.

Sugerencia

Si usa primero bundle deployment bind para enlazar un recurso en una agrupación a uno en el área de trabajo, el recurso del área de trabajo se actualiza en función de la configuración definida en la agrupación a la que se enlaza después del siguiente bundle deploy. Para obtener información sobre bundle deployment bind, vea Enlazar recursos de agrupación.

Configuración de un trabajo que usa un proceso sin servidor

En los ejemplos siguientes se muestran las configuraciones de agrupación para crear un trabajo que usa el proceso sin servidor.

Para usar el proceso sin servidor para ejecutar un trabajo que incluya tareas de cuaderno, omita la configuración job_clusters del archivo de configuración de agrupación.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job-serverless:
      name: retrieve-filter-baby-names-job-serverless
      tasks:
        - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./filter-baby-names.py

  targets:
    development:
      workspace:
        host: <workspace-url>

Para usar el proceso sin servidor para ejecutar un trabajo que incluya tareas de Python, incluya la configuración environments.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: serverless-python-tasks

resources:
jobs:
  serverless-python-job:
    name: serverless-job-with-python-tasks

    tasks:
      - task_key: wheel-task-1
        python_wheel_task:
          entry_point: main
          package_name: wheel_package
        environment_key: Default

    environments:
      - environment_key: Default
        spec:
          client: "1"
          dependencies:
            - workflows_authoring_toolkit==0.0.1

targets:
  development:
    workspace:
      host: <workspace-url>

Consulte Ejecución del trabajo de Azure Databricks con un proceso sin servidor para flujos de trabajo.

Compartir vía