Criar e usar parâmetros em fluxos

Com suporte no Tableau Prep Builder versão 2021.4.1 e posterior e na Web no Tableau Cloud e Tableau Server versão 2021.4.0 e posterior.

Observação: o conteúdo deste tópico se aplica aos fluxos de criação no Tableau Prep Builder e na Web, a menos que seja especificamente indicado. Para obter mais informações sobre os fluxos de criação na Web, consulte Tableau Prep na Web na ajuda do Tableau Server(O link abre em nova janela) e Tableau Cloud(O link abre em nova janela).

Se você costuma reutilizar fluxos usando dados diferentes com o mesmo esquema, pode criar e aplicar parâmetros de usuário a seus fluxos para fazer a transição facilmente entre cenários. Um parâmetro é um valor de espaço reservado global, como um número, valor de texto ou valor booleano que pode substituir um valor constante em um fluxo.

Em vez de criar e manter vários fluxos, agora você pode criar um fluxo e usar parâmetros para executá-lo com diferentes conjuntos de dados. Por exemplo, você pode criar um parâmetro para várias regiões de vendas e, em seguida, aplicar um valor de parâmetro ao caminho do arquivo de entrada para executar o fluxo usando apenas os dados dessa região.

A partir do Tableau Prep Builder e do Tableau Cloud versão 2023.2, você também pode adicionar parâmetros de sistema ao arquivo ou ao nome de saída da fonte de dados publicada para adicionar automaticamente um carimbo de data/hora sempre que executar o fluxo.

Onde posso aplicar os parâmetros?

Você pode aplicar parâmetros de usuário a nomes de arquivos, caminhos, nomes de tabelas, expressões de filtro e campos calculados, dependendo do tipo de etapa. A partir da versão 2022.1.1, você pode até incluir valores de substituição de parâmetro ao executar fluxos usando a API REST. Para obter mais informações, consulte Métodos de fluxo(O link abre em nova janela) na Ajuda da API REST do Tableau Server.

Você pode aplicar parâmetros de sistema (versão 2023.2 e posterior) a nomes de saída para tipos de saída de arquivo e de fonte de dados publicada.

A tabela a seguir lista os locais onde você pode aplicar parâmetros para cada tipo de etapa.

Tipo de etapaLocalização do parâmetro
Entrada

Parâmetros do usuário:

  • Conectar ao arquivo: use parâmetros no nome do arquivo ou no caminho do arquivo
  • Conectar ao banco de dados: use parâmetros para o nome da tabela e no SQL personalizado
  • Editor de expressão: filtros
Saída

Parâmetros do usuário ou do sistema:

  • Saída para arquivo: aplique parâmetros de usuário ao nome do arquivo ou ao caminho do arquivo e, a partir da versão 2022.1.1, ao nome da planilha do Microsoft Excel. Aplique os parâmetros de sistema ao nome de arquivo.
  • Saída para servidor: aplique parâmetros de usuário ou de sistema ao nome da fonte de dados publicada
  • Saída para banco de dados: aplique parâmetros de usuário ao nome da tabela e, a partir da versão 2022.1.1, a scripts SQL executados antes ou depois de gravar a saída do fluxo em um banco de dados.
Limpeza, novas linhas, dinamização, união de colunas, união de linhas

Parâmetros do usuário:

  • Editor de expressão: filtros e valores de campo calculados
Agregação

Parâmetros do usuário:

  • Editor de expressão: filtros
Script

Parâmetros do usuário:

  • Editor de expressão: filtros e valores de campo calculados
Previsão

Parâmetros do usuário:

  • Editor de expressão: filtros e valores de campo calculados

 

Criar parâmetros de usuário

Os parâmetros de usuário são específicos para o fluxo onde são usados. Crie parâmetros no menu superior e defina os valores que se aplicam a eles. Você também pode definir parâmetros que aceitam todos os valores, o que significa que qualquer usuário de fluxo pode inserir qualquer valor ao executar o fluxo.

