Usar OData filtrando com o SharePoint

14 minutos

Nessa unidade, aprendemos a usar filtros OData (Protocolo Open Data) ao consultar as listas e as bibliotecas de documentos do SharePoint.

Por que usar um filtro OData?

Para que você deve usar filtros OData para o SharePoint? Por padrão, a ação Obter itens para listas ou a ação Obter arquivos para bibliotecas só recupera os primeiros 100 itens ou arquivos do SharePoint se você não especifica um valor de Contagem principal ou Limite. Embora seja possível especificar uma Contagem principal até o limite padrão de 5.000 itens, se a sua lista ou biblioteca tiver mais de 5.000 itens ou arquivos, ela não retornará todos os dados usando uma entrada na Contagem principal. Portanto, a filtragem da consulta ajuda a criar resultados abaixo dos limites.

A tentativa de inserir um número maior que 5.000 resulta em uma falha de fluxo quando você tenta executá-lo.

Compreenda as configurações de ação para grandes listas ou bibliotecas

Se a sua lista ou biblioteca com mais de 100 itens ou arquivos e até 5.000 itens, tudo o que você precisa ajustar é a Contagem principal. Na Contagem principal, é possível inserir um valor até o limite padrão de 5.000. O limite serve para evitar que essa etapa retorne mais de 5.000 itens. A Contagem principal é uma maneira mais eficiente de recuperar até 5.000 itens de seus dados.

Se sua lista ou biblioteca tiver mais de 5.000 itens, ou sua consulta retornar mais de 5.000 itens, você precisará habilitar a Paginação da etapa. O que é paginação? Cada vez que a ação Obter itens busca valores, ela recebe 100 itens por vez. Da mesma forma que, se você percorrer sua lista ou biblioteca do SharePoint, vá até a parte inferior dos itens visíveis e o SharePoint buscará outros 100 itens. Assim, a paginação permite que o processo de busca (em lotes de 100 itens) continue muito além disso. Tenha em mente, porém, que a paginação leva tempo e diminui seu fluxo. Com a paginação habilitada, sua ação repete esse processo para retornar o valor inserido manualmente do Limite total (outra entrada necessária que discutiremos momentaneamente).

Para localizar a configuração da paginação, selecione as reticências no canto direito da ação Obter itens ou Obter arquivos para exibir as Configurações.

No painel de configurações de ação, alterne a opção Paginação como Ativada e, em seguida, insira um valor para Limite. A paginação pode retornar de 1 a 100.000 itens de sua fonte de dados, mas você só precisa defini-la para o número de itens que espera ser retornado. Por fim, selecione Feito para retornar às configurações normais.

A configuração Limite no painel de configurações é um pouco difícil de compreender, mas veja dessa forma. Ela deve corresponder ao número de itens que você espera receber de sua consulta, mas não pode retornar mais de 100.000 itens. Por exemplo, se você definir o Limite como 500 e tiver 2.000 itens correspondentes à consulta, só receberá 500 itens. Da mesma forma, se você definir o Limite como 2.000, obterá todos os 2.000 itens esperados.

Por que isso é importante? Por que não basta apenas maximizar os valores para a Contagem principal (5.000) e Limite (100.000)? Porque pedir ao Power Automate para paginar leva tempo e diminui o seu fluxo. Se você conseguir obter todos os dados esperados com um valor de Contagem principal de 2.500 (por exemplo), não há necessidade de alternar a paginação e aplicar o valor máximo ao limite para continuar a paginar todos os seus dados.

Mais uma coisa a considerar antes de seguirmos em frente: sempre defina a Contagem principal como 5.000 se você espera um retorno de mais de 5.000 itens. A Contagem principal é uma maneira rápida de retornar os primeiros 5.000 itens e a paginação retoma no final dos primeiros 5.000 itens. Elas trabalham em conjunto. A paginação por si só certamente funciona, mas tem que continuar buscando 100 itens por vez para fazer o mesmo trabalho.

Como usar OData em sua consulta de filtro

