Utilizando a API RestFul dos modelos de dados do ERP Protheus

Após algum tempo sem realizar postagens devido as correrias do dia-a-dia, voltamos a falar sobre o tema webservice REST no ERP Protheus.

Sugerimos que vocês (nosso público) fizessem-nos solicitações de postagens que achem interessantes. Seguindo a maioria das solicitações, nessa postagem iremos realizar uma abordagem muito interessante… A utilização do webservice REST com o modelo de dados (vulgo MVC) do ERP Protheus.

Para que consiga acompanhar o exemplo da postagem, sugiro que confira a postagem que a Ju escreveu no link que será disponibilizado logo abaixo. Pois será com base nessa publicação que daremos continuidade.

Link: https://mvcadvpl.wordpress.com/2017/04/10/hello-word/

 

Pessoas, sugiro que prestem bastante atenção nos detalhes da escrita do POST, pois é uma funcionalidade extremamente útil para nós desenvolvedores e que demanda de apenas uma única linha de código …

É isso mesmo, você não leu errado, teremos apenas uma linha de código para ativarmos a funcionalidade.

Então … bora lá!

Premissas:

  • Possuir um ambiente parametrizado para a utilização de webservice REST (conforme demonstrado na postagem xxx);
  • Possuir conhecimento básico em MVC;
  • Conforme citado acima, irei utilizar um programa em MVC que a Ju desenvolve, logo, para conseguir acompanhar essa postagem, também é uma premissa que tenha esse projeto compilado em seu ambiente.

Após as premissas acimas estiverem “ok”, vamos criar o nosso programa que publicará “on-air” a nossa API baseada em um modelo de dados, abaixo segue o código:

#Include ‘Protheus.ch’

#Include ‘Parmtype.ch’

#Include “FWMVCDEF.CH”

PUBLISH USER MODEL REST NAME Aluno SOURCE CMVC_01

Eu menti, quando disse acima que teríamos 1 única linha de código, havia me esquecido dos “headers files” ou mais conhecidos como “.ch”.

Tirando a parte dos includes, onde creio que a maioria já conheça ao menos um pouco de sua funcionalidade, vamos entender o trecho abaixo.

PUBLISH USER MODEL REST NAME <nome> source <fonte> RESOURCE OBJECT <objeto>

Esse é o trecho que irá disponibilizar a nossa API “on-air”.

Entendendo a diretiva de compilação:

Logo após o comando PUBLISH USER MODEL REST NAME temos a “tag” <nome>, essa tag deverá ser preenchida com o nome da sua API, por exemplo:

O nosso modelo de dados é responsável por realizar um CRUD de Alunos, logo o nome da minha API será “Aluno”.

Antes de entendermos os próximos trechos da diretiva de compilação, é importante saber que temos 2 formas diferentes de configurar a nossa API.

  • A primeira é possuir o modelo de dados em um único fonte (prw) e a publicação em outro;
  • A segunda é possuir tanto o modelo de dados, quanto a publicação no mesmo fonte (prw).

A primeira forma é a que iremos utilizar neste exemplo, onde, o nosso modelo de dados está em um programa diferente do programa de publicação da API, para que a API seja publicada dessa maneira, as diretivas de compilação devem ser aplicadas da seguinte forma:

PUBLISH USER MODEL REST NAME <nome> source <fonte>

Conforme visto acima, iremos substituir a tag <nome>, pelo nome da nossa API e adicionamos o seguinte o trecho:

source <fonte>

A tag <fonte>, deverá ser substituída pelo nome do programa onde está o modelo de dados, no nosso caso é o CMVC_01.

A segunda forma é quando possuímos o modelo e a publicação no mesmo fonte. Nesse caso a diretiva de compilação deve ser aplicada da seguinte maneira

PUBLISH USER MODEL REST NAME <nome> RESOURCE OBJECT <objeto>

Conforme visto acima, iremos substituir a tag <nome>, pelo nome da nossa API e adicionamos o seguinte temos o trecho:

RESOURCE OBJECT <objeto>

A tag <objeto> deverá ser substituída pelo objeto da model.

