É 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)
https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$filter=(baseStatus eq 'Resolved') or (baseStatus eq 'Closed')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
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
https://api.movidesk.com/public/v1/persons?token=[TOKEN DA API]&$select=id&$filter=relationships/any(org : org/name eq 'Movidesk')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
- 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).
- 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.
https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$filter=customFieldValues/any(campoAdicional : campoAdicional/customFieldId eq [ID DO CAMPO])