Filtrar relatórios usando parâmetros da cadeia de caracteres de consulta na URL

Ao abrir um relatório no serviço do Power BI, cada página do relatório tem sua própria URL exclusiva. Para filtrar essa página do relatório, é possível usar o painel Filtros na tela de relatório. Outra opção é adicionar os parâmetros de cadeia de consulta à URL para filtrar o relatório. Talvez você tenha um relatório que gostaria de mostrar aos colegas, mas antes deseja filtrá-lo previamente para enviar a eles. Uma maneira de filtrar o relatório é começar com sua URL padrão, adicionar os parâmetros de filtro à URL e enviar por email toda a nova URL.

Este artigo usa o relatório Amostra de Análise de Varejo. Se você quiser acompanhar, baixe o relatório de amostra.

Usos dos parâmetros de cadeia de consulta

Digamos que você esteja trabalhando no Power BI Desktop e queira criar um relatório que contenha links para outros relatórios do Power BI, mas deseje mostrar apenas algumas das informações nos outros relatórios. Primeiro, filtre os relatórios usando os parâmetros de cadeia consulta e salve as URLs. Em seguida, crie uma tabela no Desktop com essas novas URLs de relatório. Em seguida, publique e compartilhe o relatório.

Alguém que esteja criando uma solução avançada do Power BI também pode usar os parâmetros de cadeia de consulta. Eles criam um relatório usando o DAX (Data Analysis Expressions), que gera uma URL de relatório filtrada dinamicamente com base na seleção que o cliente faz no relatório atual. Quando os clientes selecionam a URL, eles veem apenas as informações pretendidas.

Sintaxe dos parâmetros da cadeia de caracteres de consulta para filtragem

Com parâmetros, você pode filtrar o relatório usando um ou mais valores, mesmo quando esses valores contêm espaços ou caracteres especiais. A sintaxe básica é bastante direta; comece com a URL do relatório e, em seguida, adicione a sintaxe do filtro em uma cadeia de caracteres de consulta. Uma cadeia de caracteres de consulta em uma URL começa com um ponto de interrogação (?), por exemplo:

URL?filter=Table/Field eq 'value'

• Os nomes de Tabela e de Campo diferenciam maiúsculas de minúsculas, o de valor não.
• Os campos ocultos na exibição de relatório ainda podem ser filtrados.

Se o parâmetro de filtro não for o primeiro parâmetro na cadeia de caracteres de consulta, você o unirá ao parâmetro anterior com um e comercial (>), por exemplo:

URL?reportId=aaaaaaaa-0000-1111-2222-bbbbbbbbbb&pageName=ReportSection&filter=Table/Field eq 'value'

Regras de sintaxe importantes

Ao construir filtros de URL, tenha estas regras críticas em mente:

1. Nomes de campo com espaços: Use _x0020_ para representar espaços em nomes de tabela ou de campo. Por exemplo, se a tabela se chamar "Dados de Vendas", use Sales_x0020_Data no filtro de URL.

2. Nomes de campo com caracteres especiais: Para caracteres que não são ASCII, números principais ou caracteres especiais como@, , +[ou ], usam códigos de escape Unicode. O formato é _x seguido pelo valor Unicode de quatro dígitos e outro sublinhado. Consulte caracteres especiais em nomes de tabela e coluna para obter uma referência e exemplos completos.

3. Citando valores de campo: Envolva apenas os valores de campo de texto com apóstrofos simples. Os valores numéricos não possuem caracteres ao redor.

   • Valores de texto: filter=Product/Category eq 'Electronics'
   • Valores numéricos: filter=Product/Price eq 487

4. Filtros pré-existente: Todos os filtros pré-existentes precisam ser não filtrados (ou definidos como Todos) antes que o filtro de URL seja passado. Caso contrário, os filtros existentes e os novos filtros de URL criam uma relação AND que pode resultar em zero registros no conjunto de dados.

Dica

Se o filtro de URL não estiver funcionando conforme o esperado, verifique se há espaços ou caracteres especiais em sua tabela e nomes de campo. Esses são problemas comuns quando os filtros parecem não funcionar. Consulte caracteres especiais em filtros de URL para obter diretrizes de codificação.

Tipos de campo

