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

Artigo
10/05/2024

As referências de valor dinâmico descrevem uma coleção de variáveis disponíveis ao configurar trabalhos e tarefas. Use referências de valor dinâmico para configurar instruções condicionais para tarefas ou para passar informações como parâmetros ou argumentos.

As referências de valor dinâmico incluem informações como:

Valores configurados para o trabalho, incluindo o nome do trabalho, nomes de tarefas e tipo de gatilho.
Metadados gerados sobre o trabalho, incluindo o ID do trabalho, o ID de execução e a hora de início da execução do trabalho.
Informações sobre quantas tentativas de reparo um trabalho fez ou repetiu tentativas de execução de uma tarefa.
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.

Usar referências de valor dinâmico

Use referências de valor dinâmico ao configurar trabalhos ou tarefas. Não é possível fazer referência direta a referências de valor dinâmico de ativos configurados usando tarefas como blocos de anotações, consultas ou JARs. As referências de valores dinâmicos devem ser definidas usando parâmetros ou campos que passam o contexto para as tarefas.

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

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

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

Nota

O conteúdo das cintas duplas não é avaliado como expressões. Não é possível executar operações ou funções em chaves duplas.

Os identificadores de valor fornecidos pelo usuário suportam caracteres alfanuméricos e de sublinhado. Teclas de escape que contêm caracteres especiais cercando o identificador com backticks (` `).

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

Usar referências de valor dinâmico na interface do usuário de trabalhos

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

Nota

A interface do usuário não preenche automaticamente as chaves para fazer referência a valores de tarefas.

Muitos campos que aceitam referências de valor dinâmico requerem formatação adicional para usá-los corretamente. Consulte Configurar parâmetros da tarefa.

Usar referências de valor dinâmico em um JSON de trabalho

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

Os parâmetros de trabalho e tarefa têm sintaxe diferente, e a sintaxe do parâmetro de tarefa varia de acordo com o tipo de tarefa.

O exemplo a seguir mostra a sintaxe JSON parcial para configurar parâmetros de trabalho usando referências de valor dinâmico:

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

O exemplo a seguir mostra a sintaxe JSON parcial para configurar parâmetros de tarefa do bloco de anotações 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 uma execução de trabalho

Após a conclusão de uma tarefa, você poderá ver os valores de parâmetros resolvidos em Parâmetros na página de detalhes da execução. Consulte Exibir detalhes da execução do trabalho.

Referências de valor suportadas

As seguintes referências de valor dinâmico são suportadas:

Referência	Description
`{{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) iniciada pela execução do trabalho. O valor de retorno é baseado na `argument` opção. Consulte Opções para valores de data e hora.
`{{job.parameters.<name>}}`	O valor do parâmetro de nível de trabalho com a chave `<name>`.
`{{job.trigger.type}}`	O tipo de gatilho 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 gatilho 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 para o minuto mais próximo para trabalhos com uma agenda cron. O valor de retorno é baseado na `argument` opção. Consulte Opções para valores de data e hora.
`{{task.name}}`	O nome da tarefa atual.
`{{task.run_id}}`	O identificador exclusivo da tarefa atual executada.
`{{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 bloco de anotações da tarefa atual do bloco de anotações.
`{{tasks.<task_name>.run_id}}`	O identificador exclusivo atribuído à tarefa é executado para `<task_name>`.
`{{tasks.<task_name>.result_state}}`	O estado resultante da tarefa `<task_name>`. Os valores possíveis são `success`, `failed`, , `canceledexcluded`, `evicted`, `timedout`, `upstream_canceled`, `upstream_evicted`e `upstream_failed`.
`{{tasks.<task_name>.error_code}}`	O código de erro para a tarefa `<task_name>` se ocorreu um erro ao executar a tarefa. Exemplos de valores possíveis são `RunExecutionError`, `ResourceNotFound`e `UnauthorizedError`. Para tarefas bem-sucedidas, 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 bloco de notas para a tarefa `<task_name>`do bloco de notas .
`{{tasks.<task_name>.values.<value_name>}}`	O valor da tarefa com a chave `<value_name>` que foi definida pela tarefa `<task_name>`.
`{{workspace.id}}`	O identificador exclusivo atribuído ao espaço de trabalho.
`{{workspace.url}}`	A URL do espaço de trabalho.

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

Você 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 de variáveis de parâmetro baseadas em tempo. Todos os valores de retorno são baseados em um carimbo de data/hora no fuso horário UTC.

Argumento	Description
`iso_weekday`	Devolve um dígito de 1 a 7, representando o dia da semana do carimbo de data/hora.
`is_weekday`	Retorna `true` se o carimbo de data/hora estiver em um dia da semana.
`iso_date`	Devolve a data em formato ISO.
`iso_datetime`	Devolve a data e hora em formato ISO.
`year`	Devolve a parte do ano do carimbo de data/hora.
`month`	Devolve a parte do mês do carimbo de data/hora.
`day`	Devolve a parte do dia do carimbo de data/hora.
`hour`	Retorna a parte da hora do carimbo de data/hora.
`minute`	Retorna a parte do minuto do carimbo de data/hora.
`second`	Devolve a segunda parte do carimbo de data/hora.
`timestamp_ms`	Retorna o carimbo de data/hora em milissegundos.

Referências de valor dinâmico preteridas

As seguintes referências de valor dinâmico foram preteridas. A referência de substituição recomendada está incluída na descrição de cada variável.

Variável	Description
`{{job_id}}`	O identificador exclusivo atribuído a um trabalho. Utilize `job.id` em substituição.
`{{run_id}}`	O identificador exclusivo atribuído a uma tarefa executada. Utilize `task.run_id` em substituição.
`{{start_date}}`	A data de início da execução de uma tarefa. O formato é aaaa-MM-dd no fuso horário UTC. Utilize `job.start_time.<argument>` em substituição.
`{{start_time}}`	O carimbo de data/hora do início da execução da execução depois que o cluster é criado e pronto. O formato é milissegundos desde a época do UNIX no fuso horário UTC, conforme retornado pelo `System.currentTimeMillis()`. Utilize `job.start_time.<format>` em substituição.
`{{task_retry_count}}`	O número de novas tentativas que foram tentadas para executar uma tarefa se a primeira tentativa falhar. O valor é 0 para a primeira tentativa e aumenta a cada nova tentativa. Utilize `task.execution_count` em substituição.
`{{parent_run_id}}`	O identificador exclusivo atribuído à execução de um trabalho com várias tarefas. Utilize `job.run_id` em substituição.
`{{task_key}}`	O nome exclusivo atribuído a uma tarefa que faz parte de um trabalho com várias tarefas. Utilize `task.name` em substituição.

Partilhar via