O Magic xpi 4.7 traz um novo conector para interface com serviços OData, tanto como “consumidor” deste tipo de serviço, como “provedor“.
Vamos conhecer um pouco mais desta novidade.
Logo de início, é importante nos familiarizarmos com alguns conceitos básicos do OData (Open Data Protocol), conhecendo um site dedicado a este assunto: http://www.odata.org/.
De forma resumida: OData é um padrão (normatização) de interface para webservices REST. Uma das características dos webservices REST, em contraponto ao SOAP, é a sua total liberdade dos formatos de mensagens trocadas entre consumidores e provedores.
O OData vem trazer um pouco de ordem ao REST, definindo regras de como os dados devem ser formatados para os envios, para as respostas, e como ao acessos aos recursos REST devem ser realizados. E ele faz isso de forma similar a uma “linguagem de consulta estruturada” (SQL), o que certamente facilita a adoção do padrão.
O Magic xpi 4.7 oferece suporte ao OData v4, e como dissemos antes e também por se tratarem de webservices REST , existem as conhecidas figuras do “consumidor” e do “provedor” do serviço. O Magic xpi 4.7 pode fazer o papel de ambos.
Consumindo Serviços OData
Vamos neste primeiro post (parte 1), ver o funcionamento do Magic xpi 4.7 como um “cliente REST OData“.
Um novo conector está disponível na caixa de ferramentas do Magic xpi 4.7:
Curiosidade: O conector “OData”, assim como o “MQTT”, foi desenvolvido totalmente através do “Conector Builder” do Magic xpi, disponível desde a versão 4.5. Você pode conferir isso através da pasta: %magicxpi_root%Runtime\addon_connectors\
O primeiro passo para consumir um serviço REST OData com o Magic xpi 4.7 é termos ciência da uri onde este serviço é publicado.
Neste exemplo, vamos usar a uri de um serviço público disponível no próprio site http://www.odata.org/:
http://services.odata.org/V4/Northwind/Northwind.svc/
Iniciamos pela definição de um novo recurso no projeto Magic xpi, do tipo “OData“:
E após a informamos a uri do serviço desejado, clicamos no botão “Get Metadata“:
NOTA: O “metadata” de um serviço REST OData é muito semelhante a um WSDL de um serviço SOAP. É uma estrutura EDMX que descreve o serviço: o que ele espera receber e o que ele está disposto a retornar. Enquanto o padrão para o SOAP é adicionarmos um “?wsdl” na uri do serviço, para obtermos o WSDL, por padrão no REST OData adicionamos um “$metadata” na uri (ex: http://services.odata.org/V3/Northwind/Northwind.svc/$metadata), para obter este descritivo do serviço. No Magic xpi contudo, só informamos a uri base (root). O Magic xpi adiciona automaticamente o “$metadata” ao final dela, quando clicamos em “Get Metadata“.
Executado este passo, que é obrigatório, podemos conferir na pasta do nosso projeto Magic xpi que foi criada uma subpasta chamada “OData\<Nome_do_Recurso>” e lá dentro há um arquivo chamado “metadata.xml” descrevendo todos os recursos e funcionalidades providos por este serviço.
Podemos também clicar no botão “Entities” e consultar todas as entidades que são publicadas por este serviço:
Finalizada esta etapa de parametrização, o consumo (chamada) efetivamente do serviço é feito através da configuração do conector OData na área de fluxo do projeto:
Headers: Caso o serviço exija algum cabeçalho HTTP específico para o seu funcionamento (esta informação tem de ser disponibilizada pelo responsável pelo serviço publicado), podemos definí-lo aqui através de um expressão Magic xpi (ou usar o assistente […] para montagem automática desta expressão).
Method: Devemos selecionar o “verbo HTTP” que desejamos usar neste acesso ao serviço (GET, PUT, POST, DELETE, etc…). Esta lista é montada com base nos valores possíveis que o “metadata” do serviço informou.
Entity: Devemos usar o assistente […] para selecionar a entidade para a qual desejamos invocar o método escolhido. Esta lista é montada com base nos valores possíveis que o “metadata” do serviço informou.
Parameters: Esta é uma configuração muito importante nos serviços REST OData. Ela define as regras que o cliente está fornecendo ao provedor do serviço. Por exemplo:
?$top=20&$filter=contains(ProductName,''<!?ProductName?!>'')&$orderby=ProductName&$select=ProductID,ProductName,SupplierID,CategoryID,QuantityPerUnit,UnitPrice,UnitsInStock,UnitsOnOrder,ReorderLevel,Discontinued&$expand=Category
Estes parâmetros dizem que deve ser retornada, para a entidade “Products”, uma coleção com as 20 primeiras ocorrências que contenham um valor “X” (aqui representado por <!?ProductName?!>) dentro de “ProductName”, em ordem ascendente de “ProductName”. Cada item da coleção deve conter os atributos “ProductID, ProductName, SupplierID, CategoryID, QuantityPerUnit, UnitPrice, UnitsInStock, UnitsOnOrder, ReorderLevel e Discontinued” e também devem ser retornados itens da entidade “Category” que se relacionem com os itens de “Products” que estão nesta coleção.
NOTA: Se você viu semelhança com uma linguagem SQL, você entendeu o espírito do OData.
Felizmente para nós, o Magic xpi 4.7 possui um assistente ( […] ) para nos ajudar a montar todos estes parâmetros da operação que estamos querendo fazer. Vejamos (com base no method escolhido: GET):
Restrictions
Definimos o nro máximo de itens a retornar na coleção (se não gostar de nenhuma das opções, basta remover esta regra depois).
Where
Definimos filtros a serem aplicados nos dados originais, afim de restringer a coleção de itens retornados
Column Selection
Dos atributos disponíveis na entidade escolhida, selecionamos os que queremos receber.
Expand
Uma das coisas que o “metadata” do serviço REST OData faz, é explicar os relcionamentos (quando existem) entre as entidades. O “expand” serve para definirmos quais entidades relacionadas com a entidade principal (child objects) devem ser incluídas na coleção retornada pelo serviço.
Order
Podemos também escolher a ordem dos itens dentro da coleção retornada.
Concluindo o assistente do Magic xpi, é produzida a expressão final a ser enviada ao serviço, que será adicionada ao final da sua uri.
Como a expressão usada em “parameters” inclui uma ou mais variáveis do Magic xpi 4.7, nesta caso a “<!?ProductName?!>”, já na sequência é aberto um assistente de DataMapper para podermos definir as regras e condições de preenchimento destas variáveis durante a execução do conector pelo Magic xpi Server:
Neste exemplo, definimos que ‘m’ é o que precisa estar contido dentro de “ProductName” para que o item seja incluído na coleção retornada.
Por fim, faz parte da especificação de um webservice REST OData que alguma informação seja retornada.
E nós precisamos lê-la.
Podemos conferir na pasta do nosso projeto Magic xpi que foi criada uma subpasta chamada “OData\<Nome_do_Recurso>\schema” e lá dentro há um esquema xml (XSD) para cada entidade que escolhemos trabalhar no projeto:
Desta forma, com um DataMapper podemos facilmente ler e processar o conteúdo da coleção retornada pelo serviço:
Concluímos assim, esta demonstração da facilidade e versatilidade do Magic xpi 4.7 em consumir serviços REST OData.
Se você deseja ver o protótipo do projeto Magic xpi usado neste post, basta baixá-lo deste endereço aqui.
No próximo post (parte 2), abordaremos a atuação do Magic xpi 4.7 como um “provedor REST OData“.
Para receber os artigos do Blog Magic Brasil em primeira mão no seu email registre-se aqui