Parâmetros de relatório no Construtor de Relatórios do Power BI

APLICA-SE A: Power BI Report Builder Power BI Desktop

Este artigo descreve os usos comuns de parâmetros de relatório do Power BI Report Builder, as propriedades que podem ser definidas, entre outros. Os parâmetros de relatório permitem a você controlar dados do relatório, conectar relatórios relacionados e variar a apresentação do relatório. Use parâmetros de relatório em relatórios paginados criados no Construtor de Relatórios.

Usos comuns de parâmetros

Estas são as formas mais comuns de usar parâmetros.

Controlar os dados de relatório paginado:

• Filtre dados de relatório paginado na fonte de dados escrevendo consultas de conjunto de dados que contenham variáveis.

• Permita que os usuários especifiquem valores para personalizar os dados em um relatório paginado. Por exemplo, forneça dois parâmetros para a data de início e data de término em dados de vendas.

Variar a apresentação do relatório:

• Permita que os usuários especifiquem valores para ajudar a personalizar a aparência de um relatório. Por exemplo, forneça um parâmetro booliano para indicar se é para expandir ou recolher todos os grupos de linhas aninhados em uma tabela.

• Permita que usuários personalizem os dados de relatório e a aparência incluindo parâmetros em uma expressão.

Exibir um relatório com parâmetros

Ao ver um relatório que tem parâmetros, a barra de ferramentas do visualizador de relatórios exibe cada parâmetro de forma que você possa especificar valores de maneira interativa. A ilustração a seguir mostra a área de parâmetro de um relatório com os parâmetros @ReportMonth, @ReportYear, @EmployeeID, @ShowAll, @ExpandTableRows, @CategoryQuota e @SalesDate.

1. Painel Parâmetros. A barra de ferramentas do visualizador de relatórios exibe um prompt e um valor padrão para cada parâmetro. Você pode personalizar o layout dos parâmetros no painel de parâmetros.

2. Parâmetro @SalesDate. O parâmetro @SalesDate é do tipo de dados DateTime. O prompt Selecione a Data é exibido ao lado da caixa de texto. Para modificar a data, digite uma nova data na caixa de texto ou use o controle de calendário ou selecione Ir para hoje.

3. Parâmetro @ShowAll. O parâmetro @ShowAll é do tipo de dados Booliano. Use os botões de opção para especificar True ou False.

4. Identificador Mostrar ou Ocultar Área de Parâmetros. Na barra de ferramentas do visualizador de relatórios, selecione esta seta para mostrar ou ocultar o painel de parâmetros.

5. Parâmetro @CategoryQuota. O parâmetro @CategoryQuota é do tipo de dados Float e, portanto, ele usa um valor numérico. @CategoryQuota é definido para permitir vários valores.

6. Exibir Relatório. Depois de inserir valores de parâmetro, clique em Exibir Relatório para executar o relatório. Se todos os parâmetros tiverem valores padrão, o relatório será executado automaticamente na primeira exibição.

Veja como seus clientes interagem com parâmetros em seus relatórios paginados no artigo Exibir parâmetros para relatórios paginados no serviço do Power BI.

Criar parâmetros

Você pode criar parâmetros de relatório de algumas maneiras diferentes.

Observação

Nem todas as fontes de dados oferecem suporte a parâmetros.

Consulta de conjunto de dados ou procedimento armazenado com parâmetros

Adicionar uma consulta de conjunto de dados que contenha variáveis ou um procedimento armazenado de banco de dados que contenha parâmetros de entrada. Um parâmetro de conjunto de dados é criado para cada variável ou parâmetro de entrada e um parâmetro de relatório é criado para cada parâmetro de conjunto de dados.

Esta imagem do Construtor de Relatórios mostra:

1. Os parâmetros do relatório no painel Dados do Relatório.

2. O conjunto de dados com os parâmetros.

3. O painel Parâmetros.

4. Os parâmetros listados na caixa de diálogo Propriedades do Conjunto de Dados.

Criar um parâmetro manualmente

Crie um parâmetro manualmente por meio do painel Dados do Relatório. É possível configurar os parâmetros de relatório de forma que um usuário possa inserir valores interativamente para ajudar a personalizar o conteúdo ou a aparência de um relatório. Você também pode configurar parâmetros de relatório de forma que um usuário não possa alterar os valores pré-configurados.

Observação

Como os parâmetros são gerenciados de maneira independente no servidor, a nova publicação de um relatório principal com novas configurações de parâmetros não substitui as configurações de parâmetro existentes no relatório.

Selecionar valores do parâmetro

As opções a seguir são para selecionar valores de parâmetro no relatório.

• Selecione um valor de parâmetro único da lista suspensa.

• Selecione vários valores de parâmetro da lista suspensa.

