Filtrar relatórios usando parâmetros da cadeia de caracteres de consulta na URLFilter a report using query string parameters in the URL

• 07/16/2020
• 8 minutos para o fim da leitura
• • m
  • o

Ao abrir um relatório no serviço do Power BI, cada página do relatório tem sua própria URL exclusiva.When you open a report in Power BI service, each page of the report has its own unique URL. Para filtrar essa página do relatório, é possível usar o painel Filtros na tela de relatório.To filter that report page, you could use the Filters pane on the report canvas. Outra opção é adicionar os parâmetros de cadeia de consulta na URL para filtrar o relatório.Or you could add query string parameters to the URL to pre-filter the report. Talvez você tenha um relatório que gostaria de mostrar aos colegas, mas antes deseja filtrá-lo previamente para enviar a eles.Perhaps you have a report you'd like to show colleagues and you want to pre-filter it for them. Uma maneira de filtrar isso é iniciar com a URL padrão do relatório, adicionar os parâmetros de filtro à URL e, em seguida, enviá-los a nova URL inteira por email.One way to filter it is to start with the default URL for the report, add the filter parameters to the URL, and then email them the entire new URL.

Este artigo usa o relatório Amostra de Análise de Varejo.This article uses the Retail Analysis Sample report. Se você quiser acompanhar, baixe o relatório de amostra.If you want to follow along, you can download the sample report.

Usos dos parâmetros de cadeia de consultaUses for query string parameters

Digamos que você esteja trabalhando no Power BI DesktopSay you're working in 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.You want to create a report that has links to other Power BI reports, but you want to show only some of the information in the other reports. Primeiro, filtre os relatórios usando os parâmetros de cadeia consulta e salve as URLs.First, filter the reports using query string parameters and save the URLs. Em seguida, crie uma tabela no Desktop com essas novas URLs de relatório.Next, create a table in Desktop with these new report URLs. Em seguida, publique e compartilhe o relatório.Then publish and share the report.

Alguém que esteja criando uma solução avançada do Power BI também pode usar os parâmetros de cadeia de consulta.Another use for query string parameters is for someone creating an advanced Power BI solution. Usando o DAX, ela cria um relatório que gera uma URL do relatório filtrado dinamicamente, com base na seleção que seu cliente faz no relatório atual.Using DAX, they create a report that generates a filtered report URL dynamically based on the selection their customer makes in the current report. Quando os clientes selecionam a URL, eles veem apenas as informações pretendidas.When customers select the URL, they see only the intended information.

Sintaxe dos parâmetros da cadeia de caracteres de consulta para filtragemQuery string parameter syntax for filtering

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.With parameters, you can filter the report for one or more values, even if those values contain spaces or special characters. A sintaxe básica é razoavelmente simples. Comece com a URL do relatório, adicione um ponto de interrogação e, em seguida, adicione a sintaxe do filtro.The basic syntax is fairly straightforward; start with the report URL, add a question mark, and then add your filter syntax.

URL?filter=Table/Field eq 'value'URL?filter=Table/Field eq 'value'

• Os nomes de Tabela e Campo diferenciam maiúsculas de minúsculas, o valor não.Table and Field names are case-sensitive, value isn't.
• Os campos ocultos na exibição de relatório ainda podem ser filtrados.Fields that are hidden from report view can still be filtered.

Tipos de campoField types

O tipo de campo pode ser número, data/hora ou cadeia de caracteres. O tipo usado precisa corresponder ao tipo definido no conjunto de dados.Field type can be a number, datetime, or string and the type used must match the type set in the dataset. Por exemplo, a especificação de uma coluna de tabela do tipo "cadeia de caracteres" não funcionará se você estiver procurando um valor de data/hora ou numérico em uma coluna de conjunto de dados definida como data, por exemplo, Table/StringColumn eq 1.For example, specifying a table column of type "string" won't work if you're looking for a datetime or numeric value in a dataset column set as a date, such as Table/StringColumn eq 1.