Agora que conseguimos filtrar seus dados, vamos aprender a usar a filtragem OData. Quando você está usando a filtragem OData em suas consultas, o padrão no campo Consulta de filtro é baseado no tipo de dados na coluna. Vamos começar com um filtro por uma coluna. Se o valor da coluna for igual a uma cadeia de caracteres, podemos usar um filtro parecido com esse:

StringColumn eq 'text'

Percebe como a instrução OData usa a abreviação eq para iguais? Esse é o código OData para o operador equals. Além disso, observe como o valor da nossa cadeia de caracteres tem aspas simples em volta.

É possível usar o mesmo operador OData para uma coluna com valor numérico como:

NumericColumn eq 3

Observe que, ao comparar valores numéricos, não precisamos usar aspas simples.

O SharePoint não realiza todas as operações que o Power Automate pede para fazer devido a restrições de delegação, o que significa que o SharePoint apenas executa determinados tipos de filtros de consulta por conta própria. Aqui estão os operadores OData que podem ser usados para solicitar a filtragem do SharePoint:

Operator	Abreviação	Sintaxe
Equals	eq	`StringValueColumn eq 'text'` (ou `NumericColumn eq number`)
Not equals	ne	`StringValueColumn ne 'text'` (ou `NumericColumn ne number`)
Less than	lt	`NumericColumn lt number` (ou `DateValueColumn lt date`)
Greater than	gt	`NumericColumn gt number` (ou `DateValueColumn gt date`)
Less than or equal to	le	`NumericColumn le number` (ou `DateValueColumn le date`)
Greater than or equal to	ge	`NumericColumn le number` (ou `DateValueColumn le date`)
Starts with	startswith	`startswith(StringValueColumn, 'text')`
Substring of	substringof	`substringof('text', StringValueColumn)`
And	and	`FilterFormula and FilterFormula`
Or	or	`FilterFormula or FilterFormula`

Texto de passo a passo igual ao filtro

Vamos analisar um exemplo juntos. Encontre uma lista do SharePoint com vários itens que você pode usar e abra uma instância separada do navegador para o Power Automate maker portal.

Na tela Início do Power Automate maker portal, selecione a guia Criar no menu de navegação do lado esquerdo.
Selecione Fluxo da nuvem instantâneo entre as opções na parte superior.
Selecione Disparar um fluxo manualmente>Criar.
Adicione uma etapa sob o gatilho e pesquise por sharepoint.
Localize e selecione a ação SharePoint Obter itens.
Adicione o Endereço do site do SharePoint. Esta é a URL da home page do site onde a sua lista do SharePoint reside. Se você não vir o nome da lista do SharePoint na lista suspensa para Endereço do site, é possível pegar a home page do seu site do SharePoint selecionando Início a partir do trilho de navegação do lado esquerdo e copiar a URL do navegador. De volta ao Power Automate, selecione a opção suspensa para Inserir valor personalizado e cole a URL da home page do SharePoint.
Em Nome da lista, localize e selecione o nome da lista do SharePoint no menu suspenso.
Expanda Mostrar opções avançadas e localize o campo Consulta de filtro. Observe que o texto da dica (você pode exibir toda a dica passando o mouse sobre o campo) diz que espera uma instrução de filtro ODATA e ainda fornece exemplos de sintaxe.
Vamos iniciar filtrando uma coluna de valor de texto do SharePoint usando a função equals (eq). Escolha uma de suas colunas que contenha valores de texto. Para a fórmula, insira no nome da coluna eq e, em seguida, um valor a partir dessa coluna dentro de aspas simples. Insira um valor exato nas aspas nos dados da coluna.

Se você não corresponder o nome/valor da coluna exatamente, o filtro não funcionará. Para ver os valores dos nomes das colunas, navegue até as Configurações de lista do SharePoint selecionando o ícone de configurações, em seguida, passe o mouse sobre o nome da coluna e procure o nome dessa coluna na parte inferior da tela. Ao passar o mouse sobre o nome, uma URL será exibida com um sinal de igual e, em seguida, o nome da coluna.

