Aller au contenu principal
Dernière mise à jour le

Substitutions et variables dans les Declarative Automation Bundles

Declarative Automation Bundles (anciennement connus sous le nom de Databricks Asset Bundles) prend en charge les substitutions et les variables personnalisées, ce qui rend vos fichiers de configuration de bundle 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 où un bundle est déployé et exécuté.

astuce

Vous pouvez également utiliser des références de valeur dynamique pour les valeurs de paramètre de job afin de transmettre le contexte d'une exécution de job aux tâches de job. Voir Références de valeurs dynamiques et Paramétrer les jobs.

Substitutions​

Vous pouvez utiliser des substitutions pour récupérer les valeurs des paramètres qui peuvent changer en fonction du contexte du déploiement et de l'exécution du bundle. Par exemple, des substitutions peuvent être utilisées pour faire référence aux valeurs des champs du bundle name, du bundle target et du workspace userName afin de construire le workspace root_path dans le fichier de configuration du bundle :

YAML
bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Si someone@example.com a déployé ce bundle, il serait déployé vers le chemin racine /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev.

Vous pouvez également créer des substitutions pour les ressources nommées. Par exemple, pour la définition de pipeline suivante, vous pouvez utiliser ${resources.pipelines.my_pipeline.target} pour la valeur de la cible du pipeline :

YAML
resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      schema: pipeline_bundle_${bundle.target}
      libraries:
        - notebook:
            path: ../src/my_pipeline.ipynb

      configuration:
        bundle.sourcePath: ${workspace.file_path}/src

Pour déterminer les substitutions valides, utilisez la référence de configuration de bundle, la référence de configuration de ressource ou la hiérarchie de schémas des objets correspondants documentée dans la référence d'API REST, ou la sortie de la commande bundle schema.

astuce

Pour une liste complète des substitutions disponibles pour les Ressources, consultez repository GitHub Databricks CLI out.fields.txt

