Gerenciar macros, preferências e argumentos de execução

Esta página explica como definir preferências, macros e argumentos de execução em pipelines do Cloud Data Fusion.

Termos-chave

Macros
Macros são marcadores de posição nas configurações do plug-in do Cloud Data Fusion. Elas são representadas por variáveis incluídas em ${ }, como ${input_file_path}. As macros introduzem flexibilidade nos pipelines, permitindo o uso de valores de marcador de posição, que são substituídos por valores reais no tempo de execução. Isso ativa a configuração dinâmica para parâmetros, como caminhos de arquivo e nomes de tabelas.
Preferências
As preferências são configurações predefinidas que se aplicam em vários níveis no Cloud Data Fusion, incluindo o próprio sistema, namespaces, aplicativos (que contêm pipelines) e programas individuais em pipelines. As preferências permitem definir valores padrão para configurações usadas com frequência. Os padrões podem ser herdados por pipelines e programas em níveis mais baixos, reduzindo as tarefas de configuração repetitivas.
Argumentos de ambiente de execução
Os argumentos de execução são pares de chave-valor que fornecem valores para macros e podem substituir preferências quando você implanta ou executa um pipeline. Eles são altamente personalizáveis, permitindo ajustar as configurações de acordo com a execução do pipeline, sem modificar o pipeline ou as preferências subjacentes.

Configurar macros

Para usar uma macro para um valor de propriedade do plug-in, siga estas etapas:

  1. No Cloud Data Fusion Studio, acesse o nó do plug-in e clique em Propriedades.
  2. Acesse o campo em que você quer usar uma macro e clique no ícone de** M** ao lado do campo.
  3. Insira uma chave para a macro. Por exemplo, nas propriedades do plug-in da origem do arquivo, insira a seguinte chave no campo "Formato": ${format.type}.

Definir valores de macros

Defina valores para macros antes de visualizar os dados de um pipeline e antes de executá-lo. É possível definir valores de macro nos seguintes locais:

  • Plug-ins de definição de argumentos
  • Argumentos de ambiente de execução
  • Preferências do aplicativo
  • Preferências de namespace
  • Preferências do sistema

A execução de um pipeline com macros faz o seguinte:

  • O Cloud Data Fusion primeiro verifica se o pipeline inclui um plug-in de definição de argumento:
    • Se tiver um definidor de argumentos, o Cloud Data Fusion vai usar os valores das macros dele.
    • Se não houver um conjunto de argumentos ou se houver macros que não forem atribuídas no conjunto, o Cloud Data Fusion vai usar os valores nos argumentos de execução do pipeline.
  • Os argumentos de ambiente de execução herdam macros das preferências do aplicativo.
  • As preferências do aplicativo herdam macros das preferências do namespace
  • As preferências do namespace herdam macros das preferências do sistema.

Exemplos

Um uso comum de macros é em campos de caminho. Em vez de usar caminhos codificados, use caminhos dinâmicos. Por exemplo, em um plug-in de origem do Cloud Storage, é possível substituir o valor do caminho por várias macros. O valor a seguir divide os elementos de bucket, pasta e arquivo: gs://${bucket.name}/${folder}/${file.name}.

O exemplo a seguir carrega dados de um bucket estático e de um arquivo com um nome que não é estático. Insira o nome do bucket e use uma macro para o nome do arquivo: gs://<BUCKET_NAME>/${folder}/${file.name}.

Para mais informações, consulte Macros e funções de macro.

Configurar preferências

A seção a seguir descreve a hierarquia de preferências, em que as preferências são definidas, herdadas ou substituídas.

Definir preferências do sistema

É possível definir preferências para o sistema. Como os nomes de macros precisam ser exclusivos, cada preferência se aplica a todos os pipelines que usam essa macro.

Por exemplo, você tem um pipeline com uma origem de banco de dados e usa macros para o nome e o nome de usuário do banco de dados. É possível definir preferências de banco de dados e de usuário nas preferências do sistema. Todos os namespaces e pipelines nessa instância herdam essas preferências.

Para definir as preferências do sistema, siga estas etapas:

  1. No Cloud Data Fusion Studio, clique em Administrador do sistema > Configuração.
  2. Clique em Preferências do sistema > Editar preferências do sistema.
  3. Na caixa de diálogo Preferences, insira novas preferências ou edite as existentes.
  4. Clique em Salvar e fechar. Essas preferências estão disponíveis em todos os namespaces, aplicativos e pipelines.

Definir preferências de namespace

É possível definir preferências para namespaces individuais.

Quando você define as preferências do namespace, todas as preferências do sistema herdadas são mostradas. Ao definir preferências para um namespace, é possível substituir as preferências herdadas definindo valores diferentes. Também é possível adicionar novas preferências de namespace.

Para definir as preferências de namespace, siga estas etapas:

  1. No Cloud Data Fusion Studio, clique em Administrador do sistema > Configuração.
  2. Clique em Namespaces e selecione um namespace para abrir a página de configurações dele.
  3. Para editar as preferências herdadas ou adicionar novas, acesse a guia "Preferências" e clique em Editar. Uma caixa de diálogo Preferences será aberta para que você possa inserir uma nova preferência ou substituir as preferências herdadas do sistema. Clique em <span class="material-icons">add</span> Adicionar e digite a chave e o novo valor da macro.
  4. Clique em Salvar e fechar. A preferência de namespace é criada com o novo valor, que tem precedência sobre a preferência do sistema.

