Parametrização

Esta seção aborda parâmetros e como eles são usados em jobs e tarefas.

Tópicos:

• Sobre Parâmetros
• Parâmetros de Aprovação entre Tarefas e Notebook
• Adicionar Parâmetros a um Job
• Excluir Parâmetros de um Job
• Adicionar Parâmetros a uma Tarefa
• Excluir Parâmetros de uma Tarefa
• Executar um Job com Valores de Parâmetros Diferentes

Sobre Parâmetros

Você pode personalizar execuções de job especificando parâmetros que alteram o comportamento do job, da tarefa ou do processamento de job.

Os parâmetros podem ser fornecidos em três níveis diferentes de um workflow: nível de job, nível de tarefa e nível de execução de job. Os parâmetros têm a seguinte precedência no caso de conflitos: Execução do Job > Tarefa > Tarefa.

1. Parâmetros de Nível de Execução do Job: Os parâmetros de nível de execução do job especificados no payload de execução do job têm precedência sobre os parâmetros de nível de tarefa definidos na configuração do job. Isso significa que qualquer parâmetro especificado durante a execução do job substitui os padrões específicos da tarefa.
2. Parâmetros de Nível de Tarefa: Se os parâmetros de execução de job para uma tarefa específica não forem fornecidos, a tarefa usará os parâmetros definidos no nível da tarefa na configuração do job. Os parâmetros no nível do job com o mesmo nome substituem os parâmetros no nível da tarefa para essa tarefa específica. Então, se você quiser um parâmetro específico da tarefa, você deve nomeá-lo de forma diferente do parâmetro do job.
3. Parâmetros do Nível do Cargo: Se nem parâmetros de tempo de execução nem no nível da tarefa forem fornecidos, os valores padrão definidos no nível do job serão aplicados. Os parâmetros no nível do cargo são considerados padrões que podem ser usados se nenhum parâmetro mais específico estiver disponível.

Observação:

Os parâmetros do job são imutáveis em contextos de tarefa. Isso significa que se houver um job com o parâmetro JobParamA com o valor resolvido JobParamRuntimeValueA, a execução de TaskA não poderá alterar o valor de JobParamA. O valor de JobParamA permanece JobParamRuntimeValueA para todas as tarefas e para toda a execução do job. Como resultado, se você quisesse compartilhar informações entre tarefas, poderia usar parâmetros intermediários de armazenamento ou saída para conseguir isso.

Quando nomes de tarefas, chaves de valores de tarefas ou nomes de parâmetros de tarefas contêm caracteres especiais (como !@$%), você deve cercar esses identificadores com backticks (` `). Somente caracteres alfanuméricos e sublinhados podem ser usados sem cercar o identificador em backticks.

Por exemplo:

{
  "VariableWithSpecialChars": "{{job.parameters.`param$@`}}"
}

Os Parâmetros do Sistema são parâmetros modelados cujo valor é fornecido pelo sistema como parte das execuções de workflow e das execuções de tarefas subsequentes. Não é necessário fornecer nenhum valor, padrão ou não, para esses parâmetros modelados. O AI Data Platform Workbench tem uma lista fixa de parâmetros modelo/referências de valores dinâmicos válidos que são suportados no workflow. Os parâmetros do sistema são inseridos circundando-os com duas chaves. Por exemplo, {{job.id}},

Tabela 12-1 Parâmetros do Sistema Suportados