O tipo de campo pode ser número, data/hora ou cadeia de caracteres. O tipo usado precisa corresponder ao tipo definido no modelo semântico. Por exemplo, especificar uma coluna de tabela do tipo "cadeia de caracteres" não funciona se você estiver procurando um valor numérico ou de data e hora em uma coluna de modelo semântico definida como uma data. Por exemplo, Table/StringColumn igual a 1.

• As Cadeias de caracteres precisam ser colocadas entre aspas simples, como ‘nome do gerenciador’.
• Os Números não exigem nenhuma formatação especial. Confira Tipos de dados numéricos neste artigo para obter mais detalhes.
• Datas e horas, confira Tipos de dados de data neste artigo.

Se ainda estiver confuso, continue lendo enquanto explicamos detalhadamente.

Filtrar em um campo

Suponhamos que a URL do nosso relatório seja a seguinte.

Podemos ver em nossa visualização de mapa acima que temos lojas na Carolina do Norte (NC). NC é um valor que representa a Carolina do Norte no campo Território da tabela Repositório. Portanto, para filtrar o relatório para mostrar dados somente de repositórios em "NC", acrescente esta cadeia de caracteres à URL:

?filter=Store/Territory eq 'NC'

Nosso relatório agora está filtrado para Carolina do Norte; todas as visualizações no relatório mostram dados apenas da Carolina do Norte.

Filtrar por mais de um valor em um campo

Para filtrar por mais de um valor em um único campo, use o operador in em vez do operador and. A sintaxe do é:

URL?filter=Campoda tabela/em ('value1', 'value2')

Usando o mesmo exemplo, para filtrar o relatório para mostrar dados somente de lojas em "NC" (Carolina do Norte) ou "TN" (Tennessee), inclua a URL com o seguinte:

?filter=Store/Territory in ('NC', 'TN')

Confira a tabela Operadores mais adiante neste artigo para obter uma lista de outros operadores úteis.

Filtrar em vários campos

Também é possível filtrar em vários campos adicionando mais parâmetros à sua URL. Vamos voltar ao nosso parâmetro de filtro original.

?filter=Store/Territory eq 'NC'

Para filtrar em mais campos, adicione um 'and' e outro campo no mesmo formato que o descrito acima. Veja um exemplo.

?filter=Store/Territory eq 'NC' and Store/Chain eq 'Fashions Direct'

Operadores

O Power BI dá suporte a diversos operadores além do 'and'. A tabela a seguir lista esses operadores, juntamente com o tipo de conteúdo compatível com eles.

Operador	Definição	String	Número	Data	Exemplo
and	e	sim	sim	sim	produto/preço menor ou igual a 200 e preço maior que 3.5
eq	igual a	sim	sim	sim	Endereço/Cidade eq 'Redmond'
ne	diferente de	sim	sim	sim	Endereço/Cidade != 'Londres'
ge	maior ou igual	não	sim	sim	produto/preço ≥ 10
gt	maior que	não	sim	sim	product/price gt 20
le	menor ou igual	não	sim	sim	produto/preço <= 100
lt	menor que	não	sim	sim	produto/preço menor que 20
in*	incluindo	sim	sim	sim	Aluno/Idade em (27, 29)

* Quando in é usado, os valores à direita de in podem ser uma lista separada por vírgulas entre parênteses ou uma única expressão que retorna uma coleção. Consulte o artigo Operador IN para obter exemplos.

Tipos de dados numéricos

Um filtro de URL do Power BI pode incluir números nos formatos a seguir.

Tipo de número	Exemplo
inteiro	5
longo	5 L ou 5 l
duplo	5.5 ou 55e-1 ou 0.55e+1 ou 5D ou 5d ou 0.5e1D ou 0.5e1d ou 5.5D ou 5.5d ou 55e-1D ou 55e-1d
decimal	5 M ou 5 m ou 5.5 M ou 5.5 m
flutuante	5 F ou 5 f ou 0.5e1 F ou 0.5e-1 d

Tipos de dados de data

O Power BI dá suporte ao OData V3 e V4 para os tipos de dados Data e DateTimeOffset. Para o OData V3, você precisa colocar datas entre aspas simples e precedê-las com a palavra datetime. Você não precisa de aspas simples e da palavra datetime no OData V4.