Você pode tornar os valores de parâmetro de fluxo obrigatórios ou opcionais. Ao executar o fluxo, os usuários são solicitados a inserir os valores dos parâmetros. Os valores de parâmetro obrigatórios devem ser inseridos antes que o usuário possa executar o fluxo. Valores de parâmetros opcionais podem ser inseridos ou você pode aceitar o valor atual (padrão). Os valores de parâmetro são então aplicados ao fluxo executado em todos os lugares em que esse parâmetro é usado.

Observação: para executar ou programar fluxos que incluem parâmetros no Tableau Server ou Tableau Cloud, o administrador deve habilitar as configurações de parâmetro de fluxo no servidor. Para obter mais informações, consulte Criar e interagir com fluxos na Web na ajuda do Tableau Server(O link abre em nova janela) ou Tableau Cloud(O link abre em nova janela)

  1. No menu superior, clique no ícone de parâmetro e em Criar parâmetro .

  2. Na caixa de diálogo Criar parâmetro, insira um nome e uma descrição (opcional). O nome do parâmetro deve ser exclusivo. Este é o valor mostrado na interface do usuário quando você adiciona um parâmetro.

    Se você incluir uma descrição, os usuários poderão ver essas informações ao passar o mouse (a partir da versão 2022.1.1) na lista de parâmetros e onde os parâmetros são usados.

  3. Selecione um dos tipos de dados a seguir. Os valores dos parâmetros devem corresponder ao tipo de dados selecionado.

    • Número (inteiro ou decimal)
    • Cadeia de caracteres
    • Booleano
  4. Especifique os valores permitidos. Esses são os valores que os usuários podem inserir no parâmetro.

    • Todos: esta opção permite que os usuários digitem qualquer valor para o parâmetro, mesmo durante a execução do fluxo.

      Observação: usar esta opção para parâmetros que podem ser usados nas etapas de entrada e saída pode ser um risco à segurança. Por exemplo, consultas SQL personalizadas que permitem a inserção de qualquer valor podem expor seus ativos de dados a ataques de injeção de SQL.

    • Lista: insira uma lista de valores que os usuários podem escolher ao aplicar o parâmetro. Para inserir vários valores, pressione Enter após cada entrada.
  5. (opcional) Selecione Exigir seleção em tempo de execução (solicitar valor em tempo de execução em versões anteriores). Isso torna o parâmetro obrigatório. O usuário deve inserir um valor ao executar ou programar o fluxo.
  6. Insira um valor atual. Esse é um valor obrigatório e atua como um valor padrão para o parâmetro.

    • Todos: insira um valor
    • Lista: o Tableau usa o primeiro valor da sua lista. Use a opção suspensa para alterá-lo.
    • Booleano: selecione Verdadeiro ou Falso.
  7. Clique em OK para salvar o parâmetro.

Alterar o valor padrão do parâmetro de usuário

Ao criar usuário um parâmetro de usuário, você deve especificar um valor atual (padrão). Se um parâmetro for incluído em um fluxo, esse valor será usado para:

  • Execute consultas de SQL personalizado definidas em uma etapa de entrada.
  • Preencha os parâmetros opcionais que não são especificados em tempo de execução.
  • Substitua o parâmetro como um valor estático nas etapas salvas (versão 2022.1.1 e posterior).
  • Substitua o parâmetro como um valor estático em caminhos de arquivo ao publicar fluxos com conjuntos de dados compactados.

Você pode alterar o valor a qualquer momento. No menu superior, você pode editar o parâmetro ou usar o botão Definir na lista de parâmetros. De dentro do fluxo, você pode usar o botão Definir em qualquer lugar em que o parâmetro seja aplicado. Ao fazer isso, ele redefine o valor atual (padrão) do parâmetro em todos os lugares em que o parâmetro é usado, mesmo em consultas de SQL personalizado.

