Como utilizar OData para obter uma lista de encomendas?

O exemplo de utilização da Web API ilustra a utilização da API para obter a lista de encomendas disponíveis no sistema, de forma filtrada, com recurso a OData.

O código apresentado foi desenvolvido em C# para uma aplicação de consola está disponível no repositório de exemplos de código.

Este exemplo utiliza os pedidos à WebAPI Jasmin. Para o Rose poderá ser necessário ajustar propriedades da entidade.

AccountKey e SubscriptionKey

Em primeiro lugar é necessário definir no código estes dois dados requeridos pela Web API. No exemplo, usamos duas constantes para o efeito que serão utilizadas no URL dos pedidos.

private const string AccountKey = "XXXXX"; // TODO: put your account key here
private const string SubscriptionKey = "XXXXX-XXXX"; // TODO: put your account key here

Access token

Para aceder à Web API também é necessário o token de autorização associado ao utilizador e à subscrição. Mais uma vez, no exemplo, usamos uma constante para armazenar o seu valor.

private const string AccessToken = "XXXX"; // TODO: put the authorization access token here (this should be obtained previously)

HttpClient

Para fazer chamadas a uma Web API REST em C# pode utilizar-se a classe System.Net.Http.HttpClient.

using (HttpClient client = new HttpClient())
{
    (…)
}

Configuração do access token

Os pedidos à Web API requerem sempre o access token anterior. Deve ser incluído nos headers do pedido.

client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", AccessToken);

Dados da encomenda

No caso do endpoint de consulta de encomendas com recurso a filtros OData, os dados da encomenda serão devolvidos no corpo da mensagem do resultado em JSON.

Para o efeito, criamos uma classe C# muito simples que inclui apenas os atributos da encomenda necessários para o exemplo.

internal class OrderResource
{
    #region Internal Properties
  
    public Guid Id
    {
        get;
        set;
    }
    public string DocumentType
    {
        get;
        set;
    }
    public string Serie
    {
        get;
        set;
    }
    public int SeriesNumber
    {
        get;
        set;
    }
    public string Company
    {
        get;
        set;
    }

    #endregion
}

Execução do pedido

De seguida, a chamada à Web API pode ser executada usando o endpoint correto. Note-se que o verbo é um GET e que a resposta é devolvida num tipo IDisposable HttpResponseMessage.

// URI of the endpoint

string endpoint = string.Format(CultureInfo.CurrentCulture, "{0}/{1}/{2}/sales/orders", ApiBaseAddress, AccountKey, SubscriptionKey);

// Send the request (GET)

Uri endpointUri = new Uri(endpoint);
using (HttpResponseMessage response = await client.PostAsync(endpointUri, content))
{
    (…)
}

Tratamento da resposta

O endpoint pode devolver dois tipos de respostas: sucesso ou erro. No caso de sucesso, o corpo inclui a lista de encomendas, de acordo com os filtros OData aplicados. Em caso de erro, o resultado incluirá uma mensagem de erro, dependendo do erro.

// Failed?

if (!response.IsSuccessStatusCode)
{
    string errorContent = await response.Content.ReadAsStringAsync();
    StringBuilder sb = new StringBuilder();
    sb.AppendLine(string.Format(CultureInfo.CurrentCulture, "The requested failed with status code {0} ({1}).", (int)response.StatusCode, response.StatusCode));
    if (!string.IsNullOrWhiteSpace(errorContent))
    {
        sb.Append(string.Format(CultureInfo.CurrentCulture, "Message: {0}.", errorContent));
    }

    throw new InvalidOperationException(sb.ToString());
}

// Succeeded

string json = await response.Content.ReadAsStringAsync();
JsonSerializerSettings settings = new JsonSerializerSettings()
{
  ContractResolver = new CamelCasePropertyNamesContractResolver(),
  Formatting = Formatting.Indented
};

PageResult orders = JsonConvert.DeserializeObject(json);
Console.WriteLine("The orders attributs were obtained with success.");
foreach (OrderResource order in orders)
{
  Console.WriteLine("Order: {0}.{1}.{2}", order.DocumentType, order.Company, order.SeriesNumber);
}

Console.WriteLine("Count: {0}", orders.Count);

É assim tão simples obter os atributos pretendidos, de acordo com os filtros aplicados, à lista de encomendas com a utilização de OData na Web API.