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

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

Termos-chave

Macros
As macros são marcadores de posição nas configurações de plug-in do Cloud Data Fusion. Elas são representadas por variáveis entre ${ }, como ${input_file_path}. As macros trazem flexibilidade aos seus pipelines, permitindo que você use valores de marcador, que são substituídos por valores reais no tempo de execução. Isso permite 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 em pipelines. Com as preferências, é possível 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 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 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 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 dele.
  3. Insira uma chave para a macro. Por exemplo, nas propriedades do plug-in da origem de arquivo, insira a seguinte chave no campo "Formato": ${format.type}.

Definir valores de macro

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

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

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

  • Primeiro, o Cloud Data Fusion verifica se o pipeline inclui um plug-in setter de argumentos:
    • Se ele tiver um setter de argumentos, o Cloud Data Fusion usará os valores das macros dele.
    • Se não houver um conjunto de argumentos ou se houver macros que não foram atribuídas no conjunto, o Cloud Data Fusion usará os valores nos argumentos de tempo 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 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.

Definir preferências

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

Definir preferências do sistema

Você pode 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 nome 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 Preferências, insira ou edite as preferências.
  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 de 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 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 Preferências será aberta. Nela, você pode inserir uma nova preferência ou substituir as preferências herdadas do sistema. 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 de aplicativos

É possível definir preferências para cada pipeline implantado em um namespace. Quando você define preferências de aplicativo, todas as preferências herdadas do sistema e do namespace aparecem. Ao definir preferências para um aplicativo, é possível substituir as 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 preferências de aplicativo.
  2. Clique em Central de controle.
  3. Clique no ícone de chave Definir preferências. Uma lista de todas as preferências herdadas vai aparecer.
  4. Para editar as preferências herdadas ou adicionar novas, acesse a guia "Preferências" e clique em Editar. Uma caixa de diálogo Preferências será aberta. Nela, você pode inserir uma nova preferência ou substituir as preferências herdadas do sistema. 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 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 visualização de dados

Para definir os valores de cada macro no pipeline ao visualizar os 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 tempo 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 do ambiente de execução e definir os valores de cada macro.

Definir preferências de pipeline

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

  1. No Cloud Data Fusion Studio, clique em Lista > Implantado e selecione um pipeline implantado para conferir.
  2. Na tela do pipeline, clique no menu suspenso ao lado de Executar. A caixa de diálogo Argumentos de execução será aberta.
  3. Na caixa de diálogo Argumentos de ambiente de execução que aparece, especifique o valor de cada macro no pipeline.

Visão geral de preferências, macros e argumentos de ambiente 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 de namespace: herda preferências de 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. Elas podem ser exclusivas de aplicativos individuais (que contêm pipelines).
  • Argumentos 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 serão preenchidos automaticamente nas preferências de namespace, nas preferências de aplicativo e nos 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 de execução vão usar o par 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 tempo de execução.

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

  • 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, acontece o seguinte:
    • As preferências do nível relevante, como preferências do sistema ou do namespace, são aplicadas.
    • Todos os argumentos de tempo 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 execução (ou preferências, se um argumento 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 gravador, 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 tempo de execução. Ao executar o pipeline, forneça um argumento de tempo 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