Editar parâmetros de usuário

  1. No menu superior, clique no ícone de parâmetro.
  2. Clique em Editar parâmetro.
  3. Na caixa de diálogo Editar parâmetro, faça as alterações e clique em OK.

Redefinir valores padrão do parâmetro de usuário

Para redefinir rapidamente o valor padrão do parâmetro, use o botão Definir. O botão mostra uma contagem indicando o número de lugares no fluxo onde o parâmetro é usado.

Para destacar as etapas no fluxo que usam o parâmetro, clique em Visualizar no fluxo na caixa de diálogo do parâmetro. Se houver apenas um local onde o parâmetro é usado, você será levado diretamente para essa etapa com o painel de perfil aberto.

  1. Execute um destes procedimentos:
    • No menu superior, clique no ícone de parâmetro. Use esta opção para redefinir valores de parâmetros usados em qualquer lugar no fluxo ou quando usados em filtros e campos calculados.

    • Clique no parâmetro onde ele é aplicado no fluxo. Você pode usar essa opção para parâmetros usados em nomes de arquivos, caminhos de arquivos, nomes de tabelas, SQL personalizado e scripts SQL anteriores e posteriores.

  2. Selecione ou insira o valor do parâmetro.
  3. Clique em Definir para aplicar as alterações.

Aplicar parâmetros ao seu fluxo

Depois de criar os parâmetros de usuário, você pode aplicá-los a vários lugares em todo o seu fluxo, dependendo do tipo de etapa. Quando o fluxo é executado, os valores de parâmetro são aplicados a essa execução de fluxo para produzir a saída para o cenário de dados específico.

Os parâmetros do sistema (versão 2023.2 e posterior) são gerados automaticamente quando você executa o fluxo. Basta aplicá-los ao nome da etapa de saída e toda vez que o fluxo for executado; o parâmetro será atualizado dinamicamente com a data ou hora de início da execução do fluxo.

Aplicar parâmetros às etapas de entrada

Em uma etapa de entrada, você pode usar parâmetros de usuário para substituir um nome de arquivo, seções do caminho de arquivo, um nome de tabela de banco de dados ou ao usar o SQL personalizado.

Nome do arquivo ou caminho do arquivo

Esta opção não está disponível ao editar ou criar fluxos na Web.

Você pode incluir parâmetros de usuário no caminho do arquivo com algumas exceções. A partir da versão 2022.1.1, você também pode ver uma visualização dos valores dos parâmetros.

Exceções

  • A partir da versão 2022.1.1, você pode agendar e executar fluxos na Web que incluem parâmetros no caminho do arquivo de entrada. Se estiver usando uma versão anterior, execute fluxos no Tableau Prep Builder ou na linha de comando.
  • Para incluir parâmetros no caminho do arquivo ao publicar fluxos na Web, é necessária uma conexão direta de arquivo. Caso contrário, o parâmetro é convertido em um valor estático usando o Valor atual.

    Observação: as conexões diretas de arquivos exigem que os locais dos arquivos sejam incluídos na lista segura de sua organização. Para obter mais informações, consulte Locais de entrada e saída da lista de segurança(O link abre em nova janela) na ajuda do Tableau Server.

Aplicar um parâmetro de usuário a um nome de arquivo ou caminho

  1. Na guia Configurações, no caminho do arquivo, coloque o cursor no local onde deseja adicionar o parâmetro.
  2. Clique no ícone do parâmetro e selecione o parâmetro a aplicar.

  3. Veja uma visualização do valor do parâmetro. O valor atual (padrão) é mostrado na visualização. Você será solicitado a selecionar ou inserir o valor do parâmetro ao executar o fluxo.

Tabela de banco de dados

Ao usar parâmetros de usuário em nomes de tabelas, todo o nome da tabela deve ser o parâmetro. O uso de parâmetros para partes de um nome de tabela não é suportado atualmente.

