> For the complete documentation index, see [llms.txt](https://kb.stoque.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.stoque.com.br/zeev/apis/como-utilizar-as-apis-do-zeev/como-realizar-filtros-e-manipulacoes-adicionais-nas-apis-com-odata.md). # Como realizar filtros e manipulações adicionais nas API's com oData ## 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: * [Realizar filtros adicionais sobre os dados retornados por uma API;](#como-filtrar-retornos-de-apis-com-odata) * [Limitar os campos retornados por uma API;](#como-selecionar-propriedades-em-retornos-de-apis-com-odata) * [Modificar a ordenação do retorno de uma API;](#como-ordenar-retornos-de-apis-com-odata) * [Limitar o número de registros retornados de uma API;](#como-limitar-o-numero-de-registros-nos-retornos-de-apis-com-odata) ## 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: ```json { "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 {% hint style="warning" %} Sempre prefira e utilize os métodos de filtro da própria API. Por exemplo, a API de [Listar pessoas](/zeev/apis/all/access/people/list.md)possui, 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. {% endhint %} 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 {% embed url="" %} 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`: ```bash GET /Customers?$filter=country eq 'Brasil' ``` Ou, no caso abaixo, para obter todos os clientes que estejam ativos a partir da propriedade `isAtive`: ```bash GET /Customers?$filter=isActive eq true ``` **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`: ```bash GET /Customers?$filter=country ne 'Brasil' ``` **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`: ```bash GET /Products?$filter=price gt 100 ``` Ou para obter produtos cujo preço esteja entre 50 e 150: ```bash GET /Products?$filter=price ge 50 and price le 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`: ```bash GET /Customers?$filter=substringof('Rafael', 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": ``` GET /Users?$filter=contains(toupper(name), toupper('{Form.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: ```bash GET /Products?$filter=price lt 50 or stock gt 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`: ```bash GET /Orders?$filter=orderDate gt datetime'2022-01-01T00:00:00' ``` ## 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` A cláusula `$select` segue a seguinte estrutura: ```shell $select=fieldName1,fieldName2,fieldName3 ``` * `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 n`ame` e `country` de todos os clientes: ```bash GET /Customers?$select=name,country ``` ## 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: ```bash $orderby=fieldName [asc|desc] ``` * `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: ```bash GET /Customers?$orderby=name ``` Para ordenar os clientes pelo nome em ordem decrescente: ```bash GET /Customers?$orderby=name desc ``` **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: ```bash GET /Customers?$orderby=country, name desc ``` ## Como limitar o número de registros nos retornos de API's com oData {% hint style="warning" %} Essa propriedade não pode ser usada para tentar sobrescrever os [limites de número de registros retornados em API's paginadas](/zeev/apis/como-utilizar-as-apis-do-zeev/como-navegar-entre-paginas-de-retornos-de-apis.md). {% endhint %} 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` A cláusula `$top` segue a seguinte estrutura: ```bash $top=N ``` * `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: ```bash GET /Customers?$top=10 ```