Como realizar filtros e manipulações adicionais nas API's com oData
OData (Open Data Protocol) é um padrão internacional que facilita o consumo e manipulação de API's e pode ser utilizado em algumas API's do Zeev.
O que é oData?
OData (Open Data Protocol) é um padrão internacional que facilita o consumo e manipulação de API's. Com uso de comandos oData, você pode:
Quando é possível utilizar oData
As API's do Zeev onde o uso de oData é permitido explicitamente indicarão isso em sua documentação nesse site. Nas API's onde não há referência de oData, não haverá suporte a esse recurso.
Se você tentar utilizar filtros oData em API's que não suportam isso, receberá erro 400 - BadRequest, similar ao abaixo:
{
"error": {
"code": "400",
"key": "api.badrequest",
"message": "The query specified in the URI is not valid. Query option 'Expand' is not allowed. To allow it, set the 'AllowedQueryOptions' property on EnableQueryAttribute or QueryValidationSettings.",
"vars": null,
"details": []
}
}Como filtrar retornos de API's com oData
Sempre prefira e utilize os métodos de filtro da própria API. Por exemplo, a API de Listar pessoaspossui, ela própria, propriedades de filtro pré-definidas para isActive. Utilize sempre os filtros, seja o documento JSON de filtro, sejam propriedades na URL de filtro, nativas da API.
Os filtros adicionais em OData permitem que os clientes restrinjam os resultados de uma consulta para incluir apenas os registros que atendem a critérios específicos. Esses filtros são aplicados usando a cláusula $filter na URL da requisição. A sintaxe do OData permite o uso de uma variedade de operadores de comparação e funções para criar filtros complexos.
Operadores de Comparação OData
OData suporta uma ampla gama de operadores de comparação que podem ser usados para criar filtros. Alguns dos operadores mais comuns incluem:
eq: Igual a
ne: Diferente de
gt: Maior que
ge: Maior ou igual a
lt: Menor que
le: Menor ou igual a
and: E lógico
or: Ou lógico
not: Negação lógica
Exemplos de Uso
A seguir, apresentamos exemplos práticos de como usar filtros adicionais com OData em diferentes casos de uso.
Filtrando por Igualdade
Para filtrar dados que são iguais a um valor específico, usa-se o operador eq. Por exemplo, em uma API fictícia, para obter todos os clientes cujo país seja "Brasil" a partir da propriedade country:
Ou, no caso abaixo, para obter todos os clientes que estejam ativos a partir da propriedade isAtive:
Filtrando por Inequalidade
Para excluir dados que são iguais a um valor específico, usa-se o operador ne. Por exemplo, em uma API fictícia, para obter todos os clientes que não estão no país "Brasil" a partir da propriedade country:
Filtrando por Intervalos de Valores
Os operadores gt, ge, lt, e le são usados para filtrar dados dentro de intervalos de valores. Por exemplo, em uma API fictícia, para obter produtos cujo preço seja maior que 100 a partir da propriedade price:
Ou para obter produtos cujo preço esteja entre 50 e 150:
Filtrando por Campos de Texto
Para realizar filtros em campos de texto, podem ser usadas funções como substringof.
Por exemplo, em uma API fictícia, para obter todos os clientes cujo nome contém "Rafael" a partir da propriedade name:
Aqui também pode ser utilizada a expressão contains, função essencial para verificar se uma string contém outra.
Outro reforço importante é o uso da expressão toupper, que torna as buscas como case-insensitive. Por exemplo, uma pesquisa case-insensitive para buscar os usuários que contém "dos Santos" a partir da propriedade name, dentro do campo do formulário "Nome":
Combinação de Filtros
Filtros podem ser combinados usando operadores lógicos como and e or. Por exemplo, em uma API fictícia, para obter produtos cujo preço seja menor que 50 ou cujo estoque seja maior que 200:
Filtrando por Datas
Para filtrar dados por datas, usa-se a função datetime. Por exemplo, em uma API fictícia, para obter pedidos feitos após 1º de janeiro de 2022 a partir da propriedade OrderDate:
Como selecionar propriedades em retornos de API's com oData
O operador select permite que os clientes especifiquem uma lista de campos que devem ser incluídos na resposta da API. Isso é útil quando os clientes não precisam de todos os campos de uma entidade, mas apenas de um subconjunto específico. A cláusula $select é usada na URL da requisição para indicar os campos desejados.
Sintaxe do Operador select
selectA cláusula $select segue a seguinte estrutura:
fieldName1, fieldName2, fieldName3: Os nomes dos campos que se deseja incluir na resposta.
Exemplos de Uso
A seguir, apresentamos exemplos práticos de como usar o operador select com OData em diferentes casos de uso.
Seleção de Campos Específicos
Em uma API fictívia, para obter apenas os campos name e country de todos os clientes:
Como ordenar retornos de API's com oData
As operações de ordenação em OData permitem que os clientes especifiquem a ordem em que os resultados devem ser retornados. Isso é realizado usando a cláusula $orderby na URL da requisição. A sintaxe do OData permite a ordenação por um ou mais campos, tanto em ordem crescente quanto decrescente.
Sintaxe de Ordenação
A cláusula $orderby segue a seguinte estrutura:
fieldName: O nome do campo pelo qual deseja ordenar.asc: Ordem crescente (padrão).desc: Ordem decrescente.
Exemplos de Uso
A seguir, apresentamos exemplos práticos de como usar operações de ordenação com OData em diferentes casos de uso.
Ordenação por um Campo
Para ordenar dados por um único campo em ordem crescente, simplesmente especifique o nome do campo. Por exemplo, para obter todos os clientes ordenados pelo nome:
Para ordenar os clientes pelo nome em ordem decrescente:
Ordenação por Múltiplos Campos
É possível ordenar por múltiplos campos, separando-os por vírgulas. Por exemplo, para ordenar os clientes pelo país em ordem crescente e, dentro de cada país, pelo nome em ordem decrescente:
Como limitar o número de registros nos retornos de API's com oData
Essa propriedade não pode ser usada para tentar sobrescrever os limites de número de registros retornados em API's paginadas.
O operador $top permite que os clientes especifiquem o número máximo de registros a serem retornados na resposta de uma consulta, após os limites e filtros nativos já aplicados pela própria API.
Sintaxe do Operador $top
$topA cláusula $top segue a seguinte estrutura:
N: O número máximo de registros a serem retornados.
Exemplos de Uso
A seguir, apresentamos exemplos práticos de como usar o operador $top com OData em diferentes casos de uso.
Limitação de Resultados
Para obter apenas os 10 primeiros clientes:
Atualizado