• Selecione um valor da lista suspensa para um parâmetro, o qual determina os valores que estão disponíveis na lista suspensa para outro parâmetro. Esses são parâmetros em cascata. Parâmetros em cascata permitem que você filtre milhares de valores de parâmetro sucessivamente para obter um número gerenciável. Confira mais informações em Usar parâmetros em cascata nos relatórios paginados.

• Execute o relatório sem precisar primeiro selecionar um valor de parâmetro porque um valor padrão foi criado para o parâmetro.

Propriedades de parâmetros de relatório

Altere as propriedades de parâmetro de relatório usando a caixa de diálogo Propriedades do Relatório. A tabela a seguir resume as propriedades que você pode definir para cada parâmetro:

Propriedade	Descrição
Nome	Digite um nome com diferenciação de maiúsculas e minúsculas para o parâmetro. O nome precisa começar com uma letra e pode conter letras, números e um sublinhado (_). O nome não pode conter espaços. Para parâmetros gerados automaticamente, o nome corresponde ao parâmetro na consulta de conjunto de dados. Por padrão, parâmetros criados manualmente são semelhantes a ReportParameter1.
Prompt	O texto que aparece ao lado do parâmetro na barra de ferramentas do visualizador de relatórios.
Tipo de dados	Um parâmetro de relatório deve ser de um destes tipos de dados: Boolean. O usuário seleciona Verdadeiro ou Falso usando um botão de opção. DateTime. O usuário digita uma nova data na caixa de texto, seleciona uma data de um controle de calendário ou seleciona Ir para hoje. Integer. O usuário digita valores em uma caixa de texto. Float. O usuário digita valores em uma caixa de texto. Text. O usuário digita valores em uma caixa de texto. Quando os valores disponíveis são definidos para um parâmetro, o usuário escolhe valores em uma lista suspensa, mesmo que o tipo de dados seja DateTime.
Permitir valor em branco	Selecione esta opção se o valor do parâmetro puder ser uma cadeia de caracteres vazia ou ficar em branco. Se você especificar valores válidos para um parâmetro e desejar que um valor em branco seja um dos valores válidos, deverá incluí-lo como um dos valores que especificar. A seleção dessa opção não inclui automaticamente um espaço para os valores disponíveis.
Permitir valor nulo	Selecione esta opção se o valor do parâmetro puder ser nulo. Se você especificar valores válidos para um parâmetro e desejar que um valor nulo seja um dos valores válidos, deverá incluir nulo como um dos valores que especificar. A seleção dessa opção não inclui automaticamente um nulo para os valores disponíveis.
Permitir diversos valores	Forneça valores disponíveis para criar uma lista suspensa na qual seus usuários possam fazer seleções. Essa é uma boa maneira de assegurar que somente valores válidos sejam enviados na consulta de conjunto de dados. Selecione esta opção se o valor do parâmetro puder ter diversos valores exibidos em uma lista suspensa. Valores nulos não são permitidos. Quando essa opção é selecionada, as caixas marcadas são adicionadas à lista de valores disponíveis em uma lista suspensa de parâmetros. A parte superior da lista inclui uma caixa de seleção para Selecionar Tudo. Os usuários podem marcar os valores desejados. Se os dados que fornecem valores forem alterados rapidamente, a lista que o usuário verá talvez não seja a mais atual.
Visible	Selecione essa opção para exibir o parâmetro de relatório na parte superior do relatório quando ele for executado. Esta opção permite que os usuários selecionem valores de parâmetro em tempo de execução.
Hidden	Selecione essa opção para ocultar o parâmetro no relatório publicado. Os valores de parâmetro de relatório ainda podem ser definidos em uma URL de relatório, em uma definição de assinatura ou no servidor de relatório.
Interna	Selecione essa opção para ocultar o parâmetro de relatório. No relatório publicado, o parâmetro de relatório só pode ser exibido na definição do relatório.
Valores disponíveis	Se você especificou valores disponíveis para um parâmetro, os valores válidos sempre aparecerão como uma lista suspensa. Por exemplo, se você fornecer valores disponíveis para um parâmetro DateTime , uma lista suspensa para datas aparecerá no painel de parâmetro em vez de um controle de calendário. Para assegurar que uma lista de valores seja consistente em um relatório e sub-relatórios, você poderá definir uma opção na fonte de dados para usar uma única transação para todas as consultas nos conjuntos de dados que forem associados a uma fonte de dados. Observação de Segurança: em qualquer relatório que inclua um parâmetro do tipo de dados Text, use uma lista de valores disponíveis (também conhecida como uma lista de valores válidos) e garanta que qualquer usuário que execute o relatório tenha somente as permissões necessárias para exibir os dados no relatório.
Valores padrão	Defina os valores padrão usando uma consulta ou uma lista estática. Quando cada parâmetro tem um valor padrão válido, o relatório é executado automaticamente na primeira exibição.
Avançado	Defina o atributo de definição de relatório UsedInQuery, um valor que indica se o parâmetro em questão afeta direta ou indiretamente os dados de um relatório. Determinar automaticamente quando atualizar Escolha esta opção para que o processador de relatório determine uma configuração para este valor. O valor será True se o processador de relatório detectar uma consulta de conjunto de dados com uma referência direta ou indireta a este parâmetro, ou se o relatório tiver sub-relatórios. Atualizar sempre Escolha esta opção quando o parâmetro de relatório for usado direta ou indiretamente em uma consulta de conjunto de dados ou em uma expressão de parâmetro. Esta opção define UsedInQuery como True. Nunca atualizar Escolha essa opção quando o parâmetro de relatório é usado direta ou indiretamente em uma expressão de parâmetro ou uma consulta de conjunto de dados. Esta opção define UsedInQuery como False. Cuidado: use a opção Nunca Atualizar com cuidado. No servidor de relatório, UsedInQuery é usado para ajudar a controlar as opções de cache para os dados de relatórios e para relatórios renderizados, além de opções de parâmetro para relatórios de instantâneo. Se você definir incorretamente a opção Nunca Atualizar , é possível que os dados de relatórios ou os relatórios incorretos sejam armazenados em cache, ou que um relatório de instantâneo apresente dados inconsistentes.