Parâmetro	Descrição
O nas	O identificador exclusivo atribuído ao hub
Português do Brasil	A região do hub
{{workspace.id}}	O identificador exclusivo atribuído ao espaço de trabalho
Português do Brasil	O URL do espaço de trabalho
São Paulo	O identificador exclusivo atribuído ao cargo
São Paulo	O nome do job no momento da execução do job
Português (Brasil)	O identificador exclusivo atribuído à execução do job
Português (Brasil)	O número de tentativas de reparo na execução do job atual
{{job.start_time}.	Um valor com base na hora (no fuso horário UTC) que a execução do job foi iniciada. O valor de retorno baseia-se na opção de argumento. Consulte Opções para obter valores de data e hora.
{{job.parameters.[nome]}}	O valor do parâmetro de nível de cargo com a chave [nome]
Português (Brasil)	O tipo de acionador da execução do job. Os valores possíveis são Manual e Programado.
Português (Brasil)	Se um acionador de chegada de arquivo for configurado para este job, o valor do local de armazenamento
Português (Brasil)	Um valor baseado no horário (no fuso horário UTC) em que a execução do job foi acionada, arredondado para o minuto mais próximo para jobs com uma programação cron. O valor de retorno baseia-se na opção de argumento. Consulte Opções para valores de data e hora.
{{task.name}}	O nome da tarefa atual
Português (Brasil)	O identificador exclusivo da execução da tarefa atual
Português do Brasil	O número de vezes que a tarefa atual foi executada (incluindo repetições e reparos)
Português do Brasil	O caminho do notebook da tarefa de notebook atual
{{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 êxito, falha, exclusão, cancelamento, ignorado, timeout, upstream_canceled e upstream_failed.
{{tasks.[task_name].error_code}}	O código de erro da 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 string vazia.
{{tasks.[task_name].execution_count}}	O número de vezes que a tarefa [task_name] foi executada (incluindo repetições e reparos)
{{tasks.[task_name].notebook_path}}	O caminho para o notebook da tarefa de notebook [task_name]
{{tasks.[task_name].values.[value_name]}}	O valor da tarefa com a chave [value_name] que foi definida pela tarefa [task_name]

Tabela 12-2 Opções para Data e Hora

Argumento	Descrição
dia da semana	Retorna um dígito de 1 a 7, representando o dia da semana no timestamp
is_weekday	Retorna true se o timestamp estiver em um dia da semana
iso_data	Retorna a data no formato ISO
iso_datetime	Retorna a data e a hora no formato ISO
ano	Retorna a parte do ano do timestamp
mês	Retorna a parte do mês do timestamp
dia	Retorna o período do dia do timestamp
hora	Retorna a parte da hora do timestamp
minuto	Retorna a parte do minuto do timestamp
segundo	Retorna a segunda parte do timestamp
timestamp_ms	Retorna o marcador de data/hora em milissegundos

Parâmetros de Aprovação entre Tarefas e Notebook

Você pode passar parâmetros de uma tarefa para um notebook e vice-versa. Isso permite o comportamento dinâmico do workflow, permitindo que os notebooks ajustem seu processamento com base nos valores de runtime.

O pacote oidlUtils.parameters fornece a funcionalidade necessária para tratar essas operações de parâmetro. O pacote oidlUtils é uma biblioteca de utilitários no AI Data Platform Workbench que simplifica tarefas como gerenciamento de parâmetros, aprovação de valores de tarefas e outras operações de workflow. É comumente usado em notebooks e tarefas para obter e definir parâmetros nos estágios do fluxo de trabalho.

Os valores-chave da tarefa são strings ou JSONs. Por exemplo, para usar uma string como seu valor de chave de tarefa, sua chamada de parâmetro teria a seguinte aparência:

oidlUtils.parameters.setTaskValue(key="payload", value="abc", "defaultValue")

Para usar um JSON como seu valor de chave de tarefa, sua chamada de parâmetro teria a seguinte aparência:

oidlUtils.parameters.setTaskValue(key="payload", value=json.dumps(payload), "defaultValue")

Exemplo de Workflow: Aprovando Parâmetros

Neste cenário, temos dois notebooks em um fluxo de trabalho. O Notebook 1 recebe parâmetros de uma tarefa, processa-os e define parâmetros de saída que são passados para o Notebook 2 na próxima tarefa.

Notebook 1: Obter e Definir Parâmetros

# Get parameter if already set in the task
param_key = "param1"
param_value = oidlUtils.parameters.getParameter(param_key, "defaultValue")
print(param_value)
print("Param {} value is {}".format(param_key, param_value))

 
# Set parameter value in the task
output_parameter_key = "output_parameter"
output_param_value = oidlUtils.parameters.getParameter(output_parameter_key, "defaultValue2")
print("Param {} value is {}".format(output_parameter_key, output_param_value))
oidlUtils.parameters.setTaskValue(output_parameter_key, "1234")

O primeiro notebook recupera um parâmetro (param1) passado da tarefa e, em seguida, define um novo parâmetro (output_param_2), que será usado na próxima tarefa.

Notebook 2: Ler o Parâmetro de Saída

output_param_2= "output_parameter"
param_value = oidlUtils.parameters.getTaskValue("GetSetParameter", output_param_2, "defaultValue")
print("Param {} value is {}".format(output_param_2, param_value))

O segundo notebook recebe o output_param_2 do Notebook 1 por meio da tarefa de workflow e o processa.

1. Tarefa 1: Notebook 1
   • Na primeira tarefa, os parâmetros podem ser passados para o Notebook 1 do job ou da própria tarefa.
   • O Notebook 1 processa os parâmetros como parâmetros de entrada param1 e define novos parâmetros de saída (por exemplo, output_param_2).
2. Tarefa 2: Notebook 2
   • Na segunda tarefa, o Notebook 2 recebe o parâmetro de saída da Tarefa 1 fazendo referência a ele diretamente no código de notebook, conforme mostrado acima, informando o nome da primeira tarefa "GetSetParameter" conforme definido no workflow.
   • O valor output_param_2 é passado para o Notebook 2, onde pode ser usado para processamento posterior.

Essa abordagem facilita a transmissão dinâmica de valores entre tarefas e notebooks, permitindo que seus fluxos de trabalho sejam mais flexíveis e adaptáveis.

Adicionar Parâmetros a um Job

Você pode fornecer aos seus trabalhos diferentes parâmetros para rastrear.

1. Na Home page, clique em Workflow.
2. Clique no job ao qual você deseja adicionar parâmetros e clique na guia Detalhes.
3. Em Parâmetros do Job, forneça a chave e o valor a serem rastreados. Para adicionar vários parâmetros, clique em Adicionar Parâmetro.
   As alterações feitas são salvas automaticamente.

Excluir Parâmetros de um Job

Você atualiza seus jobs para remover parâmetros que não são mais necessários.

1. Na Home page, clique em Workflow.
2. Clique no job do qual você deseja remover parâmetros e clique na guia Detalhes.
3. Em Parâmetros do Job, clique em Excluir ao lado do parâmetro que você deseja remover.
   As alterações feitas são salvas automaticamente.

Adicionar Parâmetros a uma Tarefa

Você pode adicionar parâmetros a tarefas para alterar seu comportamento.

1. Na Home page, clique em Workflow.
2. Clique no job que contém as tarefas às quais você deseja adicionar parâmetros e clique na guia Tarefas.
3. Clique na tarefa à qual deseja adicionar parâmetros.
4. Em Parâmetros, digite a chave e o valor do seu parâmetro. Para adicionar vários parâmetros, clique em Adicionar Parâmetro.
   As alterações feitas são salvas automaticamente.

Excluir Parâmetros de uma Tarefa

Você pode remover os parâmetros desnecessários de suas tarefas.

1. Na Home page, clique em Workflow.
2. Clique no job que contém as tarefas das quais você deseja excluir parâmetros e clique na guia Tarefas.
3. Clique na tarefa da qual deseja excluir parâmetros.
4. Clique em Excluir ao lado de cada parâmetro que você deseja remover.
   As alterações feitas são salvas automaticamente.

Executar um Job com Valores de Parâmetros Diferentes

Você pode optar por executar um job imediatamente com valores de parâmetro modificados.

1. Na Home page, clique em Workflow.
2. Clique no job que deseja executar.
3. Clique na seta para baixo ao lado da seta Executar Agora. Clique em Executar agora com parâmetros diferentes.
   
   

   

   
   
4. Informe novos valores. Esses valores de parâmetro só se aplicam a esta execução de job.
   
   

   

   
   
5. Clique em Executar.