Usando Parâmetros de Fluxo de Dados
No Data Integration, os tipos de parâmetros que você pode usar em fluxos de dados são definidos pelo usuário ou gerados pelo sistema.
O Data Integration gera os parâmetros do sistema no runtime, como SYS.TASK_START_TIME. Os valores dos parâmetros do sistema podem ser usados em expressões para registrar informações do sistema. No momento, você só pode usar parâmetros gerados pelo sistema com o operador de expressão.
Os parâmetros definidos pelo usuário oferecem a flexibilidade de usar tarefas com diferentes configurações de origens, destinos e transformações no design time e no runtime Para usar parâmetros, comece criando parâmetros para operadores em um fluxo de dados. Por exemplo, ao projetar um fluxo de dados, você usa a guia Detalhes do painel Propriedades de um operador para adicionar e designar parâmetros para os seguintes tipos de recursos:
- Ativo de dados (fonte e destino)
- Conexão (origem e destino)
- Esquema ou bucket (origem e destino)
- Entidade de dados (fonte e destino)
- Condição (filtro, junção, lookup, divisão)
Com uma entidade de dados, em vez de parametrizar o nome da entidade inteira, você pode incluir um ou mais parâmetros no nome da entidade de dados. Consulte Sobre Parâmetros em Nomes de Entidade de Dados.
Para operadores de fluxo de dados que usam expressões na configuração, como operadores de expressão e agregação, e os operadores de filtro, junção, lookup e divisão, você pode usar parâmetros nas expressões (também conhecidos como parâmetros escalares). Consulte Sobre Parâmetros de Expressão.
Ao utilizar parâmetros definidos pelo usuário e parâmetros de expressão em um fluxo de dados, especifique valores padrão para os parâmetros. Em seguida, ao criar uma tarefa de integração para o fluxo de dados parâmetroizado, você pode alterar um ou mais desses valores padrão na página Configurar Parâmetros ou pode alterar os valores no runtime. Se você não alterar um parâmetro durante o design time ou runtime, o conjunto de valores padrão no fluxo de dados será usado quando você executar a tarefa.
Os parâmetros também podem ser designados a recursos em tarefas como SQL, OCI Data Flow e tarefas REST. Para usar parâmetros para os recursos de origem e destino em uma tarefa do carregador de dados, consulte Usando Parâmetros para Origem e Destino.
Quando você adiciona uma tarefa parametrizada a um pipeline, é possível reconfigurar qualquer um dos valores dos parâmetros de entrada definidos no nível da tarefa ou no nível do fluxo de dados associado. Você também pode reconfigurar os valores dos parâmetros de expressão. Consulte Usando Parâmetros em Pipelines.
Considerações ao Usar Parâmetros
O uso de parâmetros impede que os recursos e valores de integração de dados fiquem permanentemente vinculados a uma tarefa de integração. Se você não designar parâmetros, os recursos e valores escolhidos serão usados sempre que a tarefa for executada. Os parâmetros oferecem a flexibilidade de reutilizar um design de fluxo de dados com diferentes recursos e valores de integração de dados. Para alterar valores no design time, use o painel Parâmetros ou a página Configurar Parâmetros quando configurar o fluxo de dados em uma tarefa de integração.
Embora os parâmetros sejam projetados para oferecer flexibilidade quando você executa o fluxo de dados em uma tarefa de integração, eles podem se tornar complexos e confusos rapidamente. Por exemplo, quando você adiciona um operador de origem a um fluxo de dados, você seleciona o ativo de dados, a conexão, o esquema e, em seguida, a entidade de dados que serve de origem de dados do fluxo de dados. Esses quatro valores são os valores padrão do operador. É possível designar parâmetros para cada um desses valores. Se você designar parâmetros, precisará ter cuidado especial e prestar muita atenção aos valores designados.
Suponha que você designe parâmetros aos valores de entidade de dados e ativo de dados, mas não aos valores de conexão nem de esquema; nesse caso, você corre o risco de obter erros quando alterar um valor de parâmetro. Por exemplo, se você alterar o valor do ativo de dados, o novo ativo de dados poderá não ter os mesmos valores de conexão, esquema ou entidade de dados que você definiu originalmente. O serviço Data Integration avisa quando você altera um valor, mas você deve analisar os relacionamentos por conta própria e garantir que o fluxo de dados ainda funcione com os valores alterados. Ao projetar o fluxo de dados, em uma tarefa de integração e ao executar a tarefa, lembre-se dos valores dos parâmetros em todos os lugares.
Os parâmetros são locais para o fluxo de dados ao qual eles são adicionados, de modo que você não pode compartilhar ou reutilizar parâmetros entre fluxos de dados.
Além disso, lembre-se dos casos em que você adiciona um parâmetro para uma nova entidade de dados de destino. As novas entidades de dados não têm forma, o que significa que ainda não contêm atributos. Para evitar encontrar erros no design time ou no runtime, tenha cuidado ao reutilizar parâmetros designados a novos objetos. Por exemplo, não designe o parâmetro cujo valor padrão é uma nova entidade de dados de destino a uma entidade de dados de origem ou a uma entidade de dados de destino existente.
Sobre Parâmetros de Expressão
Os parâmetros em expressões dão a você a flexibilidade para reutilizar expressões com diferentes valores no design time ou no runtime.
Você adiciona parâmetros a expressões no nível do fluxo de dados ao configurar operadores que usam expressões. Os parâmetros de expressão (também conhecidos como parâmetros escalares) são aplicáveis a operadores de filtro, junção, lookup, divisão, expressão e agregação. Dependendo do operador, você usa o Expression Builder ou o Condition Builder para adicionar parâmetros de expressão.
Os parâmetros de expressão adicionados a um operador são salvos no fluxo de dados e estão disponíveis a outros operadores aplicáveis dentro do fluxo de dados.
Um parâmetro de expressão tem um nome e um valor padrão e está associado a um tipo de dados. Os seguintes tipos são suportados:
NUMERICVARCHARDATEDATETIMEDECIMALDOUBLEFLOATINTEGERTIMESTAMPTINYINTBOOLEANLONGSTRING
Depois de criar um parâmetro de expressão, você não poderá alterar o nome nem o tipo nem quaisquer outras propriedades que o parâmetro possa ter dependendo do tipo. Somente o valor padrão pode ser modificado. Você pode alterar o valor padrão no design time e no runtime.
Por exemplo, considere a seguinte expressão para um filtro de condição em um fluxo de dados:
FILTER_1.COUNTRIES.CITY='Redwood Shores'Em vez de especificar um valor explícito para CITY, você pode usar um parâmetro na expressão. Suponha que você crie um parâmetro de expressão VARCHAR, quer dizer, P_VARCHAR, e defina o valor padrão como Redwood Shores. Em seguida, você pode editar o filtro de condição para usar o parâmetro de expressão:
FILTER_1.COUNTRIES.CITY=$P_VARCHARNo design time, você pode alterar o valor padrão de P_VARCHAR quando cria uma tarefa de integração que usa esse fluxo de dados. Em seguida, no runtime, é possível usar o conjunto de valores padrão na tarefa de integração ou editar o valor.
Todos os parâmetros de expressão adicionados a um fluxo de dados estão disponíveis no painel Parâmetros.
Sobre Parâmetros do Sistema
Um parâmetro do sistema tem nome e tipo. Você pode vincular o valor de um parâmetro do sistema, mas não pode modificá-lo.
Ao adicionar uma expressão a um operador de expressão em um fluxo de dados, use a guia Parâmetros no Expression Builder para ver a lista de parâmetros do sistema. Você pode usar parâmetros do sistema em expressões para registrar informações do sistema.
A tabela a seguir mostra os parâmetros do sistema que você pode usar.
| Nome | Tipo | Descrição |
|---|---|---|
| SYS.TASK_START_TIME | TIMESTAMP | Horário inicial da tarefa em UTC. |
| SYS.TASK_RUN_KEY |
OCID |
Identificador interno da execução da tarefa. |
| SYS.TASK_RUN_NAME |
STRING |
Nome da execução da tarefa. |
| SYS.TASK_SCHEDULE_TRIGGER_TIME | TIMESTAMP | O horário de acionamento da programação (para uma execução de tarefa iniciada por uma programação). O horário programado pode ser diferente do horário inicial da tarefa. |
| SYS.TASK_SCHEDULE_TIMEZONE | STRING | O fuso horário correspondente ao horário programado, que representa o horário definido na programação da tarefa. |
| SYS.RETRY_ATTEMPT | INTEGER | O número de tentativas de execução de uma tarefa configurada para novas tentativas quando uma execução falha. |
Note: Um valor de OCID é STRING.
Sobre Parâmetros em Nomes de Entidade de Dados
Ao configurar um operador de origem ou de destino em um fluxo de dados, você pode incluir um ou mais parâmetros no nome da entidade de dados, usando a sintaxe ${PARAMETER_NAME}.
Um nome de parâmetro faz distinção entre maiúsculas e minúsculas, e cada parâmetro usado deve ter um valor padrão.
Por exemplo, CUSTOMERS_${COUNTRY} pode retornar a tabela de banco de dados CUSTOMERS_USA e BANK_${COUNTRY}/* pode retornar os arquivos do serviço Object Storage em BANK_EU.
Para usar parâmetros em nomes de entidades de dados, você pode adicionar o parâmetro ao fluxo de dados antes de adicionar o operador de dados. Você também poderá adicionar o parâmetro no momento em que estiver configurando a entidade de dados para o operador.
-
Para adicionar parâmetros a um fluxo de dados, no fluxo de dados, selecione Parâmetros no menu Exibir da barra de ferramentas da tela para abrir o painel Parâmetros.
No painel de parâmetros, selecione Configuração e, em seguida, Adicionar.
No painel Adicionar parâmetro, configure um parâmetro do tipo de dados apropriado, por exemplo, VARCHAR ou NUMERIC, e adicione um valor padrão.
-
Para adicionar um parâmetro no momento da configuração da entidade de dados, no painel Pesquisar entidades de dados:
-
No menu Mais ações, selecione Adicionar parâmetro de fluxo de dados.
-
No campo de pesquisa, comece a digitar
${seguido por qualquer caractere. Se a parte frontal do nome do parâmetro corresponder aos parâmetros existentes no fluxo de dados, uma lista de nomes sugeridos será exibida. Para selecionar um parâmetro na lista, selecione o nome do parâmetro, complete a sintaxe adicionando}e pressione Enter. -
No campo de pesquisa, digite o nome do parâmetro. Se o nome do parâmetro ainda não existir no fluxo de dados e você pressionar Enter, o Data Integration exibirá o painel Adicionar parâmetro de fluxo de dados. Se preferir, depois de digitar o nome do parâmetro, selecione Adicionar parâmetro de fluxo de dados no menu Mais ações.
No painel Adicionar parâmetro de fluxo de dados, especifique o tipo de dados, o valor padrão e outras propriedades do parâmetro que você deseja adicionar e usar.
Somente para o serviço Object Storage em um operador de origem: Ao configurar a entidade de dados em um operador de origem que usa um ativo de dados do Object Storage, você pode usar parâmetros e padrões de arquivo. No painel Pesquisar entidades de dados por padrão, digite uma expressão usando parâmetros e padrões para selecionar uma ou mais entidades. Por exemplo:
ADDRESSES_${STATE}/* -
Para uma entidade de dados que inclua um parâmetro de fluxo de dados no nome, você não pode vincular o recurso de entidade a outro parâmetro. A opção Designar parâmetro não está disponível.
Sobre o Painel de Parâmetros
O painel Parâmetros em um fluxo de dados mostra os parâmetros que foram definidos em todo o fluxo de dados.
Use o painel Parâmetros para exibir:
- Todos os parâmetros criados para ativos de dados, conexões, esquemas ou buckets e entidades de dados usadas no fluxo de dados.
- Todos os parâmetros criados para modelar operadores, como filtro, junção e lookup.
- Todos os parâmetros de expressão criados para operadores de expressão, agregação e modelagem, como filtro, junção, lookup e divisão.
- Todos os parâmetros de fluxo de dados criados para nomes de entidades de dados em um fluxo de dados.
Para acessar o painel Parâmetros quando o fluxo de dados for aberto na tela do designer, selecione Parâmetros no menu Exibir na barra de ferramentas da tela.
O painel Parâmetros tem duas guias, Exibir e Configuração. Em qualquer uma das guias, você pode pesquisar a lista digitando o nome completo de um parâmetro.
Na guia Exibir, você pode:
- Ver os parâmetros que foram criados no fluxo de dados, independentemente de um parâmetro estar ou não designado a um objeto. Um parâmetro está designado quando você vê um valor ao lado de Usado em.
- Contrair e expandir os detalhes de cada parâmetro.
- Selecione o link Usado em para um parâmetro designado. O operador que referencia esse parâmetro é colocado em foco na tela e no painel Propriedades (guia Detalhes).
Na guia Configuração, você pode:
- Adicione parâmetros de expressão e parâmetros de fluxo de dados. Selecione Adicionar e, em seguida, use o painel Adicionar parâmetro que é exibido para definir o parâmetro.
- Altere o valor padrão de um parâmetro. No menu Ações (
) do parâmetro, selecione Editar para usar o painel Editar parâmetro para editar o valor. - Excluir um ou mais parâmetros. Consulte Excluindo um Parâmetro.
Adicionando um Parâmetro
Você adiciona e define parâmetros em operadores associados a origens de dados em um fluxo de dados.
Um parâmetro em um fluxo de dados pode ser reutilizado para representar o valor padrão de outro recurso do mesmo tipo, no mesmo fluxo de dados.
A forma como você define um parâmetro depende do tipo de recurso ao qual você está adicionando o parâmetro. Para todos os tipos de parâmetros, forneça um nome e uma descrição opcional e defina um valor padrão para o parâmetro. Não é possível alterar o nome e a descrição após a criação do parâmetro.
O procedimento a seguir não se aplica à adição de parâmetros em expressões e condições. Consulte Adicionando um Parâmetro de Expressão. Para adicionar parâmetros do sistema ao operador de expressão, consulte Adicionar e configurar um operador de expressão.
Para adicionar um parâmetro a um fluxo de dados:
Exibindo Parâmetros Definidos pelo Sistema e pelo Usuário
Você pode exibir os parâmetros do sistema disponíveis em um fluxo de dados no runtime e os parâmetros definidos pelo usuário que você criou.
Para parâmetros definidos pelo usuário, a lista inclui parâmetros designados e não utilizados no nível de fluxo de dados para ativos de dados, conexões, esquemas ou buckets e entidades de dados. Para parâmetros designados, você pode ver onde o parâmetro é usado no fluxo de dados.
A lista definida pelo usuário também inclui parâmetros de expressão utilizados e não utilizados. Parâmetros de expressão são parâmetros adicionados no nível do fluxo de dados usando o Condition Builder (operadores de filtro, junção, lookup e divisão) ou o Expression Builder (operadores de expressão e agregação).
Use a guia Parâmetros no painel Propriedades do fluxo de dados para exibir os parâmetros do sistema e definidos pelo usuário.
Designando um Parâmetro
Você pode designar parâmetros a diferentes tipos de recursos, como entidades de dados nos operadores de origem e destino, e condições nos operadores de filtro, junção e lookup.
Em um fluxo de dados, é possível selecionar entre os parâmetros existentes ou adicionar e depois designar um parâmetro.
Use a guia Detalhes do painel Propriedades de um operador de fluxo de dados para designar parâmetros. O procedimento a seguir pode ser usado para designar parâmetros aos operadores de origem, destino, filtro, junção e lookup.
Para designar um parâmetro para um operador em um fluxo de dados:
Editando um Parâmetro
Você edita o valor padrão de um parâmetro designado no fluxo de dados em que o parâmetro é usado.
Você também pode alterar o valor do parâmetro ao criar uma tarefa de integração usando o fluxo de dados ou ao executar a tarefa. O procedimento a seguir descreve como editar um valor de parâmetro ao projetar o fluxo de dados.
O procedimento a seguir não se aplica à edição de parâmetros de expressão em expressões ou condições.
Para editar um parâmetro designado:
Ao editar o parâmetro para um recurso de ativo de dados, conexão, esquema ou entidade de dados, certifique-se de manter os relacionamentos apropriados entre os valores. Por exemplo, se você alterar o valor do esquema, verifique se o novo valor do esquema contém a entidade de dados originalmente selecionada. Se o valor editado não conter a entidade de dados original, você corre o risco de encontrar erros com o fluxo de dados no runtime. O serviço Data Integration avisa sobre possíveis problemas, mas você é responsável por definir os valores apropriados para os parâmetros.
Removendo um Parâmetro
A remoção de um parâmetro de um operador só remove a associação do operador com o parâmetro.
O parâmetro não é excluído do fluxo de dados quando você remove um parâmetro. Você ainda pode usar o parâmetro para outro operador do mesmo tipo de recurso.
Quando você remove um parâmetro, o valor que foi designado ao parâmetro se torna o valor padrão do operador.
O procedimento a seguir não se aplica à remoção ou exclusão de parâmetros de expressão das expressões ou condições.
Para remover um parâmetro designado:
- Na tela de um fluxo de dados, selecione o operador cujo parâmetro você deseja remover.
- Na guia Detalhes do painel Propriedades, para o tipo do recurso de parâmetro que você deseja remover, selecione Remover parâmetro.
- Na caixa de diálogo Remover parâmetro, verifique a lista de operadores que serão afetados se você remover esse parâmetro e, em seguida, selecione Remover.
Excluindo um Parâmetro
Quando você exclui um parâmetro de um fluxo de dados, o parâmetro não fica mais disponível para uso no fluxo de dados.
Se o parâmetro excluído estiver associado a um operador no fluxo de dados, o valor designado ao parâmetro se tornará o valor padrão do operador.
Para excluir um parâmetro:
Adicionando um Parâmetro de Expressão
Você usa o Expression Builder ou o Condition Builder para adicionar parâmetros de expressão em um fluxo de dados.
Um parâmetro de expressão tem um nome, um tipo e um valor padrão. Somente o valor padrão pode ser alterado após a criação do parâmetro.
Para adicionar um parâmetro de expressão:
- Dependendo do operador selecionado, execute um dos seguintes procedimentos:
- Para um operador de expressão ou de agregação, selecione Adicionar expressão ou selecione Editar no menu Ações () de uma expressão existente,
- Para um operador de filtro, junção ou pesquisa, selecione Criar ou Editar.
- Para um operador de divisão, selecione Adicionar ou Editar no menu Ações () para uma condição existente.
- Para um operador de expressão ou de agregação, selecione Adicionar expressão ou selecione Editar no menu Ações (
Editando um Parâmetro de Expressão
Você só pode editar os valores padrão dos parâmetros de expressão. Não é possível modificar o nome, o tipo ou outras propriedades específicas do tipo de um parâmetro de expressão.
Você pode usar o painel Parâmetros ou a guia Parâmetros no painel Propriedades do fluxo de dados para editar os valores padrão.
O procedimento a seguir usa a guia Parâmetros no painel Propriedades do fluxo de dados.
-
Na linha do parâmetro de expressão que você deseja alterar, selecione Editar no menu Ações ().