• As Cadeias de caracteres precisam ser colocadas entre aspas simples, como ‘nome do gerenciador’.Strings must be enclosed with single quotes, as in 'manager name'.
• Os Números não exigem nenhuma formatação especial.Numbers require no special formatting. Confira Tipos de dados numéricos neste artigo para obter mais detalhes.See Numeric data types in this article for details.
• Datas e horas, confira Tipos de dados de data neste artigo.Dates and times See Date data types in this article.

Se ainda estiver confuso, continue lendo e nós explicaremos detalhadamente.If it's still confusing, continue reading and we'll break it down.

Filtrar em um campoFilter on a field

Suponhamos que a URL do nosso relatório seja a seguinte.Let’s assume that the URL to our report is the following.

Podemos ver em nossa visualização de mapa acima que temos lojas na Carolina do Norte.And we see in our map visualization above that we have stores in North Carolina. NC é um valor que representa a Carolina do Norte no campo Território da tabela Repositório.NC is the value that represents North Carolina in the Territory field of the Store table. Portanto, para filtrar o relatório para mostrar dados somente de repositórios em "NC", acrescente esta cadeia de caracteres à URL:So to filter the report to show data only for stores in "NC", we append this string to the 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.Our report is now filtered for North Carolina; all the visualizations in the report show data for only North Carolina.

Filtrar por mais de um valor em um campoFilter on more than one value in a field

Para filtrar por mais de um valor em um único campo, use o operador in em vez do operador and.To filter on more than one value in a single field, you use the in operator instead of the and operator. A sintaxe do é:The syntax is:

URL?filter=Table/Field in ('value1', 'value2')URL?filter=Table/Field in ('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:Using the same example, to filter the report to show data only for stores in "NC" (North Carolina) or "TN" (Tennessee), append the URL with the following;

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

Confira a tabela Operadores mais adiante neste artigo para obter uma lista de outros operadores úteis.See the Operators table later in the article for a list of other useful operators.

Filtrar em vários camposFilter on multiple fields

Também é possível filtrar em vários campos adicionando mais parâmetros à sua URL.You can also filter on multiple fields by adding additional parameters to your URL. Vamos voltar ao nosso parâmetro de filtro original.Let's go back to our original filter parameter.

?filter=Store/Territory eq 'NC'

Para filtrar por campos adicionais, adicione um 'and' e outro campo no mesmo formato que o descrito acima.To filter on additional fields, add an 'and' and another field in the same format as above. Veja um exemplo.Here is an example.

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

OperadoresOperators

O Power BI dá suporte a diversos operadores além do 'and'.Power BI supports many operators in addition to 'and'. A tabela a seguir lista esses operadores, juntamente com o tipo de conteúdo compatível com eles.The table below lists those operators along with the content type they support.

** 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.** When using in, the values to the right of in can be a comma-separated list enclosed in parentheses, or a single expression that returns a collection.

Tipos de dados numéricosNumeric data types

Um filtro de URL do Power BI pode incluir números nos formatos a seguir.A Power BI URL filter can include numbers in the following formats.

Tipos de dados de dataDate data types

O Power BI dá suporte ao OData V3 e V4 para os tipos de dados Data e DateTimeOffset.Power BI supports both OData V3 and V4 for Date and DateTimeOffset data types. Para OData v3, as datas precisam ser colocadas entre aspas simples e ser precedidas pela palavra datetime.For OData V3, dates must be enclosed in single quotes and be preceded by the word datetime. As aspas simples e a palavra datetime não são necessárias no OData v4.Single quotes and the word datetime aren't needed in 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".Dates are represented using the EDM format (2019-02-12T00:00:00): When you specify a date as 'YYYY-MM-DD', Power BI interprets it as 'YYYY-MM-DDT00:00:00'. Verifique se o mês e o dia são dois dígitos, MM e DD.Make sure month and day are two digits, MM and DD.

Por que essa distinção é importante?Why does this distinction matter? Digamos que você crie o parâmetro de cadeia de consulta Table/Date gt 2018-08-03.Let's say you create a query string parameter 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?Will the results include August 3, 2018 or start with August 4, 2018? O Power BI traduz sua consulta para a Table/Date gt '2018-08-03T00:00:00' .Power BI translates your query to Table/Date gt '2018-08-03T00:00:00'. Portanto, os resultados incluem todas as datas que têm uma parte de tempo diferente de zero, pois essas datas seriam maiores que "2018-08-03T00:00:00" .So, your results include any dates that have a non-zero time part, because those dates would be greater than '2018-08-03T00:00:00'.

Há outras diferenças entre V3 e V4.There are other differences between V3 and V4. O OData V3 não dão suporte a Datas, somente a DateTime.OData V3 does not support Dates, only DateTime. Portanto, se você usar o formato V3, deverá qualificá-lo com a data e hora completa.So if you use the V3 format, you must qualify it with the full date time. Datas literais, como "DateTime'2019-05-20'", não têm suporte na notação V3.Date literals like "datetime'2019-05-20'" aren't supported in V3 notation. Mas você pode simplesmente escrevê-la como "2019-05-20" na notação V4.But you can just write it as "2019-05-20" in V4 notation. Aqui estão duas consultas de filtro equivalentes em V3 e V4:Here are two equivalent filter queries in V3 and V4:

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

Caracteres especiais em filtros de URLSpecial characters in URL filters

Caracteres especiais em nomes de tabela e colunaSpecial characters in table and column names

Caracteres especiais e espaços em nomes de tabela e coluna exigem uma formatação adicional.Special characters and spaces in table and column names require some additional formatting. Quando a sua consulta contiver espaços, traços 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), em seguida, o Unicode de quatro dígitos e seguido por outro sublinhado.When your query contains spaces, dashes, or other non-ASCII characters, prefix those special characters with an escape code starting with an underscore and an X (_x), then the four-digit Unicode, then another underscore. Se o Unicode tiver menos que quatro caracteres, será necessário preenchê-lo com zeros.If the Unicode is fewer than four characters, you need to pad it with zeroes. Aqui estão alguns exemplos.Here are some examples.

