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

Nesta página, explicamos como configurar preferências, macros e argumentos de ambiente de execução nos pipelines do Cloud Data Fusion.

Termos-chave

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

Configurar macros

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

  1. No Studio do Cloud Data Fusion, acesse o nó do plug-in e clique em "Propriedades".
  2. Acesse o campo em que você quer usar uma macro e clique em** 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 macro

Defina valores para as macros antes de visualizar os dados de um pipeline e de executar um pipeline. É possível definir valores de macro nos seguintes locais:

  • Plug-ins do setter 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:

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

Exemplos

Um uso comum de macros é em campos de caminho. Em vez de caminhos codificados, você pode usar 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}.

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

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

Você pode definir preferências para o sistema. Como os nomes das macros precisam ser únicos, 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 as preferências de banco de dados e nome de usuário nas preferências do sistema. Cada namespace e pipeline na instância herda essas preferências.

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

  1. No Studio do Cloud Data Fusion, 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 Preferências, insira novas preferências ou edite as que já existem.
  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 preferências de namespace, todas as preferências herdadas do sistema são exibidas. Ao definir preferências para um namespace, é possível modificar as preferências herdadas configurando valores diferentes. Também é possível adicionar novas preferências de namespace.

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

  1. No Studio do Cloud Data Fusion, clique em Administrador do sistema > Configuração.
  2. Clique em Namespaces e selecione um namespace para abrir a página de configurações correspondente.
  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 é aberta, onde você pode inserir uma nova preferência ou substituir as preferências de sistema herdadas. Clique em <span class="material-icons">add</span> Adicionar e insira a chave e o novo valor para a 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 aplicativo

É possível definir preferências para cada pipeline implantado em um namespace. Ao definir as preferências do aplicativo, todas as preferências de sistema e namespace herdadas são exibidas. 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 Studio do Cloud Data Fusion, clique em e, depois, no menu Namespace para selecionar o namespace em que você quer adicionar preferências de 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 é aberta, onde você pode inserir uma nova preferência ou substituir as preferências de sistema herdadas. Clique em <span class="material-icons">add</span> Adicionar e insira a chave e o novo valor para a 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 de namespace. Quando você executa o pipeline implantado, as preferências do aplicativo aparecem como argumentos de ambiente de execução, que podem ser editados.

Configurar argumentos do ambiente de execução

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

Argumentos de ambiente de execução para visualização de dados

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

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

Se um pipeline incluir macros, depois de implantá-lo, adicione argumentos de ambiente de execução, que definem os valores das macros.

Ao implantar um pipeline com macros, clique no menu suspenso ao lado de Executar para abrir a caixa de diálogo Argumentos de ambiente de execução e definir os valores para cada macro.

Definir preferências de pipeline

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

  1. No Studio do Cloud Data Fusion, clique em Lista > Implantado 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 do ambiente de execução é aberta.
  3. Na caixa de diálogo Argumentos do ambiente de execução, especifique o valor de cada macro no pipeline.

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

É possível configurar as 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 de namespace: herda preferências das Preferências do sistema. É possível definir preferências para um namespace específico.
  • Preferências do aplicativo: herda preferências das preferências do namespace. Eles podem ser exclusivos para aplicativos individuais (contendo 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 de preferências do sistema, os valores da macro serão preenchidos automaticamente nas preferências de namespace, de aplicativo e argumentos de ambiente de execução.

Se você definir as preferências no nível do namespace, elas serão exibidas na lista de preferências herdadas nas preferências do aplicativo. Se um pipeline usar uma macro definida em uma preferência, os argumentos do ambiente de execução usarão 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 do ambiente de execução.

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

  • Como desenvolver um pipeline. Incorpore macros onde você precisar de valores dinâmicos para as propriedades do plug-in.
  • Opcional: como configurar preferências. Definir valores padrão para as macros nas preferências em vários níveis.
  • Como implantar e executar um pipeline. Quando você executa um pipeline, acontece o seguinte:
    • As preferências do nível relevante, como preferências do sistema ou de namespace, são aplicadas.
    • Todos os argumentos de ambiente de execução que você fornecer substituem os valores atribuídos às macros nas preferências.
    • O Cloud Data Fusion resolve as macros substituindo os valores correspondentes dos argumentos do ambiente de execução (ou preferências, caso um argumento desse tipo não seja fornecido).

Exemplo

Um pipeline tem um coletor do BigQuery que tem um valor de nome de tabela que precisa ser alterado dinamicamente. Para fazer essa configuração, faça o seguinte:

  1. Defina a macro. Nas propriedades do coletor, use a macro a seguir 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. Definir o argumento do ambiente de execução. Ao executar o pipeline, forneça um argumento de ambiente de execução, como output_table=final_analytics_data.

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