Como executar queries OData sobre os dados?

O que é o OData

O OData (Open Data Protocol) é um protocolo standard que permite a criação e consumo de dados através de uma Web API.

Trate-se de um standard construído sobre os protocolos HTTP e REST e que suporta operações CRUD sobre as entidades disponíveis na Web API.

Dadas as suas características, este protocolo é particularmente útil para executar queries ad-hoc sobre esses dados.

Mais informação: http://www.odata.org/

OData

Os serviços OData disponibilizados no Jasmin permitem consultar as entidades do Jasmin a partir de aplicações externas, nomeadamente, os seus atributos, valores correspondentes e entidades relacionadas.

O OData permite que esta consulta possa ser efetuada de uma forma mais ágil e customizada pois permite a utilização de parâmetros para obter os resultados pretendidos.

Parâmetros para as consultas OData

As consultas OData, não são mais do que a execução de ações GET na Web API, com determinados parâmetros que condicionam os resultados obtidos.

De seguida são apresentados os parâmetros que podem ser utilizados nas consultas OData, bem como exemplos da sua aplicação na Web API do Jasmin.

Dica: Sempre que referencia propriedades em expressões OData, deverá ser utilizada a convenção Pascal Case (primeira letra de cada palavra em maiúscula)

$TOP

Permite definir o número de resultados pretendidos.

Exemplo:

Para obter os 5 primeiros resultados da lista de artigos de venda:

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$top=5

$SKIP

Permite ignorar os N primeiros resultados de uma query.

Exemplo:

Para obter 5 registos da lista de artigos de venda, ignorando os 5 primeiros:

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$skip=5

$INLINECOUNT

Permite incluir um totalizador dos registos nos resultados da query.

Exemplo:

Para obter o total dos registos existentes na lista de artigos de venda:

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$inlinecount=allpages

$ORDERBY

Permite ordenar, de forma ascendente ou descendente, os resultados por um ou mais atributos.

Exemplo:

Para obter os registos existentes na lista de artigos de venda, ordenando pelo atributo "ItemKey" de forma descendente:

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$orderby=ItemKey desc

$SELECT

Permite selecionar quais os atributos a serem apresentados nos resultados devolvidos pela query.

Exemplo:

Para obter os atributos "ItemKey" e "Description" dos registos existentes na lista de artigos de venda:

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$select=ItemKey,Description

$EXPAND

Permite expandir a consulta a entidades relacionadas com a entidade da pesquisa, por exemplo, quando se pretende selecionar atributos de um detalhe. Este parâmetro só pode ser utilizado associado ao parâmetro $SELECT.

Exemplo:

Para obter os atributos "ItemKey" e "Description" dos registos existentes na lista de artigos de venda e ainda o atributo "PriceAmountAmount" dos detalhes:

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$select=ItemKey,Description,PriceListLines/PriceAmountAmount&$expand=PriceListLines

$FILTER

Permite filtrar os resultados com base em determinadas condições, nomeadamente as seguintes:

EQ (Equal)

Para obter os registos em que o atributo "ItemKey" seja igual a "PORTES":

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$filter= ItemKey eq 'PORTES'

AND

Para obter os registos em que o atributo "ItemKey" seja igual a "PORTES" e o atributo "Unit" seja igual a "UN":

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$filter= ItemKey eq 'PORTES' and Unit eq 'UN'

OR

Para obter os registos em que o atributo "Unit" seja igual a "UN" ou "KG":

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$filter= Unit eq 'UN' or Unit eq 'KG'

LT (LESS THAN)

Para obter os registos em que o atributo "ItemKey" seja menor que "0010":

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$filter= ItemKey lt '0010'

GT (GREATER THAN)

Para obter os registos em que o atributo "ItemKey" seja maior que "0010":

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$filter= ItemKey gt '0010'

GE (GREATER THAN OR EQUAL TO)

Para obter os registos em que o atributo "ItemKey" seja maior ou igual a "0010":

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$filter= ItemKey ge '0010'

LE (LESS THAN OR EQUAL TO)

Para obter os registos em que o atributo "ItemKey" seja menor ou igual a "0010":

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$filter= ItemKey le '0010'

STARTWITH

Para obter os registos em que o atributo "ItemKey" comece por "POR":

http://my.jasminsoftware.com/api/{account}/{subscription}/salescore/salesitems/odata?$filter= startswith(ItemKey , 'POR')

SUBSTRINGOF

Para obter os registos em que valor ‘cadeira’ seja parte da string do atributo "Description":

http://my.jasminsoftware.com/api/{account}/{subscr

Conjugação de parâmetros

Os parâmetros referidos anteriormente podem ser conjugados para facilitar as pesquisas. De seguida são apresentados alguns exemplos práticos.

Exemplo:

Para obter os atributos "CustomerPartyName" e "SeriesNumber" dos registos existentes na lista de encomendas, ordenados de forma descendente pelo atributo "SeriesNumber", bem como do contador de registos que correspondem aos critérios de pesquisa:

http://my.jasminsoftware.com/api/{account}/{subscription}/sales/orders/odata?$inlinecount=allpages&$select=BuyerCustomerPartyName,SeriesNumber&$orderby=SeriesNumber desc

Para obter os atributos "BuyerCustomerPartyName" e "PayableAmountAmount" para as 10 encomendas de maior valor, apresentadas do valor mais alto para o mais baixo, bem como do contador de registos que correspondem aos critérios de pesquisa:

http://my.jasminsoftware.com/api/{account}/{subscription}/sales/orders/odata?$inlinecount=allpages&$select=BuyerCustomerPartyName,PayableAmountAmount&$top=10&$orderby=PayableAmountAmount desc