Na TDN temos um exemplo bem demonstrado desse caso, por isso não irei entrar em detalhes (TDN Api RestFul).

Após compilado no RPO, vamos testar a utilização da nossa funcionalidade.

Para API’s do modelo de dados do ERP, o link de acesso fica da seguinte maneira:

<servidor:porta>/<URI>/FwModel/<nome_da_API>/<PK>

Entendendo a URL acima:

  • <servidor:porta> : Servidor + porta no qual está configurador o servidor HTTP do webservice REST.
  • <URI> : URI configurada no ini do AppServer do webservice REST dentro da seção HTTPURI:
  • FwModel: Default
  • <nome_da_API>: Nome da API definido na tag <nome> na diretiva de compilação de publicação do REST.
  • <PK>: Primary Key, para realização de filtros em operações do tipo GET, PUT, DELETE.

 

ATENÇÃO!!!

  • A chave PK deverá ser informada no formato ENCODE64.
  • A chave PK deverá ser a chave da tabela principal do modelo

 

Agora vamos testar a nossa aplicação:

No meu caso, o link para consumo da API ficou o seguinte:

http://localhost:8012/rest/fwmodel/ALUNO

E caso você tenha acompanhado as outras postagens, creio que o seu esteja parecido.

Através da ferramenta POSTMAN, se fizermos um GET nessa URL, teremos o retorno de todos os “Alunos” cadastrados na nossa base de dados:

IMG_1

Conforme a imagem acima, temos diversos registros na base de dados. Podemos conferir através da tag total.

Segue abaixo um exemplo de uma requisição GET de um registro específico, ou seja, informando a PK:

IMG_2

Podemos ver que só foi retornado o registro de parâmetro informado na URL.

Aparentemente é um código bem estranho de diferenciar, mas utilizando alguns sites da internet ou até mesmo funções do framework ADVPL, conseguimos gerar a chave para execução de testes.

Para realizarmos a inclusão de um novo registro utilizando a nossa API que está referenciando um modelo de dados existente no ERP, basta:

  • Utilizar a mesma estrutura do JSON retornado na requisição GET;
  • Apagar a PK da URL;
  • Alterar os dados da requisição para os dados desejados
  • Excluir a tag pk do body
  • Modificar a tag operation para o conteúdo 3.

Abaixo o exemplo de uma requisição do tipo POST, porém com dados de uma PK existente:

IMG_3

Repare que é retornado um erro de validação, pois já existe algum registro com aquela informação.

O ponto que nos chama atenção nesse caso é que não escrevemos nenhuma linha de código para validação, o retorno está vindo direto da rotina que referenciamos quando montamos o nosso programa de publicação da API.

Abaixo irei alterar o body de requisição, para realizarmos a inclusão do registro no ERP Protheus:

IMG_4

Repare que a execução do método foi concluída com sucesso. Para conferir, vamos acessar diretamente na tela do ERP:

IMG_5

Abaixo um exemplo da execução do método PUT, onde para sua execução:

  • Foi informado a PK para posicionamento no registro através da URL;
  • Alterado a tag operation para o conteúdo 4;
  • Alterado o conteúdo no body de requisição para o novo conteúdo que desejamos que seja gravado no ERP:

IMG_6

No exemplo acima, foi alterado o registro incluído anteriormente. Ao executar a requisição acima no POSTMAN, deverá ser atualizado o registro no ERP:

IMG_7

Por fim… A execução do método DELETE para realizar a exclusão de registros:

Para execução do método DELETE, basta enviar uma requisição do tipo DELETE e informar na URL a PK para posicionamento do registro:

IMG_8

Se conferirmos no ERP, o registro deverá estar com o status de excluído:

IMG_9

Pessoal… Atenção para alguns detalhes:

Por ser uma funcionalidade relativamente nova, a API RestFul do ERP Protheus ainda não possui uma documentação bem exemplificada, logo, todas as conclusões e testes apresentados acima foram desenvolvidos por conta própria na base da “tentativa e erro”. Podendo existir maneiras mais simples para execução dos procedimentos descritos acima.

Espero que a postagem seja útil para vocês!

Victor Andrade.

Anúncios

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s