Observação: o uso de um parâmetro para um nome de tabela em uma conexão de entrada do Google BigQuery ainda não é compatível.

  1. Na guia Configurações, no campo Tabela, clique no menu suspenso.
  2. Selecione Usar parâmetro e, em seguida, selecione o parâmetro na lista.

SQL personalizado

  1. No painel Conexões, clique em SQL personalizado.
  2. Na guia SQL personalizado, digite ou cole a consulta na caixa de texto.

  3. Clique no ícone do parâmetro e selecione o parâmetro a aplicar.

  4. Clique em Executar para executar sua consulta. Você não será solicitado a inserir um valor de parâmetro até executar o fluxo. Em vez disso, a consulta será executada inicialmente usando o Valor atual do parâmetro.

    Observação: se o parâmetro for usado em outro lugar no fluxo e o Valor atual for redefinido, essa alteração poderá afetar sua consulta.

Aplicar parâmetros de usuário às etapas de saída

Em uma etapa de saída, você pode aplicar parâmetros de usuário aos seguintes locais:

  • Nome do arquivo
  • Seções do caminho do seu arquivo
  • Nome da fonte de dados publicada
  • Nome da tabela de banco de dados
  • Nome da planilha do Microsoft Excel (versão 2022.1.1 e posterior)
  • Scripts SQL personalizados executados antes ou depois de gravar dados de saída de fluxo em um banco de dados (versão 2022.1.1 e posterior)

Nome do arquivo ou caminho do arquivo

Essa opção de saída não está disponível ao criar ou editar fluxos na web

  1. No painel Saída, selecione Arquivo na lista suspensa Salvar saída em.
  2. No campo Nome ou Local, clique no ícone de parâmetro e selecione seu parâmetro.

    Para o caminho do arquivo, coloque o cursor no local onde deseja adicionar o parâmetro.

    Ao executar o fluxo, você será solicitado a inserir seus valores de parâmetro.

Nome da fonte de dados publicada

  1. No painel Saída, na lista suspensa Salvar saída em, selecione Fonte de dados publicada.
  2. No campo Nome, clique no ícone do parâmetro e selecione seu parâmetro.

    Ao executar o fluxo, você será solicitado a inserir seus valores de parâmetro.

Tabela de banco de dados e antes e depois do SQL personalizado

  1. Na guia Saída, na lista suspensa Salvar saída em, selecione Tabela de banco de dados.
  2. No campo Tabela, selecione Usar parâmetro e, em seguida, selecione o parâmetro na lista.

  3. (Opcional) Clique na guia SQL personalizado. A partir da versão 2022.1.1, você pode inserir um script SQL com parâmetros para executar Antes e Depois que os dados forem gravados na tabela. Para incluir um parâmetro, clique em Inserir parâmetro e selecione seu parâmetro.

    Para obter mais informações sobre como usar scripts SQL ao gravar a saída em um banco de dados, consulte Salvar dados de saída de fluxo em bancos de dados externos.

    Observação: os parâmetros usados em scripts SQL devem ser excluídos manualmente. Consulte Excluir parâmetros de usuário manualmente para obter mais informações.

    Ao executar o fluxo, você será solicitado a inserir seus valores de parâmetro.

Aplicar parâmetros de sistema às etapas de saída

Em uma etapa de saída, você pode aplicar parâmetros do sistema de data e hora aos seguintes locais:

  • Nome do arquivo
  • Nome da fonte de dados publicada

Nome do arquivo

Essa opção de saída não está disponível ao criar ou editar fluxos na web

  1. No painel Saída, selecione Arquivo na lista suspensa Salvar saída em.
  2. No campo Nome, clique no ícone de parâmetro e selecione um dos parâmetros de data de execução ou hora de execução a seguir. Você pode combinar vários parâmetros do sistema para criar qualquer carimbo de data/hora necessário.

    Data de execução

    • Data: AAAA-MM-DD, AAMMDD, DD-MM-AAAA
    • Mês: nome do mês, número do mês
    • Número da semana
    • Número do trimestre
    • Número do ano

    Hora de execução

    • AAAA-MM-DD_HH-MM-SS (24 horas)
    • AAAAMMDD_HHMMSS (24 horas)

    Quando você executa o fluxo, o Tableau Prep aplica a hora de execução inicial do fluxo usando seu fuso horário local ou o fuso horário do servidor.

