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

Article
10/14/2024

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 des doubles accolades ({{ }}). 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

Remarque

Le contenu des accolades doubles n’est pas évalué en tant qu’expression. Vous ne pouvez pas exécuter d’opérations ou de fonctions entre des accolades doubles.

Les identificateurs de valeur fournis par l’utilisateur prennent en charge les caractères alphanumériques et les traits de soulignement. Ignorez les touches contenant des caractères spéciaux en entourant l’identifiant d’un astérisque (` `).

Les erreurs de syntaxe, y compris les valeurs de référence dynamiques inexistantes et les accolades manquantes, sont ignorées silencieusement et traitées comme des chaînes littérales. Un message d’erreur s’affiche si vous fournissez une référence non valide appartenant à un espace de noms connu, par exemple, {{job.notebook_url}}.

Utiliser des références de valeur dynamique dans l’IU des projets

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.

Remarque

L’IU ne termine pas automatiquement les clés pour référencer les valeurs de tâche.

De nombreux champs qui acceptent des références de valeur dynamique nécessitent une mise en forme supplémentaire pour les utiliser correctement. Consultez Configurer les paramètres de tâche.

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 valeur prises en charge

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

Référence	Description
`{{job.id}}`	Identificateur unique attribué au travail.
`{{job.name}}`	Nom du travail au moment de l’exécution du travail.
`{{job.run_id}}`	Identificateur unique attribué à l’exécution du travail.
`{{job.repair_count}}`	Nombre de tentatives de réparation sur l’exécution du travail en cours.
`{{job.start_time.<argument>}}`	Valeur basée sur l’heure (en horaire UTC) du démarrage de l’exécution du travail. La valeur de retour est basée sur l’option `argument`. Consultez Options des valeurs de date et d’heure.
`{{job.parameters.<name>}}`	Valeur du paramètre au niveau du travail avec la clé `<name>`.
`{{job.trigger.type}}`	Le type de déclencheur de l’exécution du travail. Les valeurs possibles sont : `periodic`, `one_time`, `run_job_task`, `file_arrival`, `continuous`, et `table`.
`{{job.trigger.file_arrival.location}}`	Si un déclencheur d’arrivée de fichier est configuré pour ce travail, la valeur de l’emplacement de stockage.
`{{job.trigger.time.<argument>}}`	Valeur basée sur l’heure (en horaire UTC) de déclenchement de l’exécution du travail, arrondie à la minute la plus proche pour les travaux avec une planification cron. La valeur de retour est basée sur l’option `argument`. Consultez Options des valeurs de date et d’heure.
`{{task.name}}`	Nom de la tâche en cours.
`{{task.run_id}}`	Identificateur unique de l’exécution de la tâche en cours.
`{{task.execution_count}}`	Nombre de fois que la tâche en cours a été exécutée (y compris les nouvelles tentatives et les réparations).
`{{task.notebook_path}}`	Chemin d’accès de la tâche de notebook en cours.
`{{tasks.<task_name>.run_id}}`	Identificateur unique attribué à l’exécution de tâche pour `<task_name>`.
`{{tasks.<task_name>.result_state}}`	L’état de résultat de la tâche `<task_name>`. Les valeurs possibles sont `success`, `failed`, `excluded`, `canceled`, `evicted`, `timedout`, `upstream_canceled`, `upstream_evicted` et `upstream_failed`.
`{{tasks.<task_name>.error_code}}`	Code d’erreur de la tâche `<task_name>` si une erreur s’est produite lors de l’exécution de la tâche. Exemples de valeurs possibles : `RunExecutionError`, `ResourceNotFound`et `UnauthorizedError`. Pour les tâches réussies, cela prend la valeur d’une chaîne vide.
`{{tasks.<task_name>.execution_count}}`	Nombre de fois que la tâche `<task_name>` a été exécutée (y compris les nouvelles tentatives et les réparations).
`{{tasks.<task_name>.notebook_path}}`	Chemin d’accès au notebook pour la tâche de notebook `<task_name>`.
`{{tasks.<task_name>.values.<value_name>}}`	Valeur de la tâche avec la clé `<value_name>` définie par la tâche `<task_name>`.
`{{workspace.id}}`	Identificateur unique affecté à l’espace de travail.
`{{workspace.url}}`	URL de l’espace de travail.

Vous pouvez définir ces références avec n’importe quelle tâche. Consultez Configurer les paramètres de tâche.

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.

Argument	Description
`iso_weekday`	Retourne un chiffre de 1 à 7, représentant le jour de la semaine du timestamp.
`is_weekday`	Retourne `true` si le timestamp est un jour de semaine.
`iso_date`	Retourne la date au format ISO.
`iso_datetime`	Retourne la date et l’heure au format ISO.
`year`	Retourne la partie année du timestamp.
`month`	Retourne la partie mois du timestamp.
`day`	Retourne la partie jour du timestamp.
`hour`	Retourne la partie heure du timestamp.
`minute`	Retourne la partie minute du timestamp.
`second`	Retourne la deuxième partie du timestamp.
`timestamp_ms`	Retourne le timestamp en millisecondes.

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.

Variable	Description
`{{job_id}}`	Identificateur unique attribué à un travail. Utilisez `job.id` à la place.
`{{run_id}}`	Identificateur unique attribué à une exécution de tâche. Utilisez `task.run_id` à la place.
`{{start_date}}`	Date de début d’exécution d’une tâche. Le format est aaaa-MM-JJ dans le fuseau horaire UTC. Utilisez `job.start_time.<argument>` à la place.
`{{start_time}}`	Timestamp de début d’exécution de l’exécution après la création et la préparation du cluster. Le format est en millisecondes depuis l’époque UNIX du fuseau horaire UTC, tel que rendu par `System.currentTimeMillis()`. Utilisez `job.start_time.<format>` à la place.
`{{task_retry_count}}`	Nombre de nouvelles tentatives qui ont été tentées pour exécuter une tâche en cas d’échec de la première tentative. La valeur est 0 pour la première tentative et est incrémentée à chaque nouvelle tentative. Utilisez `task.execution_count` à la place.
`{{parent_run_id}}`	Identificateur unique attribué à l’exécution d’un travail avec plusieurs tâches. Utilisez `job.run_id` à la place.
`{{task_key}}`	Nom unique attribué à une tâche qui fait partie d’un travail avec plusieurs tâches. Utilisez `task.name` à la place.

Partager via