Table_x0020_Name/Column_x002B_Plus eq 3 Table_x0020_Name/Column_x002B_Plus eq 3

Table_x0020_Special/x005B_Column_x0020_Brackets_x005D eq '[C]' Table_x0020_Special/x005B_Column_x0020_Brackets_x005D eq '[C]'

Caracteres especiais em valoresSpecial characters in values

Os filtros de URL já dão suporte a todos os caracteres especiais em valores de campo, exceto a aspa simples (').URL filters already support all special characters in field values, except the single quote ('). Esse é o único caractere que você precisa ignorar.That's the only character you need to escape. Para procurar um caractere de aspa simples, use duas aspas simples ('').To search for a single quote character, use two single quotes ('').

Por exemplo:For example:

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

  

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

  

• O operador in também dá suporte a este escape: ?filter=Table/Name in ('Lee''s Summit', 'O''Brien') torna-se:The in operator supports this escaping as well: ?filter=Table/Name in ('Lee''s Summit', 'O''Brien') becomes:

  

Usar o DAX para filtrar vários valoresUse DAX to filter on multiple values

Outra maneira de filtrar em vários campos é criar uma coluna calculada que concatena dois campos em um único valor.Another way to filter on multiple fields is by creating a calculated column that concatenates two fields to a single value. A partir daí, é possível filtrar nesse valor.Then you can filter on that value.

Suponhamos, por exemplo, que haja dois campos: Território e Cadeia.For example, we have two fields: Territory and Chain. No Power BI Desktop, crie uma nova coluna Calculada (campo) chamada TerritoryChain.In Power BI Desktop, create a new Calculated column (Field) called TerritoryChain. Lembre-se que o nome do Campo não pode conter espaços.Remember that the Field name can't have any spaces. Veja a seguir a fórmula DAX da coluna.Here is the DAX formula for that column.

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

