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

As macros, as preferências e os argumentos de ambiente de execução do Cloud Data Fusion permitem parametrizar pipelines de maneira dinâmica e criar modelos reutilizáveis. É possível estabelecer configurações padrão hierárquicas nos ambientes e substituir valores de configuração ao visualizar ou executar um pipeline.

Termos-chave

Macros
As macros são marcadores de posição nas configurações de plug-ins do Cloud Data Fusion. Eles são representados por variáveis entre ${ }, como ${input_file_path}. As macros introduzem flexibilidade nos pipelines, permitindo o uso de valores de marcador, que são substituídos por valores reais no ambiente de execução. Isso permite a configuração dinâmica de parâmetros, como caminhos de arquivo 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 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 do ambiente de execução
Os argumentos de ambiente de execução são pares de chave-valor que fornecem valores para macros e podem substituir preferências ao implantar ou executar um pipeline. Eles são altamente personalizáveis, permitindo que você ajuste as configurações por execução de pipeline, sem modificar o pipeline ou as preferências subjacentes.

Configurar macros

Para usar uma macro em um valor de propriedade de 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 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 macro

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

  • Plug-ins do Argument Setter
  • Argumentos do 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 houver um definidor de argumentos, o Cloud Data Fusion vai usar os valores das macros dele.
    • Se não houver um definidor de argumentos ou se houver macros que não foram atribuídas no definidor de argumentos, o Cloud Data Fusion usará os valores nos argumentos do ambiente 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 de namespace herdam macros das preferências do sistema.

Exemplos

Um uso comum de macros é em campos de caminho. Em vez de usar 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}.

O exemplo a seguir carrega dados de um bucket estático e um arquivo com um nome que não é estático. Insira o nome do bucket e use uma macro para o nome de 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 modificadas.

Definir preferências do sistema

Você pode definir as preferências do sistema. Como os nomes de macro 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 do banco de dados e o nome de usuário. É possível definir as preferências de banco de dados e nome de usuário nas preferências do sistema. Cada namespace e cada pipeline nessa instância herda 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 Preferências, insira novas preferências ou edite as atuais.
  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 de namespace, todas as preferências do sistema herdadas são exibidas. 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.
  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, em que você poderá inserir uma nova preferência ou substituir as preferências do sistema herdadas. Clique em Adicionar e insira 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 aplicativo

É possível definir preferências para cada pipeline implantado em um namespace. Quando você define as preferências do aplicativo, todas as preferências herdadas do sistema e do namespace são exibidas. Ao definir as preferências de 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. Uma lista de todas as preferências herdadas é exibida.
  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, em que você poderá inserir uma nova preferência ou substituir as preferências do sistema herdadas. Clique em Adicionar e insira 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 ambiente de execução, que podem ser editados.

Configurar argumentos de ambiente de execução

Configure argumentos de ambiente de execução para fornecer valores para macros e, possivelmente, substituir 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 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 de cada macro.

Definir preferências de pipeline

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

  1. No Cloud Data Fusion Studio, clique em Lista > Implantado e selecione um pipeline implantado para visualizá-lo.
  2. Na tela do pipeline, clique no menu suspenso ao lado de Executar. A caixa de diálogo Argumentos de ambiente de execução será aberta.
  3. Na caixa de diálogo Argumentos de ambiente de execução que é aberta, 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 as preferências do sistema . É possível definir preferências para um namespace específico.
  • Preferências do aplicativo: herda as preferências de Preferências de namespace. Eles podem ser exclusivos para aplicativos individuais (que contêm pipelines).
  • Argumentos de 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 de macro vão preencher automaticamente as preferências de namespace, as preferências do aplicativo e os argumentos de ambiente 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 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 das preferências em cada nível de preferência e nos argumentos de 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ê 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.
  • Como implantar e executar um pipeline. Quando você executa um pipeline, acontece o seguinte:
    • As preferências do nível relevante, como as preferências do sistema ou do namespace, são aplicadas.
    • Todos os argumentos de ambiente de execução fornecidos substituem os valores atribuídos às macros nas preferências.
    • O Cloud Data Fusion resolve as macros substituindo os valores delas pelos argumentos de ambiente de execução (ou preferências, se um argumento de ambiente de execução não for fornecido).

Exemplo

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

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