Substitutions et variables dans les packs de ressources Databricks

Article
02/12/2025

Les packs de ressources Databricks prennent en charge les substitutions et les variables personnalisées, ce qui rend vos fichiers de configuration de pack plus modulaires et réutilisables. Les substitutions 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 du déploiement et de l’exécution d’un pack.

Conseil

Vous pouvez également utiliser des références de valeurs dynamiques pour les valeurs de paramètre de tâche afin de transmettre le contexte d’une exécution de travail aux tâches de travail. Consultez Qu’est-ce qu’une référence de valeur dynamique ? et Définir les paramètres de projets.

Substitutions

Vous pouvez utiliser des substitutions pour récupérer les valeurs des paramètres qui changent en fonction du contexte du déploiement et de l’exécution du pack.

Par exemple, lorsque vous exécutez la commande bundle validate --output json, vous pouvez voir un graphique comme celui-ci :

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

Les substitutions peuvent être utilisées pour faire référence aux valeurs du pack name, du pack target et des champs userName de l’espace de travail pour construire l’espace de travail root_path dans le fichier de configuration du pack :

bundle:
  name: hello-bundle

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

# ...

targets:
  dev:
    default: true

Vous pouvez également créer des substitutions pour les ressources nommées. Par exemple, pour le pipeline configuré avec le nom my_pipeline, ${resources.pipelines.my_pipeline.target} est la substitution de la valeur de la cible de my_pipeline.

Pour déterminer les substitutions valides, vous pouvez utiliser la hiérarchie de schéma documentée dans la référence de l’API REST ou utiliser la sortie de la commande bundle schema.

Voici quelques substitutions couramment utilisées :

${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.short_name}
${workspace.current_user.userName}
${workspace.file_path}
${workspace.root_path}
${resources.jobs.<job-name>.id}
${resources.models.<model-name>.name}
${resources.pipelines.<pipeline-name>.name}

Variables personnalisées

Vous pouvez définir des variables personnalisées simples et complexes dans votre pack pour permettre la récupération dynamique des valeurs nécessaires à de nombreux scénarios. Les variables personnalisées sont déclarées dans vos fichiers de configuration de bundle dans le mappage variables ou dans un fichier variable-overrides.json. Pour plus d’informations sur le mappage de variables, consultez les variables.

L’exemple de configuration suivant définit les variables my_cluster_id et my_notebook_path :

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

Si vous ne fournissez pas de valeur default pour une variable dans le cadre de cette déclaration, vous devez la définir lors de l’exécution de commandes groupées, via une variable d’environnement ou ailleurs dans vos fichiers de configuration du pack, comme décrit dans Définir la valeur d’une variable.

Vous pouvez également définir et définir des valeurs de variable dans le fichier .databricks/bundle/<target>/variable-overrides.json dans le projet groupé, où <target> est la cible de l’espace de travail, par exemple dev. Consultez Définir la valeur d’une variable.

Référencer une variable

Pour référencer une variable personnalisée dans la configuration du pack, utilisez la substitution de variable ${var.<variable_name>}. Par exemple, pour référencer des variables my_cluster_id et my_notebook_path :

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

Définir la valeur d’une variable

Si vous n’avez pas fourni de valeur default pour une variable, ou si vous souhaitez remplacer temporairement la valeur default d’une variable, fournissez la nouvelle valeur temporaire de la variable à l’aide d’une des approches suivantes :

Fournissez la valeur de la variable dans le cadre d’une commande bundle telle que validate, deployou run. Pour ce faire, utilisez l’option --var="<key>=<value>", où <key> est le nom de la variable et <value> est la valeur de la variable. Par exemple, dans le cadre de la commande bundle validate, pour fournir la valeur de 1234-567890-abcde123 à la variable nommée my_cluster_idet pour fournir la valeur de ./hello.py à la variable nommée my_notebook_path, exécutez :
```
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"

# Or:
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
```
Fournissez la valeur de la variable en définissant une variable d’environnement. Le nom de la variable d’environnement doit commencer par BUNDLE_VAR_. Pour définir des variables d’environnement, consultez la documentation de votre système d’exploitation. Par exemple, pour fournir la valeur de 1234-567890-abcde123 à la variable nommée my_cluster_id, et pour fournir la valeur de ./hello.py à la variable nommée my_notebook_path, exécutez la commande suivante avant d’appeler une commande bundle telle que validate, deployou run :