Veja nosso exemplo abaixo. Nossa coluna do SharePoint é chamada de Descrição do produto, mas o nome real nos dados é field_1, então esse é o nome que precisaríamos inserir para o nome da coluna.
Para que possamos ver quantos itens retornam com nosso filtro, vamos adicionar mais uma ação na ação Obter itens. Adicionar uma ação Compor. Selecione o campo Entradas e alterne para a guia Expressão. Adicione a seguinte fórmula no campo de entrada Expressão:

length(outputs('Get_items')?['body/value'])

Esta ação conta o número de linhas que nossa ação Obter itens retorna.
Selecione Atualizar para salvar esse valor.
Agora vamos testar nosso fluxo. Selecione Salvar>Testar>Manualmente>Testar e, depois que a conexão estiver verificada, selecione Executar fluxo.
Depois de executar o fluxo, expanda a ação Compor nos resultados do fluxo e exiba quantos itens foram retornados. Era isso o que você esperava? Se você testou com uma grande lista de itens com mais de um item correspondendo aos seus critérios, pode ter retornado apenas 100 itens.

Se o filtro não funcionou, confira para saber se estão exatos o nome da coluna e os dados correspondentes dentro de aspas simples.

Usar a Contagem principal

Usando o mesmo fluxo, vamos ver como a Contagem principal pode ser útil. A Contagem principal é uma ótima maneira de testar se a sua lista está filtrando corretamente, já que você pode limitar os dados retornados para alguns itens e exibir rapidamente esses dados depois que o fluxo for executado.

Coloque seu fluxo de volta no modo de Edição.
Expanda a ação Obter itens e selecione Mostrar opções avançadas.
No campo à direita da Contagem principal, insira 1.
Teste e execute seu fluxo novamente.

Dica

Ao testar seu fluxo, você pode usar a opção Automaticamente com uma execução anterior para executar novamente o fluxo com menos cliques de botão.
Na tela de resultados da execução, se você expandir sua ação Compor, ela deverá refletir o valor de 1 em entradas/saídas.
Se você expandir a ação Obter itens, poderá selecionar Clicar para baixar para retratar o código JSON do item retornado.
Coloque seu fluxo de volta no modo de Edição mais uma vez.
Insira um valor de contagem principal do que você espera ver em sua consulta (até 5.000), mas não maior que o número de itens em sua lista.
Salve e Teste seu fluxo novamente. Conseguiu os resultados que esperava? Caso contrário, volte e verifique seus valores, e tente novamente.

Usar a paginação

Para testar a paginação, você precisará ter uma lista com mais de 100 itens, já que a função Get Items busca 100 itens por vez. Uma lista com 101 a 200 itens precisaria de duas buscas. Lembre-se, você realmente não precisa de paginação se espera retornar 5.000 itens ou menos, a Contagem principal tem um desempenho muito melhor. Mas ela mostra como funciona.

Coloque seu fluxo no modo de Edição mais uma vez.
Apague o valor que tiver para a Contagem principal e deixe em branco. Realisticamente, você sempre usaria a Contagem principal para seu filtro porque ele pode chamar rapidamente seus primeiros 5.000 valores. Mas, neste caso, esperamos demonstrar como a paginação funciona, e como ela pode ser lenta se for executada sozinha.
Vá para as configurações da ação Obter itens.
Alterne a Paginação para Ativada e insira o número de itens que você espera recuperar no campo de entrada Limite.
Selecione Concluído.
Salve e Teste seu fluxo. Se você tiver uma lista grande, observe que o fluxo demora muito tempo para ser executado. Imagine percorrer toda a sua lista do SharePoint 100 itens de cada vez!

Em resumo

Espero que você tenha conseguido uma compreensão básica de:

Filtragem de listas do SharePoint usando a filtragem OData,
Por que você deseja filtrar o SharePoint,
E como você pode modificar suas ações do SharePoint para retornar os dados desejados.

Continuar