Qu’est-ce qu’une référence de valeur dynamique ?

Les références de valeur dynamiques décrivent une collection de variables disponibles lors de la configuration des projets et des tâches. Utilisez les références de valeur dynamiques pour configurer des instructions conditionnelles pour les tâches ou pour transférer des informations comme paramètres ou arguments.

Les références aux valeurs dynamiques comprennent des informations comme :

• Valeurs configurées pour le projet, notamment le nom du projet, les noms des tâches, et le type de déclencheur.
• Métadonnées générées sur le projet, notamment l’ID tâche, l’identifiant de l’exécution et l’heure de début de l’exécution du projet.
• Informations sur le nombre de tentatives de réparation d’un projet ou de nouvelles tentatives d’exécution d’une tâche.
• État de résultat d’une tâche spécifiée.
• Valeurs configurées à l’aide des paramètres du projet, des paramètres de la tâche ou définies à l’aide des valeurs de la tâche.

Utiliser des références de valeur dynamiques

Utilisez des références de valeur dynamiques lors de la configuration de projets ou de tâches. Vous ne pouvez pas faire directement référence à des valeurs dynamiques à partir de ressources configurées à l’aide de tâches comme des notebooks, des requêtes ou des JAR. Les références à des valeurs dynamiques doivent être définies à l’aide de paramètres ou de champs qui transfèrent le contexte aux tâches.

Les références à des valeurs dynamiques utilisent deux accolades doubles ({{ }}). Lorsqu’un projet ou une tâche s’exécute, une chaîne littérale remplace la référence de la valeur dynamique. Par exemple, si vous configurez la paire clé-valeur suivante comme paramètre de tâche :

{"job_run_id": "job_{{job.run_id}}"}

Si votre ID d’exécution est 550315892394120, la valeur pour job_run_id est évaluée à job_550315892394120

Utiliser des références de valeur dynamique dans l’interface utilisateur des tâches

Les champs qui acceptent des références de valeur dynamique fournissent un raccourci pour insérer des références de valeur dynamique disponibles. Cliquez sur { } pour afficher cette liste et l’insérer dans le champ fourni.

Utiliser des références de valeur dynamique dans un JSON de projet

Utilisez la syntaxe {{ }} pour utiliser des valeurs dynamiques dans les définitions JSON de projet utilisées par la CLI Databricks et l’API REST.

Les paramètres de projet et de tâche ont une syntaxe différente et la syntaxe des paramètres de tâche varie selon le type de tâche.

L’exemple suivant affiche la syntaxe JSON partielle pour configurer les paramètres de projet à l’aide de références de valeur dynamique :

{
  "parameters": [
    {
      "name": "my_job_id",
      "default": "{{job.id}}"
    },
    {
      "name": "run_date",
      "default": "{{job.start_time.iso_date}}"
    }
  ]
}

L’exemple suivant affiche la syntaxe JSON partielle pour configurer les paramètres de projet du notebook à l’aide de références de valeur dynamique :

{
  "notebook_task": {
    "base_parameters": {
      "workspace_id": "workspace_{{workspace.id}}",
      "file_arrival_location": "{{job.trigger.file_arrival.location}}"
    }
  }
}

Réviser les paramètres d’une exécution de projet

Une fois une tâche terminée, vous pouvez voir les valeurs résolues des paramètres sous Paramètres sur la page des détails de l’exécution. Consultez Afficher les détails de l’exécution d’un travail.

Références de valeurs prises en charge

Les références de valeur dynamiques suivantes sont prises en charge :

Vous pouvez définir ces références avec n’importe quelle tâche. Consultez Configurer les paramètres de tâche. Les paramètres de remplissage ne sont disponibles que lors de la création d’un travail de remplissage.

Vous pouvez également transmettre des paramètres entre les tâches d’un travail avec des valeurs de tâche. Consultez Utiliser les valeurs de tâche pour transférer des informations entre les tâches.

Options des valeurs de date et d’heure

Utilisez les arguments suivants pour spécifier la valeur renvoyée depuis des variables de paramètre basées sur le temps. Toutes les valeurs renvoyées sont basées sur un horodateur du fuseau horaire UTC.

Options de sortie SQL

Vous pouvez accéder à la sortie d’une tâche SQL en amont à l’aide de valeurs dynamiques.

Par exemple, si vous avez une tâche SQL appelée sales_by_year avec le code SQL suivant, elle crée une sortie basée sur l’instruction finale SELECT .

-- Generate example data
CREATE OR REPLACE TEMP VIEW example_sales AS
SELECT * FROM VALUES
  (2020, 12),
  (2021, 23),
  (2022, 47),
  (2023, 15),
  (2024, 22)
AS example_sales(sales_year, num_sales);

-- Query example data
SELECT sales_year, num_sales FROM example_sales;

Vous pouvez référencer la sortie dans une tâche en aval en créant une configuration de tâche à l’aide d’une {{tasks.<task_name>.output.<argument>}} valeur dynamique.

Dans les tâches For each, les lignes sont envoyées de manière itérative à la tâche imbriquée. Dans cet exemple, si vous deviez définir les entrées d’une tâche For each sur {{tasks.sales_by_year.output.rows}}, puis dans la tâche imbriquée, vous pouvez utiliser la syntaxe {{input.<column_alias>}} pour envoyer de manière itérative les valeurs de ligne en tant que paramètres. Dans la configuration de tâche imbriquée, vous pouvez créer deux paramètres avec les paires yearclé-valeur :{{input.sales_year}}, et sales:{{input.num_sales}}. En supposant que la tâche imbriquée est une tâche SQL, vous pouvez référencer les valeurs de votre code avec une requête telle que la suivante.

-- Example: access data from previous query:
SELECT concat('In ', :year, ' we had ', :sales, ' sales.')

Pour plus d’informations sur For each les tâches et leurs tâches imbriquées, consultez Utiliser une For each tâche pour exécuter une autre tâche dans une boucle.

Références de valeur dynamique déconseillées

Les références de valeur dynamique suivantes sont déconseillées. La référence de remplacement recommandée est incluse dans la description de chaque variable.