Che cos'è un valore dinamico di riferimento?

Articolo
10/16/2024

I valori dinamici di riferimento descrivono una raccolta di variabili disponibili durante la configurazione di processi e attività. Usare valori dinamici di riferimento per configurare istruzioni condizionali per i processi o per passare informazioni come parametri o argomenti.

I valori dinamici di riferimento includono informazioni quali:

Valori configurati per il processo, inclusi il nome del processo, i nomi delle attività e il tipo di trigger.
Metadati generati sul processo, inclusi l'ID processo, l'ID esecuzione e l'ora di inizio dell'esecuzione del processo.
Informazioni sul numero di tentativi di ripristino eseguiti o tentativi di esecuzione di un'attività.
Stato del risultato per un'attività specificata.
Valori configurati usando parametri di processo, parametri dell'attività o impostati usando i valori delle attività.

Usare valori dinamici di riferimento

Usare valori dinamici di riferimento durante la configurazione di processi o attività. Non è possibile fare riferimento direttamente a valori dinamici di riferimento dagli asset configurati usando attività come notebook, query o JAR. I valori dinamici di riferimento devono essere definiti usando parametri o campi che passano il contesto alle attività.

I valori dinamici di riferimento usano parentesi graffe doppie ({{ }}). Quando viene eseguito un processo o un'attività, un valore letterale stringa sostituisce il valore dinamico di riferimento. Ad esempio, se si configura la coppia chiave-valore seguente come parametro dell'attività:

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

Se l'ID esecuzione è 550315892394120, il valore per job_run_id restituisce job_550315892394120.

Nota

Il contenuto delle doppie parentesi graffe non viene valutato come espressioni. Non è possibile eseguire operazioni o funzioni in parentesi graffe doppie.

Gli identificatori di valore forniti dall'utente supportano caratteri alfanumerici e caratteri underscore. Chiavi di escape contenenti caratteri speciali che circondano l'identificatore con backtick (` `).

Gli errori di sintassi, inclusi i valori dinamici di riferimento inesistenti e le parentesi graffe mancanti, vengono ignorati automaticamente e vengono considerati come stringhe letterali. Viene visualizzato un messaggio di errore se si specifica un riferimento non valido appartenente a uno spazio dei nomi noto, ad esempio {{job.notebook_url}}.

Usare valori dinamici di riferimento nell'interfaccia utente dei processi

I campi che accettano valori dinamici di riferimento forniscono un collegamento per inserire valori dinamici di riferimento disponibili. Fare clic su { } per visualizzare l'elenco e inserirlo nel campo specificato.

Nota

L'interfaccia utente non completa automaticamente le chiavi per fare riferimento ai valori delle attività.

Molti campi che accettano valori dinamici di riferimento richiedono una formattazione aggiuntiva perché vengano usati correttamente. Vedere Configurare i parametri dell'attività.

Usare valori dinamici di riferimento in un’attività JSON

Usare la sintassi {{ }} per utilizzare valori dinamici nelle definizioni JSON del processo impiegate dall'interfaccia della riga di comando di Databricks e dall'API REST.

I parametri di processo e attività hanno sintassi diversa, e la sintassi dei parametri dell'attività varia in base al tipo di attività.

L'esempio seguente illustra la sintassi JSON parziale per configurare i parametri del processo usando valori dinamici di riferimento:

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

L'esempio seguente illustra la sintassi JSON parziale per configurare i parametri dell’attività del notebook usando un valore dinamico di riferimento:

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

Esaminare i parametri per l'esecuzione di un processo

Al termine di un'attività, è possibile visualizzare i valori dei parametri risolti alla voce Parametri nella pagina dei dettagli dell'esecuzione. Vedere Visualizzare i dettagli dell'esecuzione del processo.

Riferimenti ai valori supportati

Sono supportati i valori dinamici di riferimento seguenti:

