Configuration de bundle en Python

Le support Python pour les Declarative Automation Bundles étend les Declarative Automation Bundles avec des capacités supplémentaires qui s'appliquent lors du déploiement de bundles afin que vous puissiez :

• Définissez les ressources dans le code Python. Ces définitions peuvent coexister avec des ressources définies en YAML.

• Créez dynamiquement des ressources lors du déploiement du bundle à l’aide de métadonnées. Voir Créer des ressources à l'aide de métadonnées.

• Modifier les ressources définies en YAML ou Python pendant le déploiement du bundle. Consultez Modifier les ressources définies en YAML ou Python.

astuce

Vous pouvez également modifier les ressources de bundle au moment de l'exécution à l'aide de fonctionnalités telles que if/else condition_task ou for_each_task pour les Jobs.

La documentation de référence pour la prise en charge de Python pour les Bundles d'automatisation déclaratifs package databricks-bundles est disponible à l'adresse https://databricks.github.io/cli/python/.

Exigences

Pour utiliser le support Python pour les Declarative Automation Bundles, vous devez d'abord :

1. Installez la Databricks CLI, version 0.275.0 ou supérieure. Consultez Installer ou mettre à jour la Databricks CLI.

2. Authentifiez-vous à votre Workspace Databricks si vous ne l'avez pas déjà fait :

   Bash

   databricks configure

3. Installer uv. Consultez Installation de uv. Python pour les Declarative Automation Bundles utilise uv pour créer un environnement virtuel et installer les dépendances requises. Vous pouvez également configurer votre environnement Python à l'aide d'autres outils tels que venv.

Créer un Template à partir du Template

Pour créer un nouveau projet Python support pour Declarative Automation Bundles, initialisez un bundle en utilisant le pydabs Template :

Bash

databricks bundle init pydabs

Lorsque vous y êtes invité, donnez un nom à votre projet, tel que my_pydabs_project, et acceptez l'inclusion d'un Notebook et d'un package Python.

Créez maintenant un nouvel environnement virtuel dans votre nouveau dossier de projet :

Bash

cd my_pydabs_project
uv sync

Par défaut, le Template inclut un exemple de Job défini comme Python dans le fichier resources/my_pydabs_project_job.py :

Python

from databricks.bundles.jobs import Job


my_pydabs_project_job = Job.from_dict(
    {
        "name": "my_pydabs_project_job",
        "tasks": [
            {
                "task_key": "notebook_task",
                "notebook_task": {
                    "notebook_path": "src/notebook.ipynb",
                },
            },
        ],
    },
)

La fonction Job.from_dict accepte un dictionnaire Python utilisant le même format que YAML. Les Ressources peuvent également être construites en utilisant la syntaxe dataclass :

Python

from databricks.bundles.jobs import Job, Task, NotebookTask


my_pydabs_project_job = Job(
    name="my_pydabs_project_job",
    tasks=[
        Task(
            task_key="notebook_task",
            notebook_task=NotebookTask(
                notebook_path="src/notebook.ipynb",
            ),
        ),
    ],
)

Les fichiers Python sont chargés via un point d'entrée spécifié dans la section python de databricks.yml:

YAML

python:
  # Activate the virtual environment before loading resources defined in
  # Python. If disabled, it defaults to using the Python interpreter
  # available in the current shell.
  venv_path: .venv
  # Functions called to load resources defined in Python.
  # See resources/__init__.py
  resources:
    - 'resources:load_resources'

Par default, resources/__init__.py contient une fonction qui charge tous les fichiers Python du package de ressources.

Python

from databricks.bundles.core import (
    Bundle,
    Resources,
    load_resources_from_current_package_module,
)


def load_resources(bundle: Bundle) -> Resources:
    """
    'load_resources' function is referenced in databricks.yml and is responsible for loading
    bundle resources defined in Python code. This function is called by Databricks CLI during
    bundle deployment. After deployment, this function is not used.
    """

    # the default implementation loads all Python files in 'resources' directory
    return load_resources_from_current_package_module()

Déployer et exécuter des jobs ou des pipelines

Pour déployer le bundle vers la cible de développement, utilisez la commande de déploiement de bundle depuis la racine du projet de bundle :

Bash

databricks bundle deploy --target dev

Cette commande déploie tout ce qui est défini pour le projet de bundle. Par exemple, un projet créé à l’aide du template « default » déploie un job appelé [dev yourname] my_pydabs_project_job dans votre workspace. Vous pouvez trouver ce job en accédant à Jobs & Pipelines dans votre workspace Databricks.

Une fois le bundle déployé, vous pouvez utiliser la commande de résumé du bundle pour examiner tout ce qui est déployé :

Bash

databricks bundle summary --target dev

Enfin, pour exécuter un Job ou un pipeline, utilisez la commande d'exécution de bundle:

Bash

databricks bundle run my_pydabs_project_job

Mettre à jour les bundles existants

Pour mettre à jour les bundles existants, modélisez la structure du template de projet comme décrit dans Créer un projet à partir d'un template. Les bundles existants avec YAML peuvent être mis à jour pour inclure des ressources définies en tant que code Python en ajoutant une section python dans databricks.yml:

YAML

python:
  # Activate the virtual environment before loading resources defined in
  # Python. If disabled, it defaults to using the Python interpreter
  # available in the current shell.
  venv_path: .venv
  # Functions called to load resources defined in Python.
  # See resources/__init__.py
  resources:
    - 'resources:load_resources'

L'environnement virtuel spécifié doit contenir le package PyPi databricks-bundles installé.

Bash

pip install databricks-bundles==0.275.0

