É comum que em integrações com nossas APIs seja necessário retornar os dados de Campos Adicionais de tickets (ou de pessoas), e-mails, dados de organizações, e várias informações mais extensas armazenadas em coleções.
Consequentemente, o volume de dados retornados pode ficar pesado, às vezes contendo dados de entidades (tickets ou pessoas, por exemplo) que não são desejadas para a análise ou integração sendo realizada no momento.
Um exemplo seria puxar os dados de todos os tickets da base de atendimento, quando na verdade só se quer as informações de tickets cujo status seja “Resolvido”.
É para essa filtragem que existe o operador $filter, em API’s ODATA, como as nossas.
Neste artigo, você vai ver:
- Utilização do $filter e operadores de igualdade/intervalo
- Usando operadores booleanos (E e Ou)
- Operadores quantitativos e expressões lambda
Utilização do $filter e operadores de igualdade/intervalo
A ideia é que através do operador de $filter, você consegue definir dentro de quais condições as entidades pesquisadas em sua requisição da API devem estar, para serem retornadas. Um exemplo seria para consultar o ID só de tickets cujo status base seja “Resolvido”, na API de Tickets, usar a consulta:
https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$filter=baseStatus eq 'Resolved'
A lógica é que com essa consulta, através do parâmetro “$filter=baseStatus eq ‘Resolved’”, você está estipulando que deve haver uma filtragem dos dados retornados pela requisição de forma a obrigar que o atributo “baseStatus” do ticket seja igual a ‘Resolved’.
Abaixo, segue imagem de artigo da Microsoft, onde são descritos os 6 operadores aceitos no parâmetro de $filter (eq, ne, gt, lt, ge, le):
Usando operadores booleanos (E e Ou)
Caso desejado, também é possível filtrar por várias condições de uma só vez. Por exemplo, se além do status base igual a Resolvido, também quiser retornar os tickets que tenham o status base igual a Fechado (voltando tanto os Resolvidos quanto Fechados), você também pode utilizar o operador lógico “or” (ou), junto de uma nova condição em nosso $filter:
https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$filter=(baseStatus eq 'Resolved') or (baseStatus eq 'Closed')
Se, em vez de buscar por duas condições ao mesmo tempo (com o “or”), você quiser filtrar por dois atributos ao mesmo tempo (exemplo, tickets com status base Resolvidos cuja equipe responsável seja “Suporte”), é possível usar o operador lógico “and” (e):
https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$filter=(baseStatus eq 'Resolved') and (ownerTeam eq 'Suporte')
Operadores quantitativos e expressões lambda
Dito isso, é importante levantar alguns pontos. Por mais que o uso do $filter seja bem direto para atributos individuais, como os vistos até agora, ao mexer com subcoleções, é preciso tomar um pouco mais de cuidado. Nestes casos, é necessário usar operadores quantitativos e expressões lambda em conjunto com o filtro, para poder fazer essas consultas.
Usando operadores quantitativos
Existem três formas de usar esses operadores:
1. Usando o “All()”, com uma expressão lambda dentro dos parênteses
Neste caso, o dado será filtrado caso a expressão inserida seja verdadeira para todos os dados da coleção filtrada.
Ex: Filtrando o ID dos tickets nos quais todos os clientes do ticket sejam do tipo “Agente e Cliente”:
https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$filter=clients/all(client : client/profileType eq Movidesk.Core.Data.Enums.ProfileType'3')
2. Usando o “Any()”, com uma expressão lambda dentro dos parênteses
Neste caso, o dado será filtrado caso a expressão inserida seja verdadeira para qualquer um dos dados da coleção filtrada.
Ex: Solicitar o ID de todas as pessoas na organização “Movidesk”:
https://api.movidesk.com/public/v1/persons?token=[TOKEN DA API]&$select=id&$filter=relationships/any(org : org/name eq 'Movidesk')
Ou, ainda, selecionar o ID de todos os tickets que, em algum momento, já tenham sido alterados para o status “Resolvido”:
https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$filter=statusHistories/any(stts : stts/status eq "Resolvido")
3. Usando o “Any()”, sem expressão lambda nos parênteses
Dessa forma, a informação será filtrada caso haja qualquer elemento dentro da sua subcoleção.
Ex: Retornar o ID de todas as pessoas que tenham ao menos um contato cadastrado:
https://api.movidesk.com/public/v1/persons?token=[TOKEN DA API]&$select=id&$filter=contacts/any()
PS: Você também pode usar o operador lógico “not”, para “inverter” essa lógica, onde só são retornados os registros vazios. Um exemplo seria retornar todas as pessoas que não tenham nenhum e-mail cadastrado:
https://api.movidesk.com/public/v1/persons?token=[TOKEN DA API]&$select=id&$filter=not emails/any()
Construindo expressões Lambda
Uma dúvida que pode surgir ao ver os trechos acima é referente às “expressões lambda” mencionadas e contidas dentro dos parênteses de algumas das requisições supracitadas. Essas expressões nada mais são que formas de se referir a cada elemento da coleção que está sendo analisada, e os dados/atributos deste elemento.
Basicamente, ao usar o Any() ou All() para filtrar pelos dados e atributos de uma coleção, é preciso especificar uma expressão que “regule” quais valores serão filtrados. Consequentemente, existem, nestes casos, 3 informações necessárias: Coleção, Operador, e Expressão Lambda.
- Coleção: A propriedade que é uma coleção e pela qual gostaríamos de filtrar (exemplo, customFieldValues, que é a coleção de campos adicionais do ticket).
- Operador: O operador quantitativo que desejamos utilizar nessa comparação, como abordado neste artigo, onde podemos optar pelo “any”, ou pelo “all”.
- Expressão Lambda: As condições que devem ser respeitadas para este filtro, em formato de expressão lambda. Essa expressão deve seguir o formato de (apelidoDoElemento : Condições).
Na expressão Lambda, ainda existem as definições:
- ApelidoDoElemento: É como cada elemento da coleção “será chamado” dentro da expressão lambda. Pode ser o que preferir, até mesmo sendo uma só letra, mas o ideal é usar um termo que fique legível e tenha relação com o elemento sendo analisado, para facilitar a sua própria construção da consulta. No exemplo que daremos abaixo, vamos usar o apelido “campoAdicional”, já que estamos fazendo uma consulta com filtro relacionado à coleção de “customFieldValues”, onde os campos adicionais são armazenados.
- Condições: A condição lógica que deve ser preenchida para a filtragem de sua requisição da API. Seguem a mesma lógica das condições lógicas do $filter normais, mencionadas no início deste artigo.
Abaixo, segue um exemplo de requisição com um $filter usando expressões lambda, dessa vez com a fonte colorida conforme o que aquela informação representa dentro do conceito abordado aqui, para que possa comparar às cores do texto acima.
https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$filter=customFieldValues/any(campoAdicional : campoAdicional/customFieldId eq [ID DO CAMPO])
Esse seria um exemplo de como selecionar o ID de seus tickets que contenham determinado campo adicional específico dentro deles (que pode ser informado através da substituição de “[ID DO CAMPO]” pelo ID do campo adicional).
Para as "/" (barras) usadas na requisição acima, em “campoAdicional/customFieldId”, elas servem o propósito de associar que estamos olhando para o valor de "customFieldId" dentro do elemento apelidado de "campoAdicional".
Entendemos que o tópico abordado neste artigo possui maior complexidade para usuários que não tenham experiência com Lógica de Programação ou API’s, e em casos de quaisquer dúvidas sobre os temas abordados, podem sempre entrar em contato com nossas equipes de atendimento.
Vale reforçar que não realizamos a configuração de consultas da API personalizadas para clientes, mas podemos auxiliar com dúvidas pontuais sobre o funcionamento de nossas API’s, e parametrizações ou retornos das requisições.