Riferimento	Descrizione
`{{job.id}}`	Identificatore univoco assegnato al processo.
`{{job.name}}`	Nome del processo al momento dell'esecuzione del processo.
`{{job.run_id}}`	Identificatore univoco assegnato all’esecuzione del processo.
`{{job.repair_count}}`	Numero di tentativi di ripristino nell'esecuzione del processo corrente.
`{{job.start_time.<argument>}}`	Valore basato sull'ora (in fuso orario UTC) di avvio dell'esecuzione del processo. Il valore restituito si basa sull'opzione `argument`. Vedere Opzioni per i valori di data e ora.
`{{job.parameters.<name>}}`	Il valore del parametro a livello di processo con la chiave `<name>`.
`{{job.trigger.type}}`	Il tipo di trigger del processo eseguito. I valori possibili sono: `periodic`, `one_time`, `run_job_task`, `file_arrival`, `continuous` e `table`.
`{{job.trigger.file_arrival.location}}`	Se per questo processo è configurato un trigger di arrivo file, il valore della posizione di archiviazione.
`{{job.trigger.time.<argument>}}`	Valore basato sull'ora (nel fuso orario UTC) in cui è stata attivata l'esecuzione del processo, arrotondato per difetto al minuto più vicino per i processi con una pianificazione cron. Il valore restituito si basa sull'opzione `argument`. Vedere Opzioni per i valori di data e ora.
`{{task.name}}`	Il nome dell’attività corrente.
`{{task.run_id}}`	L’identificatore univoco dell'esecuzione dell'attività corrente.
`{{task.execution_count}}`	Il numero di volte in cui l'attività corrente è stata eseguita (inclusi i tentativi e le riparazioni).
`{{task.notebook_path}}`	Il percorso del notebook dell'attività notebook corrente.
`{{tasks.<task_name>.run_id}}`	L’identificatore univoco assegnato al processo eseguito per `<task_name>`.
`{{tasks.<task_name>.result_state}}`	Lo stato del risultato dell'attività `<task_name>`. I valori possibili sono `success`, `failed`, `excluded`, `canceled`, `evicted`, `timedout`, `upstream_canceled`, `upstream_evicted` e `upstream_failed`.
`{{tasks.<task_name>.error_code}}`	il codice di errore per l'attività `<task_name>` se si è verificato un errore durante l'esecuzione dell'attività. Esempi di valori possibili sono `RunExecutionError`, `ResourceNotFound` e `UnauthorizedError`. Per le attività riuscite, viene restituita una stringa vuota.
`{{tasks.<task_name>.execution_count}}`	Il numero di volte in cui l'attività `<task_name>` è stata eseguita (inclusi i tentativi e le riparazioni).
`{{tasks.<task_name>.notebook_path}}`	Il percorso del notebook per l'attività `<task_name>` del notebook.
`{{tasks.<task_name>.values.<value_name>}}`	Il valore dell'attività con la chiave `<value_name>` impostata dall'attività `<task_name>`.
`{{workspace.id}}`	L’identificatore univoco assegnato all’area di lavoro.
`{{workspace.url}}`	L’URL dell'area di lavoro.

È possibile impostare questi riferimenti con qualsiasi attività. Vedere Configurare i parametri dell'attività.

Inoltre, è possibile passare i parametri tra le attività in un processo con i valori delle attività. Vedere Usare i valori delle attività per passare informazioni tra le attività.

Opzioni per i valori di data e ora

Usare gli argomenti seguenti per specificare il valore restituito dalle variabili di parametro basate sul tempo. Tutti i valori restituiti si basano su un timestamp nel fuso orario UTC.

Argomento	Descrizione
`iso_weekday`	Restituisce una cifra compresa tra 1 e 7, che rappresenta il giorno della settimana del timestamp.
`is_weekday`	Restituisce `true` se il timestamp è in un giorno feriale.
`iso_date`	Restituisce la data in formato ISO.
`iso_datetime`	Restituisce la data e l'ora in formato ISO.
`year`	Restituisce la parte anno del timestamp.
`month`	Restituisce la parte mese del timestamp.
`day`	Restituisce la parte giorno del timestamp.
`hour`	Restituisce la parte ora del timestamp.
`minute`	Restituisce la parte minuti del timestamp.
`second`	Restituisce la parte secondi del timestamp.
`timestamp_ms`	Restituisce il timestamp in millisecondi.

Riferimenti a valori dinamici deprecati

I valori dinamici di riferimento seguenti sono deprecati. Il riferimento di sostituzione consigliato è incluso nella descrizione di ciascuna variabile.

Variabile	Descrizione
`{{job_id}}`	L’identificatore univoco assegnato a un processo. Utilizzare invece `job.id`.
`{{run_id}}`	L’identificatore univoco assegnato all’esecuzione di un processo. Utilizzare invece `task.run_id`.
`{{start_date}}`	La data di inizio dell'esecuzione di un'attività. Il formato è aaaa-MM-gg nel fuso orario UTC. Utilizzare invece `job.start_time.<argument>`.
`{{start_time}}`	Timestamp dell'inizio dell'esecuzione dopo la creazione e la preparazione del cluster. Il formato è in millisecondi dall'epoca UNIX nel fuso orario UTC, come restituito da `System.currentTimeMillis()`. Utilizzare invece `job.start_time.<format>`.
`{{task_retry_count}}`	Numero di tentativi che sono stati tentati nuovamente per eseguire un'attività se il primo tentativo ha dato esito negativo. Il valore è 0 per il primo tentativo e aumenta a ogni tentativo. Utilizzare invece `task.execution_count`.
`{{parent_run_id}}`	L’identificatore univoco assegnato all'esecuzione di un processo con più attività. Utilizzare invece `job.run_id`.
`{{task_key}}`	Il nome univoco assegnato a un'attività che fa parte di un processo con più attività. Utilizzare invece `task.name`.

Condividi tramite