Consulta do conjunto de dados

Para filtrar dados na consulta de conjunto de dados, você pode incluir uma cláusula de restrição que limite os dados recuperados especificando valores a serem incluídos ou excluídos do conjunto de resultados.

Use o designer de consulta para a fonte de dados para criar uma consulta parametrizada.

• Para consultas Transact-SQL, fontes de dados diferentes dão suporte a diferentes tipos de sintaxe para parâmetros. O suporte abrange parâmetros que são identificados na consulta por posição ou por nome. No designer de consulta relacional, você deve selecionar a opção de parâmetro para um filtro para poder criar uma consulta parametrizada.

• Para consultas que são baseadas em uma fonte de dados multidimensional, como o Microsoft SQL Server Analysis Services, você pode especificar se deseja criar um parâmetro com base em um filtro especificado no designer de consultas.

Gerenciamento de parâmetros para um relatório publicado

Quando você cria um relatório, os parâmetros de relatório são salvos na definição de relatório. Quando você publica um relatório, os parâmetros de relatório são salvos e gerenciados separadamente da definição de relatório.

Para um relatório publicado, você pode usar o seguinte:

• Propriedades de parâmetros de relatório. Altere os valores de parâmetros de relatório diretamente no servidor de relatório, de modo independente da definição de relatório.

• Assinaturas de relatório. Você pode especificar valores de parâmetro para filtrar dados e entregar relatórios por meio de assinaturas.

As propriedades de parâmetros para um relatório publicado serão preservadas se você publicar novamente a definição do relatório. Se a definição do relatório for publicada novamente como o mesmo relatório, e os nomes e tipos de dados dos parâmetros continuarem os mesmos, as configurações de propriedades serão retidas. Se você adicionar ou excluir parâmetros da definição de relatório ou alterar o tipo de dados ou o nome de um parâmetro existente, talvez você precise alterar as propriedades de parâmetro no relatório publicado.

Nem todos os parâmetros podem ser modificados em todos os casos. Se um parâmetro de relatório obtiver um valor padrão de uma consulta de conjunto de dados, esse valor não poderá ser modificado para um relatório publicado e não poderá ser modificado no servidor de relatório. O valor usado em tempo de execução é determinado quando a consulta é executada ou, no caso de parâmetros baseados em expressão, quando a expressão é avaliada.

As opções de execução de relatório podem afetar o tipo de processamento dos parâmetros. Um relatório que é executado como um instantâneo não pode usar parâmetros que são derivados de uma consulta, a menos que a consulta inclua valores padrão para os parâmetros.

Parâmetros para uma assinatura

Você pode definir uma assinatura para um relatório sob demanda ou para um instantâneo e especificar os valores de parâmetro a serem usados durante o processamento da assinatura.

• Relatório sob demanda. Para um relatório sob demanda, você pode especificar um valor de parâmetro diferente do valor publicado para cada parâmetro listado para o relatório. Por exemplo, suponha que você tenha um relatório Serviço de Chamada que usa um parâmetro Período de Tempo para retornar solicitações de atendimento ao cliente para o dia, semana ou mês atual. Se o valor de parâmetro padrão do relatório for definido como hoje, sua assinatura poderá usar um valor de parâmetro diferente (como semana ou mês) para produzir um relatório com estatísticas semanais ou mensais.

Conteúdo relacionado

• O que são relatórios paginados no Power BI?
• Usar parâmetros em cascata nos relatórios paginados