As datas são representadas usando o formato EDM (2019-02-12T00:00:00): Ao especificar uma data como "AAAA-MM-DD", o Power BI interpreta como "AAAA-MM-DDT00:00:00". Verifique se o mês (MM) e o dia (DD) são dois dígitos.

Por que essa distinção é importante? Digamos que você crie o parâmetro de cadeia de consulta Table/Date gt 2018-08-03. Os resultados incluirão 3 de agosto de 3, 2018 ou começarão em 4 de agosto de 4, 2018? O Power BI traduz sua consulta para a Table/Date gt '2018-08-03T00:00:00' . Portanto, seus resultados incluem todas as datas que tenham uma parte de tempo diferente de zero, pois essas datas seriam maiores que '2018-08-03T00:00:00'.

Há outras diferenças entre V3 e V4. O OData V3 não dá suporte a Datas, apenas DateTime. Portanto, se você usar o formato V3, deverá qualificá-lo com a data e hora completa. Datas literais, como "DateTime'2019-05-20'", não têm suporte na notação V3. Mas você pode simplesmente escrevê-la como "2019-05-20" na notação V4. Aqui estão duas consultas de filtro equivalentes em V3 e V4:

• Formato OData V4: filter=Table/Date gt 2019-05-20
• Formato OData V3: filter=Table/Date gt datetime'2019-05-20T00:00:00'

Caracteres especiais em filtros de URL

Caracteres especiais em nomes de tabela e coluna

Caracteres especiais, espaços e números iniciais nos nomes de tabela e coluna exigem mais formatação. Quando sua consulta contiver espaços, travessões, números iniciais ou outros caracteres não-ASCII, prefixe esses caracteres especiais com um código de escape começando com um sublinhado e um X (_x), depois o código de quatro dígitos Unicode e, em seguida, outro sublinhado. Se o Unicode tiver menos que quatro caracteres, será necessário preenchê-lo com zeros. Aqui estão alguns exemplos.

Identificador	Unicode	Codificação para o Power BI
Nome da tabela	O espaço é 00x20	Table_x0020_Name
Coluna@Número	@ é 00x40	Column_x0040_Number
[Column]	[ é 0x005B ] é 0x005D	_x005B_Column_x005D_
Column+Plus	+ é 0x2B	Column_x002B_Plus
2TableName	2 é x0032	_x0032_TableName

Table_x0020_Name/Column_x002B_Plus eq 3

Table_x0020_Special/_x005B_Column_x0020_Brackets_x005D_ eq '[C]'

Caracteres especiais em valores

Os filtros de URL dão suporte à maioria dos caracteres especiais nos valores do campo, mas alguns também exigem códigos de escape. Por exemplo, para procurar um caractere de aspa simples, use duas aspas simples ('').

• ?filter=Table/Name eq 'O''Brien' torna-se:

  

• ?filter=Table/Name eq 'Lee''s Summit' torna-se:

  

• O operador in também dá suporte a este escape: ?filter=Table/Name in ('Lee''s Summit', 'O''Brien') torna-se:

  

A seguir está uma lista de alguns caracteres especiais que exigem códigos de escape nos valores do campo.

Caractere	Código de escape
(um espaço)	%20
'	''
%	%25
+	%2B
/	%2F
?	%3F
#	%23
&	%26

Caracteres de escape padrão de URL

Quando você usa uma URL com espaços e outros caracteres especiais, os navegadores podem substituí-los automaticamente por caracteres de escape padrão. Digamos que você crie esta cadeia de caracteres de consulta de URL:

https://app.powerbi.com/groups/me/reports/b7dea1d4-d9f0-47aa-a88d-xxxxxxxxxxxx/ReportSection2?filter=Executives/Executive eq 'Andrew Ma'

Ela abre o Exemplo de Rentabilidade do Cliente, filtrado para Andrew Ma. Mas se você olhar para a URL agora, ela pode ser semelhante a esta:

https://app.powerbi.com/groups/me/reports/b7dea1d4-d9f0-47aa-a88d-xxxxxxxxxxxx/ReportSection2?filter=Executives%2FExecutive%20eq%20%27Andrew%20Ma%27