Publique o relatório no serviço do Power BI e, em seguida, use a cadeia de caracteres de consulta de URL para filtrar e exibir dados somente de lojas Lindseys em NC.Publish the report to Power BI service and then use the URL query string to filter to display data for only Lindseys stores in 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 filtradoPin a tile from a filtered report

Após filtrar o relatório usando parâmetros da cadeia de caracteres de consulta, é possível fixar as visualizações do relatório em questão no seu dashboard.Once you've filtered the report using query string parameters, you can pin visualizations from that report to your dashboard. O bloco no dashboard exibe os dados filtrados; a seleção desse bloco do dashboard abre o relatório usado para criá-lo.The tile on the dashboard displays the filtered data and selecting that dashboard tile opens the report that was used to create it. No entanto, a filtragem executada usando a URL não é salva com o relatório.However, the filtering you did using the URL isn't saved with the report. Quando você seleciona o bloco do painel, o relatório é aberto em seu estado não filtrado.When you select the dashboard tile, the report opens in its unfiltered state. Isso significa que os dados exibidos no bloco do painel não correspondem aos dados exibidos na visualização de relatório.Thus, the data displayed in the dashboard tile doesn't match the data displayed in the report visualization.

Essa discrepância é útil quando você deseja ver resultados diferentes: filtrados no painel e não filtrados no relatório.This discrepancy is helpful when you want to see different results; filtered on the dashboard and unfiltered in the report.

Considerações e solução de problemasConsiderations and troubleshooting

Há alguns pontos a serem considerados ao usar os parâmetros da cadeia de caracteres de consulta.There are a couple of things to be aware of when using the query string parameters.

• Quando o operador in é usado, os valores à direita de in devem ser uma lista separada por vírgulas entre parênteses.When using the in operator, the values to the right of in must be a comma-separated list enclosed in parentheses.
• O Servidor de Relatórios do Power BI também é compatível com a capacidade de especificar filtros adicionais usando o parâmetro de URL "filter".Power BI Report Server also supports the ability to specify additional filters using the “filter” URL parameter. 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'Here's an example of what the URL might look like in Power BI Report Server: 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).Report URL filters have a 10-expression limit (10 filters connected by AND).
• O tipo de dados Long é (2^53-1) devido a limitações de JavaScript.The long data type is (2^53-1) due to JavaScript limitations.
• O Power BI não limita o número de caracteres em cadeias de consulta de URL.Power BI doesn't limit the number of characters in URL query strings. Diferentes navegadores têm diferentes restrições de comprimento.Different browsers have different length restrictions.

Os filtros de URL são compatíveis com alguns cenários de inserção e não com outros.URL filters are supported in some embedding scenarios and not in others.

• Inserir um relatório em um portal ou site protegido é compatível.Embedding a report in a secure portal or website is supported.
• Os filtros de URL são compatíveis com o Power BI Embedded.URL filters are supported in Power BI Embedded. Confira os Recursos avançados de filtragem de URL do Power BI Embedded para obter mais detalhes.See Power BI Embedded advanced URL filtering capabilities for details.
• A filtragem da cadeia de caracteres de consulta não funciona com Publicar na Web ou Exportar para PDF.Query string filtering doesn't work with Publish to web or Export to PDF.
• Inserir com Web Part de Relatório no SharePoint Online não é compatível com filtros de URL.Embed with report web part in SharePoint Online doesn't support URL filters.
• As equipes não permitem especificar uma URL.Teams doesn't allow specifying a URL.

Próximas etapasNext steps

Fixar uma visualização em um dashboardPin a visualization to a dashboard
Inscrever-se em uma avaliação gratuitaSign up for a free trial

Mais perguntas?More questions? Experimente perguntar para a Comunidade do Power BITry asking the Power BI Community