O que é uma referência de valor dinâmico?

As referências de valores dinâmicos descrevem um conjunto de variáveis disponíveis ao configurar o Job e a tarefa. Use referências de valores dinâmicos para configurar instruções condicionais para a tarefa ou para passar informações como parâmetros ou argumentos.

As referências de valores dinâmicos incluem informações como

• Valores configurados para o trabalho, incluindo o nome do trabalho, os nomes das tarefas e o tipo de acionador.

• Metadados gerados sobre o trabalho, incluindo o ID do trabalho, o ID de execução e o horário de início da execução do trabalho.

• informações sobre quantas tentativas de reparo um trabalho fez ou quantas tentativas de execução de uma tarefa foram feitas.

• O estado do resultado de uma tarefa especificada.

• Valores configurados usando parâmetros de trabalho, parâmetros de tarefa ou definidos usando valores de tarefa.

Use referências de valores dinâmicos

Use referências de valores dinâmicos ao configurar o Job ou a tarefa. O senhor não pode fazer referência direta a referências de valores dinâmicos do ativo configurado usando tarefas como Notebook, consultas ou JARs. As referências de valores dinâmicos devem ser definidas usando parâmetros ou campos que passam o contexto para a tarefa.

As referências de valores dinâmicos usam chaves duplas ({{ }}). Quando um Job ou tarefa é executado, um literal de cadeia de caracteres substitui a referência de valor dinâmico. Por exemplo, se o senhor configurar o seguinte parâmetro key-value como um parâmetro de tarefa:

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

Se o ID de execução for 550315892394120, o valor de job_run_id será avaliado como job_550315892394120.

Observação

O conteúdo dos colchetes duplos não é avaliado como expressões. O senhor não pode executar operações ou funções entre chaves duplas.

Os identificadores de valores fornecidos pelo usuário suportam caracteres alfanuméricos e sublinhados. Escape a chave que contém caracteres especiais, cercando o identificador com pontos traseiros ( ` ` ).

Os erros de sintaxe, incluindo valores de referência dinâmica inexistentes e chaves ausentes, são silenciosamente ignorados e tratados como literais strings. Uma mensagem de erro será exibida se você fornecer uma referência inválida pertencente a um namespace conhecido, por exemplo, {{job.notebook_url}}.

Usar referências de valores dinâmicos na interface do usuário do trabalho

Os campos que aceitam referências de valores dinâmicos fornecem um atalho para inserir referências de valores dinâmicos disponíveis. Clique em {} para ver essa lista e inseri-la no campo fornecido.

Observação

A interface do usuário não preenche automaticamente a chave para fazer referência aos valores de tarefa.

Muitos campos que aceitam referências de valores dinâmicos exigem formatação adicional para serem usados corretamente. Consulte Configurar parâmetros da tarefa.

Usar referências de valores dinâmicos em uma tarefa JSON

Use a sintaxe {{ }} para usar valores dinâmicos nas definições do Job JSON usadas pelos sites Databricks CLI e REST API.

Job e os parâmetros de tarefa têm sintaxe diferente, e a sintaxe dos parâmetros de tarefa varia de acordo com o tipo de tarefa.

O exemplo a seguir mostra a sintaxe parcial do site JSON para configurar os parâmetros do Job usando referências de valores dinâmicos:

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

O exemplo a seguir mostra a sintaxe parcial do site JSON para configurar os parâmetros de tarefa do Notebook usando uma referência de valor dinâmico:

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

Revisar parâmetros para a execução de um trabalho

Após a conclusão de uma tarefa, o senhor pode ver os valores dos parâmetros resolvidos em Parâmetros na página de detalhes da execução. Veja os detalhes da execução do trabalho.

Referências de valor suportadas

As seguintes referências de valores dinâmicos são suportadas:

