Che cos'è un valore dinamico di riferimento?

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 relativi al job, inclusi l'ID del job, l'ID dell'esecuzione e l'ora di inizio esecuzione del job.
• Informazioni su quante volte è stato tentato di riparare un lavoro o su quante volte è stata eseguita una nuova prova 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à, una stringa letterale sostituisce il riferimento al valore dinamico. 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 viene valutato come job_550315892394120.

Nota

Il contenuto delle doppie parentesi graffe non viene interpretato come un'espressione. 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 riferimenti di valore dinamici in un processo 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 lavoro

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 all'attività.
{{job.name}}	Nome del job al momento dell'esecuzione del job.
{{job.run_id}}	Identificatore univoco assegnato all'esecuzione del lavoro.
{{job.repair_count}}	Numero di tentativi di riparazione 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 lavoro con la chiave <name>.
{{job.trigger.type}}	Il tipo di trigger dell'operazione eseguita. I valori possibili sono: periodic, one_time, run_job_task, file_arrival, continuous e table.
{{job.trigger.file_arrival.location}}	Se per questa attività è configurata un'attivazione all'arrivo del file, il valore della posizione di archiviazione.
{{job.trigger.time.<argument>}}	Un valore determinato dall'ora (nel fuso orario UTC) in cui è stata avviata l'esecuzione dell'attività, arrotondato al minuto inferiore più vicino per le attività 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à corrente del notebook.
{{tasks.<task_name>.run_id}}	L'identificatore univoco assegnato all'attività effettuata 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 chiave <value_name> che è stata impostata dall'attività <task_name>.
{{tasks.<task_name>.output.rows}}	Le righe di output di un'attività SQL <task_name> upstream. Se passato come input per un'attività For each , ogni riga viene inviata in modo iterativo all'attività nidificata. L'output SQL è limitato a 1.000 righe e 48 KB di dimensioni. Vedere Opzioni di output SQL.
{{tasks.<task_name>.output.first_row}}	La prima riga dell'output di un compito SQL a monte <task_name>. L'output SQL è limitato a 1.000 righe e 48 KB di dimensioni.
{{tasks.<task_name>.output.first_row.<column_alias>}}	Il valore della colonna <column_alias> nella prima riga dell'output di un'attività SQL upstream <task_name>. L'output SQL è limitato a 1.000 righe e 48 KB di dimensioni.
{{tasks.<task_name>.output.alert_state}}	Stato dell'attività di avviso SQL upstream. Il valore è uno di UNKNOWN, OKo TRIGGERED.
{{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 dell'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.

Opzioni di output SQL

È possibile accedere all'output di un'attività SQL upstream usando valori dinamici.

Ad esempio, se si dispone di un'attività SQL denominata sales_by_year con il codice SQL seguente, viene creato l'output in base all'istruzione 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;

È possibile fare riferimento all'output in un'attività downstream creando la configurazione dell'attività usando un {{tasks.<task_name>.output.<argument>}} valore dinamico.

Nelle For each attività le righe vengono inviate in modo iterativo all'attività nidificata. In questo esempio, se si impostano gli Inputs di un'attività For each su {{tasks.sales_by_year.output.rows}}, nell'attività nidificata è possibile usare la sintassi {{input.<column_alias>}} per inviare iterativamente i valori di riga come parametri. Nella configurazione dell'attività annidata è possibile creare due parametri con le coppie chiave-valore year:{{input.sales_year}} e sales:{{input.num_sales}}. Supponendo che il compito annidato sia un'attività SQL, puoi riferirti ai valori nel tuo codice con una query come la seguente.

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

Per ulteriori informazioni sulle attività For each e le loro attività annidate, consulta Usare un'attività For each per eseguire un'altra attività in un ciclo.

Nota

L'output della query SQL viene conservato per 7 giorni. Se il processo viene sospeso (ad esempio, in caso di errore) e quindi ripreso più di 7 giorni dopo, l'output della query SQL non sarà disponibile.

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'attività. 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 disponibilità 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}}	Nome univoco assegnato a un'attività che fa parte di un processo con più attività. Utilizzare invece task.name.