ASP.NET Web API e OData: Como criar filtros e ordena��o

O que � OData?

OData (Open Data Protocolo) � um protocolo criado pela Microsoft para facilitar a criaç�o e consumo de web services RESTful. Seu objetivo � definir padr�es de como os serviços devem funcionar, a fim de permitir que os clientes os consumissem com facilidade, uma vez que estar�o lidando com uma aplicaç�o que segue uma padronizaç�o amplamente utilizada.

Por exemplo, esse protocolo define como deve ser a URL para realizaç�o de certas operaç�es, como filtros e ordenaç�o. Neste exemplo instalaremos um pacote via NuGet para implementar esses recursos de consulta seguindo o padr�o OData.

Instalaç�o do pacote

Neste exemplo partimos de um projeto ASP.NET Web API previamente criado e instalamos nele o pacote Microsoft.AspNet.WebApi.OData. Para isso utilizamos o NuGet e os passos executados s�o ilustrados na sequ�ncia de imagens abaixo:

#PraCegoVer - Transcriç�o dos Slides Passo 1: Clicar com a direita em References / Manage Nuget Packages
Passo 2: Pesquisar por OData e instalar o pacote Microsoft.AspNet.WebApi.OData
Passo 3: Clicar em I Accept na tela que se abrir�
Final: Pacote instalado juntamente com suas depend�ncias

Habilitando as funcionalidades

Na sequ�ncia, para habilitar as operaç�es de filtro, ordenaç�o, etc. em nosso controller precisamos importar o seguinte namespace:

using System.Web.Http.OData;

Em seguida basta adicionar o atributo [EnableQuery] na action respons�vel pela listagem de registros:


  [EnableQuery]
  public IQueryable<Vaga> GetVagas()
  {
                  return db.Vagas;
  }

Aqui � importante destacar que o m�todo que receber esse atributo deve retornar uma coleç�o do tipo IQueryable.

A partir de agora esse m�todo j� � capaz de tratar as operaç�es de consulta do OData, que ser�o destacadas a seguir.

Operaç�es do OData

Por padr�o o m�todo GetVagas � o respons�vel por tratar requisiç�es GET na URL http:///api/vagas e retorna todos os objetos do tipo Vaga contidos no banco. A partir do momento que adicionamos a ele o atributo [EnableQuery] somos capazes de efetuar operaç�es de consulta complexas passando alguns par�metros:

/api/vagas?$filter=filtro: aplica filtros diversos seguindo do protocolo OData. Na Tabela 1 temos alguns exemplos de filtro que podem ser aplicados.

$filter=Propriedade eq Valor	Registros cuja �Propriedade� seja igual a �Valor�.
$filter=Propriedade gt Valor	Registros cuja �Propriedade� seja maior que (greater than) �Valor�.
$filter=Propriedade lt Valor	Registros cuja �Propriedade� seja menor que (less than) �Valor�.
$filter=substring(�Valor�, Propriedade)	Registros cuja �Propriedade� contenha o texto �Valor�.

Tabela 1. Exemplos de Filtros

A lista completa de operadores dispon�veis pode ser encontrada na documentaç�o oficial do OData.

/api/vagas?$orderby=propriedadades: ordena o resultado a partir de uma ou v�rias propriedades, de forma crescente ou decrescente. Na Tabela 2 temos exemplos de ordenaç�o.

$orderby=Salario	Ordena pelo campo SalarioInicial de forma crescente.
$orderby=Salario, Id desc	Ordena pelo campo SalarioInicial de forma crescente e pelo campo Id de forma decrescente.

Tabela 2. Exemplos de ordenaç�o

/api/vagas?$select=propriedades: define quais campos devem ser retornados no registro. Essa opç�o � particularmente �til para aplicaç�es clientes que n�o precisam listar todos os dados do resultado na requisiç�o. Para isso, � poss�vel escolher apenas os campos que s�o �teis em cada contexto. Abaixo temos um exemplo de uso desse par�metro:

$select=Titulo, Salario Lista apenas os campos Titulo e Salario.

Limitando as operaç�es suportadas

Quando adicionamos o atributo [EnableQuery] no m�todo ele passa a suportar todas as operaç�es do OData. No entanto, nem sempre queremos liberar tantas opç�es para os clientes. Nesses cen�rios podemos limitar as operaç�es suportadas.

Para isso, o primeiro passo � importar o seguinte namespace:

using System.Web.Http.OData.Query;

Em seguida, basta especificar o argumento AllowedQueryOptions no atributo:


  [EnableQuery(AllowedQueryOptions = AllowedQueryOptions.Filter |
                                   AllowedQueryOptions.OrderBy |
                                    AllowedQueryOptions.Select)]
  public IQueryable<Vaga> GetVagas()
  {
         return db.Vagas;
  }

Agora apenas as operaç�es de filtro, ordenaç�o e seleç�o ser�o suportadas.

Sugest�o de conte�do

Para ver um web service completo em que utilizamos o OData para realizar consultas, confira o exemplo abaixo:

Web service RESTful com CRUD, filtros e ordenaç�o usando ASP.NET Web API