Definir preferências do app

É possível definir preferências para cada pipeline implantado em um namespace. Quando você define as preferências do aplicativo, todas as preferências de sistema e de namespace herdadas aparecem. Ao definir preferências para um aplicativo, é possível substituir as preferências herdadas definindo valores diferentes ou adicionar novas preferências para o aplicativo:

  1. No Cloud Data Fusion Studio, clique em e no menu Namespace para selecionar o namespace em que você quer adicionar as preferências do aplicativo.
  2. Clique em Central de controle.
  3. Clique no ícone de chave inglesa "Definir preferências". A página "Preferências" aparece e lista todas as preferências herdadas.
  4. Para editar as preferências herdadas ou adicionar novas, acesse a guia "Preferências" e clique em Editar. Uma caixa de diálogo Preferences será aberta para que você possa inserir uma nova preferência ou substituir as preferências herdadas do sistema. Clique em <span class="material-icons">add</span> Adicionar e digite a chave e o novo valor da macro.
  5. Clique em Salvar e fechar. A preferência do aplicativo é criada com o novo valor, que substitui as preferências do sistema ou do namespace. Quando você executa o pipeline implantado, as preferências do aplicativo aparecem como argumentos de tempo de execução, que podem ser editados.

Configurar argumentos de ambiente de execução

Configure argumentos de execução para fornecer valores para macros e, possivelmente, substitua preferências ao implantar ou executar um pipeline.

Argumentos de ambiente de execução para visualizar dados

Para definir os valores de cada macro no pipeline ao visualizar dados no Cloud Data Fusion Studio, clique em Lista > Configurar.

Argumentos de ambiente de execução para executar pipelines implantados

Se um pipeline incluir macros, depois de implantar um pipeline, adicione argumentos de execução, que definem os valores das macros.

Ao implantar um pipeline com macros, clique no menu suspenso ao lado de Run para abrir a caixa de diálogo Runtime arguments e definir os valores de cada macro.

Definir preferências do pipeline

Para definir preferências para um pipeline, siga estas etapas:

  1. No Cloud Data Fusion Studio, clique em List > Deployed e selecione um pipeline implantado para visualizá-lo.
  2. Na tela do pipeline, clique no menu suspenso ao lado de Run. A caixa de diálogo Argumentos de execução será aberta.
  3. Na caixa de diálogo Argumentos de execução que é aberta, especifique o valor de cada macro no pipeline.

Visão geral de preferências, macros e argumentos de execução

É possível definir preferências nos seguintes níveis:

  • Preferências do sistema: o nível mais alto em que você define preferências, como padrões, para toda a instância.
  • Preferências do namespace: herda as preferências das Preferências do sistema. É possível definir preferências para um namespace específico.
  • Preferências do aplicativo: herda as preferências das preferências do namespace. Eles podem ser exclusivos para aplicativos individuais (que contêm pipelines).
  • Argumentos do ambiente de execução: pares de chave-valor que substituem as preferências em níveis mais altos.

Se você definir uma preferência no nível das preferências do sistema, os valores da macro vão ser preenchidos automaticamente nas preferências de namespace, de aplicativo e nos argumentos de execução.

Se você definir preferências no nível do namespace, elas vão aparecer na lista de preferências herdadas nas preferências do aplicativo. Se um pipeline usa uma macro definida em uma preferência, os argumentos de execução usam o par de chave-valor definido na preferência. É possível substituir os valores de preferências em cada nível de preferência e nos argumentos de execução.

Use preferências, macros e argumentos de execução para os seguintes casos de uso:

  • Como desenvolver um pipeline. Incorpore macros onde você precisa de valores dinâmicos para propriedades de plug-in.
  • Opcional: definir preferências. Defina valores padrão para as macros nas preferências em vários níveis.
  • Implantar e executar um pipeline. Quando você executa um pipeline, o seguinte acontece:
    • As preferências do nível relevante, como preferências do sistema ou do namespace, são aplicadas.
    • Todos os argumentos de execução fornecidos substituem os valores atribuídos às macros nas preferências.
    • O Cloud Data Fusion resolve as macros substituindo os valores dos argumentos de execução (ou preferências, se um argumento de execução não for fornecido).

Exemplo

Um pipeline tem um coletor do BigQuery que tem um valor de nome de tabela que precisa mudar dinamicamente. Para configurar isso, faça o seguinte:

  1. Defina a macro. Nas propriedades do sink, use a seguinte macro no campo Nome da tabela: ${output_table}.
  2. **Defina a preferência. **Nas preferências do aplicativo, defina uma preferência para ${output_table} com o seguinte valor padrão: data_staging.
  3. Defina o argumento de execução. Ao executar o pipeline, forneça um argumento de execução, por exemplo, output_table=final_analytics_data.

Durante a execução do pipeline, a macro ${output_table}, é substituída por final_analytics_data.

A seguir