Voici quelques substitutions couramment utilisées :

  • ${bundle.name}
  • ${bundle.target} # Use this substitution instead of ${bundle.environment}
  • ${workspace.host}
  • ${workspace.current_user.domain_friendly_name}
  • ${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 bundle 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 des informations sur le mappage variables, consultez variables.

La configuration d'exemple suivante définit les variables my_cluster_id et my_notebook_path:

YAML
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 des commandes du bundle, par le biais d’une variable d’environnement, ailleurs dans vos fichiers de configuration du bundle, ou dans le fichier .databricks/bundle/<target>/variable-overrides.json du projet de bundle. Consultez Définir la valeur d’une variable.

Référencer une variable​

Pour faire référence à une variable personnalisée dans la configuration de votre bundle, utilisez la substitution de variable ${var.<variable_name>}. Par exemple, la configuration suivante fait référence aux variables my_cluster_id et my_notebook_path:

YAML
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 défini de default valeur pour une variable, ou si vous souhaitez remplacer temporairement la valeur default d'une variable, fournissez la nouvelle valeur temporaire de la variable en utilisant l'une des approches suivantes.

remarque

Les variables de bundle sont des variables au moment du déploiement. Ils sont interprétés lorsque vous déployez le bundle. Par exemple, lorsque vous exécutez un Job, il exécute un Job précédemment déployé et les variables configurées pour ce déploiement, de sorte que le fait de transmettre des valeurs différentes pour les variables lors de l'exécution du Job ne s'appliquera pas. Au lieu de cela, transmettez des valeurs à une exécution de Job en utilisant les parameters du Job. Consultez Passer les Job parameters.

  • Fournissez la valeur de la variable dans le cadre d'une commande bundle telle que validate, deploy ou 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_id, et pour fournir la valeur de ./hello.py à la variable nommée my_notebook_path, exécutez :

    Bash
    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"

  • Indiquez la valeur de la variable en définissant une variable d'environnement. Le nom de la variable d'environnement doit start 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, deploy, ou run:

    Pour Linux et macOS :

    Bash
    export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py

    Pour Windows :

    Bash
    "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"

    Ou, fournissez la valeur de la variable dans le cadre d'une commande bundle telle que validate, deploy ou run, par exemple pour Linux et macOS :

    Bash
    BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate

    Ou pour Windows :

    Bash
    "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 en utilisant le mapping variables au sein du mapping targets, en suivant ce format :

    YAML
    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 :

    YAML
    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, en utilisant le format suivant :

    JSON
    {
      "<variable-name>": "<variable-value>"
    }

    Par exemple, pour fournir des valeurs aux 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 :

    JSON
    {
      "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 variables, utilisez la même approche pendant les phases de déploiement et d'exécution. Sinon, vous pourriez obtenir des résultats inattendus entre le moment d'un déploiement et l'exécution d'un Job ou d'un pipeline basé sur ce déploiement existant.

Ordre de priorité​

Le Databricks CLI recherche les valeurs des variables dans l'ordre suivant : il s'arrête lorsqu'il trouve une valeur pour une variable.

  1. Dans les options --var spécifiées dans la commande bundle.
  2. Dans toutes les variables d'environnement définies qui commencent par BUNDLE_VAR_.
  3. Dans le fichier variable-overrides.json, s'il existe.
  4. Dans n'importe quel mappage variables, parmi les mappages targets de vos fichiers de configuration de bundle.
  5. Toute valeur default pour la définition de cette variable, parmi les mappages variables de premier niveau dans vos fichiers de configuration de bundle.

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 de type complexe pour votre bundle dans sa configuration, définissez type sur complex.

remarque

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

Dans l'exemple suivant, les paramètres de clusters sont définis au sein d'une variable complexe personnalisée nommée my_cluster:

YAML
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/bundle/<target>/variable-overrides.json, comme illustré dans l'exemple suivant :

JSON
{
  "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 afin de récupérer l’ID d’un objet nommé en utilisant ce format :

YAML
variables:
  <variable-name>:
    lookup:
      <object-type>: '<object-name>'

Si une recherche est définie pour une variable, l'ID de l'objet avec le nom spécifié est utilisé comme valeur de la variable. Ceci 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é*.

YAML
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}

Substitution de sortie et valeurs des variables​

Pour vous assurer que vos substitutions et variables sont correctement spécifiées et analysées par les Declarative Automation Bundles, exécutez databricks bundle validate. Voir databricks bundle validate. Pour afficher les valeurs qui seront utilisées lors du déploiement d’un bundle, utilisez l’option --output json :

Bash
databricks bundle validate --output json

Par exemple, pour un bundle avec la variable my_cluster_id définie et utilisée dans une tâche de Job :

YAML
bundle:
  name: variables_bundle

variables:
  my_cluster_id:
    default: 1234-567890-abcde123

resources:
  jobs:
    variables_bundle_job:
      name: variables_bundle_job
      tasks:
        - task_key: notebook_task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ../src/notebook.ipynb

La sortie du schéma databricks bundle validate serait la suivante :

JSON
{
  "bundle": {
    "..."
    "name": "variables_bundle",
    "target": "dev",
  "..."
  },
  "resources": {
    "jobs": {
      "variables_bundle_job": {
        "deployment": {
          "kind": "BUNDLE",
          "metadata_file_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/state/metadata.json"
        },
        "max_concurrent_runs": 4,
        "name": "[dev someone] variables_bundle_job",
        "tasks": [
          {
            "existing_cluster_id": "1234-567890-abcde123",
            "notebook_task": {
              "notebook_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/files/variables_bundle/src/notebook"
            },
            "task_key": "notebook_task"
          },
        ],
      "..."
      }
    }
  },
  "..."
  "variables": {
    "my_cluster_id": {
      "default": "1234-567890-abcde123",
      "value": "1234-567890-abcde123"
    }
  },
"..."
}
Sur cette page