Acessar valores de parâmetro de uma tarefa

Este artigo descreve como acessar valores de parâmetro do código em suas tarefas, incluindo blocos de anotações do Databricks, scripts Python e arquivos SQL.

Os parâmetros incluem parâmetros definidos pelo usuário, saída de valores de tarefas upstream e valores de metadados gerados pelo trabalho. Confira Parametrizar trabalhos.

Embora os detalhes variem de acordo com o tipo de tarefa, há quatro métodos comuns usados para referenciar valores de parâmetro do código-fonte:

• Widgets de utilitários do Databricks
• Sintaxe de parâmetro chamada SQL
• Referências de valores dinâmicos
• Argumentos de código

Em cada um desses casos, você faz referência à chave do parâmetro para acessar seu valor. Às vezes, a chave é conhecida como o nome do parâmetro.

Usar dbutils no código em um notebook

O código do notebook em execução em uma tarefa pode acessar os valores dos parâmetros com a biblioteca dbutils . O exemplo a seguir mostra como usar dbutils no Python para obter o valor de um year_param parâmetro de tarefa que é passado para a tarefa do notebook.

# Retrieve a job-level parameter
year_value = dbutils.widgets.get("year_param")

# Use the value in your code
display(babynames.filter(babynames.Year == year_value))

Os parâmetros são acessados pelo nome. Se você tiver parâmetros de tarefa e parâmetros de trabalho com o mesmo nome, os parâmetros de trabalho serão buscados.

O código acima produz um erro quando executado em um notebook autônomo e não como parte de um trabalho porque os parâmetros não são enviados para um notebook autônomo. Você pode definir um padrão para o year_param parâmetro com o seguinte código:

# Set a default (for when not running in a job)
dbutils.widgets.text("year_param", "2012", "Year Parameter")

# Retrieve a job-level parameter (will use default if it doesn't exist)
year_value = dbutils.widgets.get("year_param")

# Use the value in your code
display(babynames.filter(babynames.Year == year_value))

Embora isso seja útil para testar fora de um trabalho, ele também tem a desvantagem de ocultar quando os parâmetros de tarefa ou trabalho não são configurados corretamente.

Usar parâmetros nomeados em um notebook SQL

Ao executar o SQL em uma tarefa de notebook, você pode usar a sintaxe de parâmetro nomeada para acessar parâmetros de tarefa. Por exemplo, para acessar um parâmetro de tarefa chamado year_param, você pode obter seu valor usando :year_param em sua consulta:

SELECT *
FROM baby_names_prepared
WHERE Year_Of_Birth = :year_param
GROUP BY First_Name

Acesso como os argumentos de código

Para alguns parâmetros de tipos de tarefa, são passados para o código como argumentos. Os seguintes tipos de tarefa têm argumentos passados para eles:

• Python script
• Python Wheel
• JAR
• Spark Submit

Para obter detalhes, consulte Detalhes por tipo de tarefa, mais adiante neste artigo.

Para as tarefas dbt, os parâmetros são passados chamando os comandos dbt em sua tarefa.

Usar referências de valor dinâmico ao configurar uma tarefa

Quando você estiver configurando uma tarefa na interface do usuário do Azure Databricks, use a sintaxe de referência de valor dinâmico para acessar parâmetros de trabalho ou outros valores dinâmicos. Para acessar parâmetros de trabalho, use a sintaxe: {{job.parameters.<name>}}. Por exemplo, ao configurar uma Python wheel tarefa, você pode definir entradas chave e valor de um parâmetro para fazer referência a um parâmetro de trabalho chamado year_param, como year / Year_{{job.parameters.year_param}}. Além de fornecer acesso a parâmetros na configuração, os valores dinâmicos também fornecem acesso a outros dados sobre seu trabalho ou tarefa, por exemplo, o {{job.id}}. Você pode clicar {} na configuração da tarefa para obter uma lista de possíveis valores dinâmicos e inseri-los em sua configuração.

Detalhes por tipo de tarefa

Qual desses métodos você usa depende do tipo de tarefa.

Tipo de tarefa	Acesso na configuração	Acesso no código
Notebooks	Você pode usar as referências de valores dinâmicos na interface do usuário do Azure Databricks para configurar o notebook (por exemplo, para referir-se aos parâmetros do trabalho nos valores dos parâmetros da tarefa). Você pode substituir ou adicionar parâmetros adicionais ao executar manualmente uma tarefa usando a opção Executar um trabalho com configurações diferentes .	Você pode usar parâmetros nomeados para SQL em seu notebook ou dbutils.widgets em seu código.
Python Script	Os parâmetros definidos na tarefa são passados como argumentos para o script. Você pode usar referências de valor dinâmico na caixa de texto Parâmetros .	Os parâmetros podem ser lidos como argumentos posicionais ou analisados usando o módulo argparse no Python.
Roda Python	Os parâmetros definidos na definição da tarefa são passados como argumentos de palavra-chave para o código. Os arquivos de roda do Python devem ser configurados para aceitar argumentos de palavra-chave. Você pode usar referências de valor dinâmico nos valores de seus parâmetros.	Acesse como argumentos de palavra-chave para seu script. Para ver um exemplo de leitura de argumentos em um script Python empacotado em um arquivo wheel do Python, consulte Usar um arquivo wheel do Python em Lakeflow Jobs.
SQL	Você pode usar referências de valor dinâmico na configuração da tarefa.	Utilize parâmetros nomeados para acessar valores de parâmetro.
Pipeline	Os pipelines não dão suporte à passagem de parâmetros para a tarefa.	Não há suporte.
Painel de Controle	As tarefas do painel não dão suporte à passagem de parâmetros para a tarefa.	Não há suporte.
Power BI	As tarefas do Power BI não dão suporte à passagem de parâmetros para a tarefa.	Não há suporte.
dbt	Você pode usar as referências de valor dinâmico para passar os parâmetros como os comandos dbt ao configurar sua tarefa.	Acesse como comandos dbt.
JARRO	Você pode usar referências de valor dinâmico para passar parâmetros como argumentos na caixa de texto Parâmetros ao configurar sua tarefa.	Os parâmetros são acessados como argumentos para o método principal da classe principal.
Envio Spark	Você pode usar referências de valor dinâmico para passar parâmetros como argumentos na caixa de texto Parâmetros ao configurar sua tarefa.	Os parâmetros são acessados como argumentos para o método principal da classe principal.
Executar tarefa	Você pode usar referências de valor dinâmico para criar um conjunto de parâmetros de trabalho ao configurar sua tarefa. Os valores podem incluir referências de valor dinâmico.	Não aplicável.
Condição if/else	Você pode usar referências de valor dinâmico ao configurar sua tarefa, por exemplo, na Condição.	Não aplicável.
Para cada	Você pode usar referências de valor dinâmico ao configurar as Entradas para sua tarefa. A tarefa aninhada recebe uma entrada como um parâmetro de tarefa para cada iteração da tarefa aninhada.	As tarefas aninhadas acessam os parâmetros, com base no tipo de tarefa.
Notebook da Sala Limpa	Você pode usar as referências de valores dinâmicos na interface do usuário do Azure Databricks para configurar o notebook (por exemplo, para referir-se aos parâmetros do trabalho nos valores dos parâmetros da tarefa).	Você pode usar parâmetros nomeados para SQL em seu notebook ou dbutils.widgets em seu código.