APIs

Tutorial de uso das APIs de Entidade com filtros - OData

402 views 26/03/2020 01/06/2020 sergio-souza 1

Tutorial de uso das APIs de entidade com filtros – OData

O OData, Open Data Protocol, é um protocolo aberto que permite a criação e consumo de APIs RESTful de maneira simples e padrão. As APIs de entidade na Senior, atualmente, utilizam apenas parte do Query Data. Mais especificamente, as opções filter e orderby.

Para consumir as APIs de entidade é necessário seguir os padrões:

  • Método HTTP GET
  • E URL https://api.senior.com.br/{dominio}/{serviço}/entities/{nomeDaEntidade}

Obs.: Caso a entidade exija autenticação, é necessário incluir no HTTP Header o “Authorization: Bearer {access-token}”. Para obter o access-token, favor consultar o Tutorial da API Authentication.

Opção filter

Ao efetuar uma chamada para uma entidade, por padrão, são retornados todos os registros da entidade. Porém, com o OData, é possível restringir os registros retornados, utilizando o parâmetro filter. O exemplo abaixo retornará todos os registros da entidade visitType (tipos de visita), do domínio sam, serviço lobby, cujos ids sejam maior que 2 e menor que 5, ou seja, os registros com id igual a 3 e 4.

https://api.senior.com.br/sam/lobby/entities/visitType?filter=id gt 2 and id lt 5

Abaixo é mostrada uma tabela contendo os operadores e funções suportados pela busca com filtro:

Operador Descrição Exemplo
eq = (igual) filter=id eq 10
ne <> (diferente) filter=id ne 10
lt < (menor que) filter=id lt 10
gt > (maior que) filter=id gt 10
le <= (menor ou igual) filter=id le 10
ge >= (maior que) filter=id ge 10
is Verifica se parâmetro é nulo filter=id is null
containing Contendo valor da direita no atributo da esquerda filter=containing(name, 'albert')
lower Função de caixa baixa filter=containing(lower(name), lower('Albert'))
and E filter=id eq 10 and status eq 'y'
or Ou filter=id eq 10 or id eq 20

Observações:

  • Podem ser utilizados parênteses entre as expressões.
  • Caso utilize alguma função (com exceção da função containing), o nome da função deve ser exatamente o mesmo nome da função suportada pelo banco de dados, como por exemplo lower.
  • Dependendo da entidade e do atributo filtrado, o desempenho da consulta poderá ser afetado. Caso a consulta fique lenta, tente rever o formato de filtro utilizado.
  • A função containing suporta apenas valores string no segundo parâmetro, o valor deve ser precedido e seguido por aspas simples.
  • Com exceção da função containing, outras funções de banco de dados podem ser utilizadas, porém somente são suportados funções com apenas um parâmetro, exemplo: ?filter=lower(trim(customerName)) eq lower(trim(‘ marie curie ‘)) ou ?filter=trunc(total) ge round(2589.45).
  • Caso existir aspas simples (apóstrofo) no meio da busca, deve-se colocar a contra barra, exemplo: ?filter=nome eq ‘Caixa d\’água’.
  • São suportados até quatro níveis de entidades encadeadas para filtros. Ex.: ?filter=objNivel2.objNivel3.objNivel4.id eq ’93eab564-0d3c-4e1a-b2ab-5dc293e5deb5′.

 

Abaixo é apresentada uma tabela contento exemplos de filtros e os tipos de campos suportados:

Campo da entidade: tipo Exemplo
stringField: string filter=stringField eq 'this is a plane text'
booleanField: boolean filter=booleanField eq true
integerField: integer filter=integerField ge 12345
doubleField: double filter=doubleField eq 5890.159
dateField: date filter=dateField eq '2018-04-04'
timeField: time filter=timeField eq '12:40:38'
dateTimeField: dateTime filter=dateTimeField eq '2018-04-04T12:40:38.155Z'
moneyField: money filter=moneyField gt 1234567890.098
enumField: fruit filter=enumField eq APPLE
uuidField: uuid filter=uuidField eq 'a9abe17c-ac41-43bf-9d35-52cb8034d486'
binaryField: binary Não suportado

 

Opção orderby

Com o orderby é possível definir a ordem em que os registros de uma entidade devem ser retornados. Pode ser feito com qualquer campo do retorno, até quatro níveis. E por padrão a ordenação é sempre em ordem crescente. Caso haja a necessidade de ordenar em ordem decrescente, basta adicionar um espaço em branco e o termo desc após o nome do atributo. Como demonstramos no exemplo abaixo, que retornará todos os registros de tipos de visita ordenados pelo nome em ordem decrescente:

https://api.senior.com.br/sam/lobby/entities/visitType?orderby=name desc

Também é possível filtrar e efetuar a ordenação por mais de um campo, basta separá-los por vírgula:

https://api.senior.com.br/sam/lobby/entities/visitType?filter=containing(lower(name), ‘ de ‘)&orderby=name desc,id

 

Opções adicionais

Essas opções são extras, não fazem parte do OData, mas que visam facilitar o desenvolvimento.

Size e Offset

Essas duas opções estão relacionadas a quantidade de registros por página (size) e o número da página a ser recuperada (offset), lembrando que a numeração de página começa em 0 (zero).

No exemplo abaixo temos um exemplo de consulta, para retornar 2 registros na página 1, ordenado pelo nome.

https://api.senior.com.br/sam/lobby/entities/visitType?size=2&offset=0&orderby=name

Displayfields

Com o displayfields é possível informar quais campos da entidade devem ser retornados pela API, visto que, por padrão, são retornados todos os campos da entidade. Essa opção permite reduzir o tamanho da resposta. Para isso basta informar os campos separados por vírgula, conforme exemplo abaixo:

https://api.senior.com.br/sam/lobby/entities/visitType?displayfields=id,name

Este artigo foi útil para você?