# 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 ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://kb.stoque.com.br/zeev/apis/como-utilizar-as-apis-do-zeev/como-realizar-filtros-e-manipulacoes-adicionais-nas-apis-com-odata.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.