Nome da fonte de dados publicada

  1. No painel Saída, na lista suspensa Salvar saída em, selecione Fonte de dados publicada.
  2. No campo Nome, clique no ícone de parâmetro e selecione um dos parâmetros de data de execução ou hora de execução a seguir. Você pode combinar vários parâmetros do sistema para criar qualquer carimbo de data/hora necessário.

    Data de execução

    • Data: AAAA-MM-DD, AAMMDD, DD-MM-AAAA
    • Mês: nome do mês, número do mês
    • Número da semana
    • Número do trimestre
    • Número do ano

    Hora de execução

    • AAAA-MM-DD_HH-MM-SS (24 horas)
    • AAAAMMDD_HHMMSS (24 horas)

    Quando você executa o fluxo, o Tableau Prep aplica a hora de execução inicial do fluxo usando seu fuso horário local ou o fuso horário do servidor.

Aplicar parâmetros de usuário para filtrar cálculos

Use parâmetros de usuário para filtrar dados em todo o fluxo. Filtre seu conjunto de dados na etapa de entrada ou aplique parâmetros de filtro no nível de valor da etapa ou do campo. Por exemplo, use um parâmetro de filtro para inserir dados apenas para uma região específica ou filtrar dados em uma etapa para um departamento específico.

Observação: a partir da versão 2022.1, você pode usar copiar e colar para reutilizar cálculos de filtro com parâmetros em outros fluxos quando houver o mesmo parâmetro com o mesmo nome e tipo de dados.

  1. Na etapa Entrada ou na barra de ferramentas, no painel Perfil, clique em Filtrar valores. Para adicionar um filtro de parâmetro a um campo, no menu de opções Mais selecione Filtros > Cálculo.
  2. No editor de cálculo Adicionar Filtro, digite o nome do parâmetro para selecioná-lo na lista (o parâmetro é mostrado em roxo) e clique em Salvar para salvar o filtro.

    Ao executar o fluxo, você será solicitado a inserir seus valores de parâmetro.

Aplicar parâmetros de usuário aos campos calculados

Use parâmetros de usuário para substituir valores constantes em cálculos que você usa em todo o fluxo. Você pode aplicar parâmetros de cálculo no nível da etapa ou do valor do campo.

Observação: a partir da versão 2022.1, você pode usar copiar e colar para reutilizar cálculos com parâmetros em outros fluxos quando houver o mesmo parâmetro com o mesmo nome e tipo de dados.

  1. Na barra de ferramentas no painel de perfil, clique em Criar campo calculado. Para adicionar um parâmetro a um cálculo em um campo, no menu de opções Mais, selecione Criar campo calculado > Cálculo personalizado.
  2. No editor de cálculo Adicionar campo, insira nosso cálculo, digite o nome do parâmetro para selecioná-lo na lista e clique em Salvar para salvar seu cálculo.

    Ao executar o fluxo, você será solicitado a inserir seus valores de parâmetro.

Excluir parâmetros de usuário

Para excluir parâmetros de usuário que você não precisa mais, clique em Excluir parâmetro na caixa de diálogo Editar parâmetro. Isso remove qualquer instância do parâmetro usado em todo o fluxo e a substitui pelo Valor atual do parâmetro. Essa ação não pode ser desfeita.

Observação: as opções para excluir parâmetros em um fluxo variam de acordo com sua versão. Use as instruções abaixo para a versão 2022.1 e posterior. Use Excluir parâmetros de usuário manualmente para versões anteriores e para excluir parâmetros usados em scripts de SQL personalizados executados antes ou depois de gravar a saída em um banco de dados.

  1. No menu superior, clique no menu suspenso do ícone do parâmetro e clique em Editar parâmetro para o parâmetro que deseja excluir.
  2. Na caixa de diálogo Editar parâmetro, clique em Excluir parâmetro.

  3. Na caixa de diálogo de confirmação, selecione Excluir parâmetro novamente. Você pode clicar em Exibir no fluxo para destacar as etapas e investigar onde o parâmetro é usado antes de excluí-lo.