Le dossier Ressources doit contenir le fichier __init__.py :

Python

from databricks.bundles.core import (
    Bundle,
    Resources,
    load_resources_from_current_package_module,
)


def load_resources(bundle: Bundle) -> Resources:
    """
    'load_resources' function is referenced in databricks.yml and
    is responsible for loading bundle resources defined in Python code.
    This function is called by Databricks CLI during bundle deployment.
    After deployment, this function is not used.
    """

    # default implementation loads all Python files in 'resources' folder
    return load_resources_from_current_package_module()

Convertir les Jobs existants en Python

Pour convertir les jobs existants en Python, vous pouvez utiliser la fonctionnalité Afficher comme code . Voir Afficher les jobs sous forme de code.

1. Ouvrez la page du Job existant dans le Workspace Databricks.

2. Cliquez sur le kebab à gauche du bouton Exécuter maintenant , puis cliquez sur Afficher en tant que code :

   

3. Sélectionnez Python , puis Declarative Automation Bundles

   

4. Cliquez sur Copier et enregistrez le Python généré en tant que fichier Python dans le dossier Ressources du projet de bundle.

astuce

Vous pouvez également afficher et copier le YAML des jobs et pipelines existants que vous pouvez coller directement dans vos fichiers YAML de configuration de bundle.

Créer des ressources à l'aide de métadonnées

L'implémentation par default de la fonction load_resources charge les fichiers Python dans le package resources. Vous pouvez utiliser Python pour créer des ressources par programme. Par exemple, vous pouvez charger des fichiers de configuration et créer des jobs en boucle :

Python

from databricks.bundles.core import (
    Bundle,
    Resources,
    load_resources_from_current_package_module,
)


from databricks.bundles.jobs import Job


def create_job(country: str):
    my_notebook = {
        "task_key": "my_notebook",
        "notebook_task": {
            "notebook_path": "files/my_notebook.py",
        },
    }


    return Job.from_dict(
        {
            "name": f"my_job_{country}",
            "tasks": [my_notebook],
        }
    )


def load_resources(bundle: Bundle) -> Resources:
    resources = load_resources_from_current_package_module()


    for country in ["US", "NL"]:
        resources.add_resource(f"my_job_{country}", create_job(country))


    return resources

Accéder aux variables du bundle

Les substitutions de bundles et les variables personnalisées permettent la récupération dynamique des valeurs afin que les paramètres puissent être déterminés au moment où un bundle est déployé et exécuté sur une cible. Pour obtenir des informations sur les variables de bundle, consultez Variables personnalisées.

En Python, définissez des variables, puis utilisez le parameter bundle pour y accéder. Voir décorateur@variables, Variable, Bundle et Ressources.

Python

from databricks.bundles.core import Bundle, Resources, Variable, variables

@variables
class Variables:
    # Define a variable
    warehouse_id: Variable[str]


def load_resources(bundle: Bundle) -> Resources:
    # Resolve the variable
    warehouse_id = bundle.resolve_variable(Variables.warehouse_id)

    ...

Les variables sont également accessibles en Python à l'aide de substitutions.

Python

sample_job = Job.from_dict(
    {
        "name": "sample_job",
        "tasks": [
            {
                "task_key": "my_sql_query_task",
                "sql_task": {
                    "warehouse_id": "${var.warehouse_id}",
                    "query": {
                        "query_id": "11111111-1111-1111-1111-111111111111",
                    },
    ...

Utilisez les substitutions de cibles pour définir les valeurs des variables pour différentes cibles de déploiement.

Modifier les ressources définies en YAML ou Python

Pour modifier les ressources, vous pouvez référencer des fonctions mutateur dans databricks.yml, similaire aux fonctions de chargement de ressources. Cette fonctionnalité peut être utilisée indépendamment du chargement des ressources définies en Python et modifie les ressources définies à la fois en YAML et en Python.

Tout d'abord, créez mutators.py dans la racine du bundle avec le contenu suivant :

Python

from dataclasses import replace


from databricks.bundles.core import Bundle, job_mutator
from databricks.bundles.jobs import Job, JobEmailNotifications


@job_mutator
def add_email_notifications(bundle: Bundle, job: Job) -> Job:
    if job.email_notifications:
        return job


    email_notifications = JobEmailNotifications.from_dict(
        {
            "on_failure": ["${workspace.current_user.userName}"],
        }
    )


    return replace(job, email_notifications=email_notifications)

Utilisez maintenant la configuration suivante pour exécuter la fonction add_email_notifications pendant le déploiement du bundle. Cela met à jour chaque job défini dans le bundle avec des notifications par e-mail s'ils sont absents. Les fonctions mutateurs doivent être spécifiées dans databricks.yml, et sont exécutées dans l'ordre spécifié. Les mutateurs de job sont exécutés pour chaque job défini dans un bundle et peuvent soit renvoyer une copie mise à jour, soit une entrée non modifiée. Les mutateurs peuvent également être utilisés pour d'autres champs, tels que la configuration des clusters de Job default ou des SQL Warehouse.

YAML

python:
  mutators:
    - 'mutators:add_email_notifications'

Si les fonctions lèvent une exception pendant l'exécution du mutateur, le déploiement du bundle est annulé.

astuce

Pour configurer des préréglages pour les cibles (par exemple, pour relancer les planifications pour la cible prod), utilisez les modes de déploiement et les préréglages. Voir Préréglages personnalisés.

Ressources supplémentaires

• Exemples de configuration de bundle
• Ajouter des tâches aux Jobs dans les Bundles d'Automatisation Déclarative
• Remplacer par les paramètres cibles
• bundle groupe de commandes