Referência	Descrição
{{job.id}}	O identificador exclusivo atribuído ao trabalho.
{{job.name}}	O nome do trabalho no momento da execução do trabalho.
{{job.run_id}}	O identificador exclusivo atribuído à execução do trabalho.
{{job.repair_count}}	O número de tentativas de reparo na execução do trabalho atual.
{{job.start_time.<argument>}}	Um valor baseado na hora (no fuso horário UTC) em que a execução do trabalho começou. O valor de retorno é baseado na opção argument. Consulte Opções para valores de data e hora.
{{job.parameters.<name>}}	O valor do parâmetro Job-level com o endereço key <name>.
{{job.trigger.type}}	O tipo de acionador da execução do trabalho. Os valores possíveis são periodic, one_time, run_job_task, file_arrival, continuous e table.
{{job.trigger.file_arrival.location}}	Se um acionador de chegada de arquivo estiver configurado para esse trabalho, o valor do local de armazenamento.
{{job.trigger.time.<argument>}}	Um valor baseado na hora (no fuso horário UTC) em que a execução do trabalho foi acionada, arredondado para baixo até o minuto mais próximo para trabalhos com um cron programar. O valor de retorno é baseado na opção argument. Consulte Opções para valores de data e hora.
{{task.name}}	O nome da tarefa atual.
{{task.run_id}}	O identificador exclusivo da execução da tarefa atual.
{{task.execution_count}}	O número de vezes que a tarefa atual foi executada (incluindo novas tentativas e reparos).
{{task.notebook_path}}	O caminho do Notebook da tarefa atual do Notebook.
{{tasks.<task_name>.run_id}}	O identificador exclusivo atribuído à execução da tarefa para <task_name>.
{{tasks.<task_name>.result_state}}	O estado do resultado da tarefa <task_name>. Os valores possíveis são success, failed, excluded, canceled, evicted, timedout, upstream_canceled, upstream_evicted e upstream_failed.
{{tasks.<task_name>.error_code}}	O código de erro da tarefa <task_name> se ocorrer um erro na execução da tarefa. Exemplos de valores possíveis são RunExecutionError, ResourceNotFound e UnauthorizedError. Para uma tarefa bem-sucedida, isso é avaliado como uma cadeia de caracteres vazia.
{{tasks.<task_name>.execution_count}}	O número de vezes que a tarefa <task_name> foi executada (incluindo novas tentativas e reparos).
{{tasks.<task_name>.notebook_path}}	O caminho para o Notebook para a tarefa do Notebook <task_name>.
{{tasks.<task_name>.values.<value_name>}}	O valor da tarefa com o key <value_name> que foi definido pela tarefa <task_name>.
{{workspace.id}}	O identificador exclusivo atribuído ao site workspace.
{{workspace.url}}	O URL do site workspace.

O senhor pode definir essas referências com qualquer tarefa. Consulte Configurar parâmetros da tarefa.

O senhor também pode passar parâmetros entre tarefas em um trabalho com valores de tarefa. Consulte Usar valores de tarefa para passar informações entre tarefas.

Opções para valores de data e hora

Use os argumentos a seguir para especificar o valor de retorno das variáveis de parâmetros com base no tempo. Todos os valores de retorno são baseados em um carimbo de data/hora no fuso horário UTC.

Argumento	Descrição
iso_weekday	Retorna um dígito de 1 a 7, representando o dia da semana do timestamp.
is_weekday	Retorna true se o carimbo de data/hora for em um dia da semana.
iso_date	Retorna a data no formato ISO.
iso_datetime	Retorna a data e a hora no formato ISO.
year	Retorna a parte do ano do carimbo de data/hora.
month	Retorna a parte mensal do carimbo de data/hora.
day	Retorna a parte do dia do carimbo de data/hora.
hour	Retorna a parte da hora do carimbo de data/hora.
minute	Retorna a parte minuciosa do carimbo de data/hora.
second	Retorna a segunda parte do carimbo de data/hora.
timestamp_ms	Retorna o carimbo de data/hora em milissegundos.

Referências de valores dinâmicos obsoletas

As seguintes referências de valores dinâmicos estão obsoletas. A referência de substituição recomendada está incluída na descrição de cada variável.

Variável	Descrição
{{job_id}}	O identificador exclusivo atribuído a um trabalho. Em vez disso, use job.id.
{{run_id}}	O identificador exclusivo atribuído a uma execução de tarefa. Em vez disso, use task.run_id.
{{start_date}}	A data em que a tarefa execução começar. O formato é YYYY-MM-DD no fuso horário UTC. Em vez disso, use job.start_time.<argument>.
{{start_time}}	O registro de data e hora do início da execução após o site cluster ter sido criado e estar pronto. O formato é de milissegundos desde a época do UNIX no fuso horário UTC, conforme retornado por System.currentTimeMillis(). Em vez disso, use job.start_time.<format>.
{{task_retry_count}}	O número de novas tentativas de execução de uma tarefa se a primeira tentativa falhar. O valor é 0 para a primeira tentativa e aumenta a cada nova tentativa. Em vez disso, use task.execution_count.
{{parent_run_id}}	O identificador exclusivo atribuído à execução de um trabalho com várias tarefas. Em vez disso, use job.run_id.
{{task_key}}	O nome exclusivo atribuído a uma tarefa que faz parte de um trabalho com várias tarefas. Em vez disso, use task.name.