Pour Linux et macOS :
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
Pour Windows :
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
Vous pouvez également fournir la valeur de la variable dans le cadre d’une commande bundle telle que validate, deployou run, par exemple pour Linux et macOS :
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
Ou pour Windows :
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
Fournissez la valeur de la variable dans vos fichiers de configuration de bundle à l’aide du mappage variables dans le mappage targets, en suivant ce format :
```
variables:
  <variable-name>: <value>
```
Par exemple, pour définir des valeurs pour les variables nommées my_cluster_id et my_notebook_path pour deux cibles distinctes :
```
targets:
  dev:
    variables:
      my_cluster_id: 1234-567890-abcde123
      my_notebook_path: ./hello.py
  prod:
    variables:
      my_cluster_id: 2345-678901-bcdef234
      my_notebook_path: ./hello.py
```
Fournissez la valeur de la variable dans le fichier .databricks/bundle/<target>/variable-overrides.json, au format suivant :
```
{
  "<variable-name>": "<variable-value>"
}
```
Par exemple, pour fournir des valeurs pour les variables nommées my_cluster_id et my_notebook_path pour la cible de développement, créez un fichier .databricks/bundle/dev/variable-overrides.json et définissez son contenu sur :
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
Vous pouvez également définir des variables complexes dans le fichier variable-overrides.json.

Remarque

Quelle que soit l’approche que vous choisissez pour fournir des valeurs de variable, utilisez la même lors des phases de déploiement et d’exécution. Vous risquez sinon obtenir des résultats imprévisibles entre le moment d’un déploiement et une exécution de travail ou de pipeline basée sur ce déploiement existant.

Ordre de précédence

L’interface CLI Databricks recherche des valeurs pour les variables dans l’ordre suivant, en s’arrêtant lorsqu’elle trouve une valeur pour une variable :

dans toutes les options --var spécifiées dans le cadre de la commande bundle.
dans les variables d’environnement définies qui commencent par BUNDLE_VAR_.
Dans le fichier variables-overrides.json, s’il existe.
Dans tous les mappages variables, parmi les mappages targets dans vos fichiers de configuration de pack.
N’importe quelle valeur default pour la définition de cette variable, parmi les mappages variables de niveau supérieur dans vos fichiers de configuration de pack.

Définir une variable complexe

Une variable personnalisée est supposée être de type chaîne, sauf si vous la définissez comme une variable complexe. Pour définir une variable personnalisée avec un type complexe pour votre bundle dans votre configuration de bundle, définissez type sur complex.

Remarque

La seule valeur valide pour le paramètre type est complex. En outre, la validation du pack échoue si type est défini sur complex et que la valeur default définie pour la variable est une valeur unique.

Dans l’exemple suivant, les paramètres de cluster sont définis dans une variable complexe personnalisée nommée my_cluster :

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

Vous pouvez également définir une variable complexe dans le fichier .databricks/bundles/<target>/variable-overrides.json, comme illustré dans l’exemple suivant :

{
  "my_cluster": {
    "spark_version": "13.2.x-scala2.11",
    "node_type_id": "Standard_DS3_v2",
    "num_workers": 2
  }
}

Récupérer la valeur d’ID d’un objet

Pour les types d’objets alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal et warehouse, vous pouvez définir un lookup pour votre variable personnalisée pour récupérer un ID d’objet nommé au format suivant :

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

Si une recherche est définie pour une variable, l’ID de l’objet portant le nom spécifié est utilisé comme valeur de la variable. Cela garantit que l’ID résolu correct de l’objet est toujours utilisé pour la variable.

Remarque

Une erreur se produit si un objet portant le nom spécifié n’existe pas ou s’il existe plusieurs objets portant le nom spécifié.

Par exemple, dans la configuration suivante, ${var.my_cluster_id} sera remplacé par l’ID du cluster 12.2 partagé.

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}

Partager via

Substitutions et variables dans les packs de ressources Databricks

Substitutions

Variables personnalisées

Référencer une variable

Définir la valeur d’une variable

Ordre de précédence

Définir une variable complexe

Récupérer la valeur d’ID d’un objet

Commentaires

Ressources supplémentaires