O navegador substituiu o espaço entre Andrew e Ma por %20, da mesma forma, os outros espaços. Ele substituiu a barra entre o nome da tabela Executives e o nome do campo Executive por %2F e substituiu a aspa simples ' por %27.

Essa versão de uma URL pode ser útil. Por exemplo, você pode colá-la no chat do Microsoft Teams e ela retornará os resultados filtrados desejados.

Usar o DAX para filtrar vários valores

Outra maneira de filtrar em vários campos é criar uma coluna calculada que concatena dois campos em um único valor. A partir daí, é possível filtrar nesse valor.

Suponhamos, por exemplo, que haja dois campos: Território e Cadeia. No Power BI Desktop, crie uma nova coluna Calculada (campo) chamada TerritoryChain. Lembre-se que o nome do Campo não pode conter espaços. Aqui está a fórmula DAX para essa coluna.

TerritoryChain = [Território] & " - " & [Cadeia]

Publique o relatório no serviço do Power BI e, em seguida, use a cadeia de caracteres de consulta da URL para filtrar e exibir dados somente das lojas Lindseys em NC.

https://app.powerbi.com/groups/me/reports/8d6e300b-696f-498e-b611-41ae03366851/ReportSection3?filter=Store/TerritoryChain eq 'NC – Lindseys'

Fixar um bloco de um relatório filtrado

Depois de filtrar o relatório usando parâmetros de cadeia de caracteres de consulta, você poderá fixar visualizações desse relatório no painel. O bloco no dashboard exibe os dados filtrados; a seleção desse bloco do dashboard abre o relatório usado para criá-lo. No entanto, a filtragem executada usando a URL não é salva com o relatório. Quando você seleciona o bloco do painel, o relatório é aberto em seu estado não filtrado. Isso significa que os dados exibidos no bloco do painel não correspondem aos dados exibidos na visualização de relatório.

Essa discrepância é útil quando você deseja ver resultados diferentes: filtrados no painel e não filtrados no relatório.

Considerações e solução de problemas

Há alguns pontos a serem considerados ao usar os parâmetros da cadeia de caracteres de consulta.

• Quando o operador in é usado, os valores à direita de in devem ser uma lista separada por vírgulas entre parênteses.

• O Servidor de Relatórios do Power BI também dá suporte à capacidade de especificar mais de um filtro usando o parâmetro de URL "filter". Veja um exemplo da aparência de uma URL em um Servidor de Relatórios do Power BI: https://reportserver/reports/powerbi/Store Sales?rs:Embed=true&filter= Store/Territory eq 'NC' and Store/Chain eq 'Fashions Direct'

• Filtros de URL do relatório têm um limite de 10 expressões (10 filtros conectados por AND).

• O tipo de dados Long é (2^53-1) devido a limitações de JavaScript.

• As cadeias de caracteres de consulta de URL são limitadas a 2.000 caracteres. Esse limite inclui códigos de escape para caracteres especiais (por exemplo, um espaço, %, +).

• Não é possível filtrar nomes de tabela ou coluna que começam com as letras maiúsculas INF, incluindo, por exemplo, um nome de tabela começando com "INFORMATION". “INF” em maiúsculas é um valor especial no OData. Se você quiser iniciar um nome de tabela ou coluna com "INF", faça-o em minúsculas "inf".

• Os nomes de tabela e de campo podem conter caracteres chineses expressos no formato Unicode. Por exemplo, digamos que você queira aplicar um filtro que 表/人 eq '张力' (isso significa Tabela/Pessoa eq '张力'). O filtro foi convertido para _x8868_/_x4eba_ eq '张力'.

  

Cenários de inserção

Os filtros de URL são compatíveis com alguns cenários de inserção e não com outros.

• Inserir um relatório em um portal ou site protegido é compatível.
• Os filtros de URL são compatíveis com o Power BI Embedded.
• A filtragem da cadeia de caracteres de consulta não funciona com Publicar na Web ou Exportar para PDF.
• Inserir com Web Part de Relatório no SharePoint Online não é compatível com filtros de URL.
• As equipes não permitem especificar uma URL.

Conteúdo relacionado

• Fixar uma visualização em um dashboard
• Inscrever-se em uma avaliação gratuita

Mais perguntas? Experimente perguntar à Comunidade do Power BI