Excluir parâmetros de usuário manualmente

Aplica-se à versão 2021.4.4 e anterior e aos parâmetros usados em scripts do SQL personalizado anteriores e posteriores

Para excluir um parâmetro de usuário da sua lista de parâmetros, primeiro localize e remova todas as instâncias dos parâmetros do seu fluxo, mesmo do painel Alterações.

  1. No menu superior, clique no menu suspenso do ícone do parâmetro .
  2. Para o parâmetro que deseja excluir, clique em Visualizar no fluxo para localizar todas as instâncias em que o parâmetro é usado no fluxo.

    Se o parâmetro não for usado em nenhum lugar do fluxo, pule para a etapa 4.

  3. Para cada etapa em que o parâmetro é usado, remova o parâmetro, incluindo a exclusão de quaisquer alterações listadas no painel Alterações.
  4. No menu superior, clique no menu suspenso do ícone de parâmetro e para o parâmetro que deseja excluir, clique em Editar parâmetro.
  5. Na caixa de diálogo Editar parâmetro, clique em Excluir parâmetro.

    O parâmetro será substituído pelo Valor atual do parâmetro.

Executar fluxos com parâmetros

Fluxos em execução que incluem parâmetros são iguais aos fluxos em execução que não os têm, exceto que os usuários são solicitados a inserir valores de parâmetros de usuário em tempo de execução ou ao adicionar o fluxo a uma agenda no Tableau Server ou Tableau Cloud.

Os parâmetros do sistema são aplicados automaticamente quando o fluxo é executado.

Se um parâmetro de usuário for marcado como obrigatório, os usuários deverão inserir um valor para que possam executar o fluxo. Se um parâmetro for opcional, os usuários poderão inserir um valor ou aceitar o Valor atual do parâmetro por padrão.

Os parâmetros obrigatórios são aqueles que têm a caixa de seleção Exigir seleção em tempo de execução (Solicitar valor em tempo de execução em liberações anteriores) marcada.

Se você executar fluxos usando a interface de linha de comando e desejar substituir os valores de parâmetro atuais (padrão), crie um arquivo de substituição de parâmetros .json e inclua a sintaxe -p --parameters na linha de comando. Para obter mais informações, consulte Atualizar arquivos de saída de fluxo a partir da linha de comando.

Executar fluxos manualmente

Quando você executa um fluxo do Tableau Prep Builder ou manualmente no Tableau Server ou Tableau Cloud, a caixa de diálogos Parâmetros é aberta quando você clica em Executar.

  1. Insira ou selecione os valores de parâmetro de usuário. Se houver parâmetros opcionais no fluxo, você poderá inserir os valores neste momento ou aceitar o valor do parâmetro atual (padrão).
  2. Clique em Executar fluxo para executar o fluxo.

Para obter mais informações sobre a execução de fluxos, consulte Publicar um fluxo no Tableau Server ou Tableau Cloud.

Executar fluxos em um cronograma

Quando você agendar fluxos para execução no Tableau Server ou no Tableau Cloud, precisará inserir todos os valores de parâmetro de usuário necessários ao agendar os fluxos.

  1. Na guia Novas Tarefas ou Tarefas Vinculadas, na seção Definir Parâmetros, insira ou selecione os valores dos parâmetros. Se houver parâmetros opcionais no fluxo, você pode inserir os valores neste momento ou deixar o campo vazio para usar o valor do parâmetro atual (padrão).

  2. Clique em Criar tarefas para agendar o fluxo.
Agradecemos seu feedback!Seu feedback foi enviado. Obrigado!