O Cronapp permite disponibilizar serviços REST por Bloco de programação ou Fonte de dados. Veremos a seguir como configurar nos dois casos.  E, ao final, mostraremos como obter esses recursos usando um programa externo ao Cronapp.

Pré-requisitos

1. Projeto do tipo mobile ou web criado. Caso , caso haja dúvidas de como criar esse tipo de projeto acesse o link ( Criar  criar projeto );
2. Criar classes no Diagrama, gerar persistência e popular o banco. Para Saber utilizar as funcionalidades do diagrama, como criar classes e gerar persistência, caso haja dúvidas acesse o link ( Diagrama ).
   Para esse exemplo vamos criar um agenda simples, link diagrama;
3. Saber criar um bloco de programação, caso haja dúvidas acesse o link bloco de programação;
4. Saber criar uma fonte de dados, caso haja dúvidas acesse o link fonte de dados.

Configurando o diagrama

Nesse tutorial vamos criar uma agenda simples utilizando um relacionamento de 1 para N, onde um cliente pode possuir vários telefones.

Vamos começar criando a classe Cliente com os atributos id (inteiro) e nome (Texto), em seguida, vamos adicionar a classe Telefone com os atributos id (inteiro), numero (Texto) e fixo (Lógico). Por fim, vamos adicionar o relacionamento 1 to N entre a classe Cliente e a classe Telefone.

Figura 1.1 - Relacionamento usado nesse exemplo

Passos

Configurando o relacionamento entre classes

Após configurar as classes e o relacionamento, vamos gerar a camada de persistência e as páginas CRUD.

Image Added

Figura 1.2 - Gerando o CRUD e a camada de persistência

1. Parar gerar a camada de persistência, vamos clicar no ícone (1 da Figura 1.2) e, na nova janela, clicar no botão Gerar;
2. Para gerar as páginas CRUD, vamos clicar com o botão direito do mouse sobre a entidade Cliente, selecionar Criar visão para a entidade (2) e escolher o modelo de formulário CRUD Web na nova janela. Vamos repetir o item 2 na entidade Telefone.

Via Bloco de programação

Crie Para configurar o serviço REST via bloco, vamos iniciar criando um bloco de programação do lado Servidor (Figura 2.1). Siga os passos abaixo.

Image Added

Figura 2.1 - Nova função de bloco de programação

1. Clique com o botão direito na pasta Servidor

1. e escolher Novo;
2. Em seguida, vamos clicar em Bloco de Programação;
3. Na janela Novo vamos selecionar Bloco de Programação Vazio (Low-code), clicar em Avançar, preencher os campos e clicar em Finalizar.
   • Nome do Arquivo: WebServiceREST;
   • Nome da Função: Cliente.

Configuração

Parâmetro REST

Vamos começar a configuração criando o parâmetro idCliente que retornará os dados de um cliente. Clique na engrenagem da função Cliente (Figura 2.2), arraste o bloco nome de entrada para dentro do bloco entradas e altere o nome da entrada para idCliente. Ele ficará disponível na categoria Variáveis.

Image Added

Figura 2.2 - Adicionando parâmetro de entrada à função

Agora arraste o bloco Abrir consulta (categoria Banco de dados) para que os dados sejam retornados, encaixe-o no retorno da função Cliente (Figura 2.3) e configure-o, conforme os passos abaixo.

Image Modified

Figura 2.1 - Nova função de 3 - Configurando o bloco de programação e consulta

Configuração do Bloco

1. Clique na engrenagem do bloco Abrir consulta;
2. Na janela Configurar Bloco de Programação:
   1. Selecione a entidade Telefone em "..." e clique em Adicionar;
   2. Adicione um Novo Campo e escolha a opção Obter t;
   3. Adicione uma Nova Regra e selecione t.cliente.id, o restante da expressão será preenchido de forma automática;
3. Clique em OK ao final;
4. Por fim, adicione a variável idCliente (categoria Variáveis) no parâmetro clienteId.

Propriedades do bloco

Após configurar o parâmetro REST, vamos alterar as propriedades do bloco. Vamos clicar na engrenagem Após criar a função, clique na engrenagem "Configuração dos tipos de regras" (lado direito/superior) para abrir a janela de "Propriedades do bloco de programação" (Figura 2.4). Nessa janela, é importante entender os únicos campos que nos interessam estão descritos abaixo . (e, após entendê-los, seguir para os passos abaixo da Figura 2.2)4:

• Tempo limite: limite em segundos para a execução. Após o limite, a ação é finalizada.
• Tipo: define o tipo de permissão para acesso ao bloco, sendo dois tipos:
  1. Interno: o bloco só é consumido dentro do no projeto;
  2. Externo: permite que o bloco seja também consumido fora do projeto;
• Endereço REST: trecho final do endereço do serviço REST, será concatenado após o domínio do sistema;
• Segurança: Abre uma outra janela que nos permite dar autorização de CRUD e Execução aos permissionáveis do sistema.

• .

Image Modified

Figura 2.2 4 - Configuração da chamada REST

Finalizada a configuração do bloco, podemos obter parâmetros por REST ou Query String. Usaremos nesse tutorial a opção REST, porém mostraremos também como obter por Query String.

Parâmetro REST

Para obter o parâmetro dessa forma, basta clicar sobre a engrenagem do bloco Função (destaque 1 da Figura 2.3), arrastar e nomear o bloco nome de entrada. Nesse tutorial só precisaremos de um parâmetro, por isso, arraste um bloco e nomeio para "idC" (identificador do Cliente). Podemos adicionar quantos parâmetros forem necessários, eles ficarão disponíveis no menu lateral Variáveis (destaque 2 da Figura 2.3).

Image Removed

Figura 2.3 - Adicionando parâmetros de entrada à função

Ao utilizar parâmetros Rest, não é necessário que o requerente saiba o nome exato dos parâmetros, porém, é fundamental que saiba a ordem exata que esses parâmetros devem ser passados após o nome da função. Por exemplo, se além da entrada idC, inseríssemos outra, como idOperadora, a estrutura final da URI ficaria como no trecho abaixo, onde o valor "3123" seria recebido pela variável idC e o valor "05" pela idOperadora (Figura 2.4).

https://... WebServiceRest:cliente/3123/05

Image Removed

Figura 2.4 - Obtendo mais de um parâmetro

Parâmetro Query String

1. Após clicar na engrenagem, altere o campo Tipo para Externa;
2. No campo Segurança, clique no botão e altere as permissões Permitir Executar e Permitir Obter para Todos;
3. Observe o campo Endereço REST, ele será utilizado para testar o serviço.

Por fim, vamos salvar tudo, executar a aplicação e a requisição REST via bloco de programação já estará disponível. 

Informação extra

Parâmetro Query String

Também é possível obter parâmetros por query string. Como ele não será utilizado nesse tutorial, mas se trata de um tópico que está relacionado, vamos apenas explicá-lo.

Os parâmetros via query string também pode ser passados junto com os parâmetros Restde rotas, dessa forma, é possível efetuar uma requisição como no trecho da URI abaixo, em que após o parâmetro REST "3123", usamos o caractere interrogação "?" para informar os parâmetros query string e seus valores.

Diferentemente dos parâmetros Restpor Rotas, não é necessário se preocupar com a ordem dos parâmetros query string definidos na URI.  Para Para obter seus valores, basta utilizar o bloco "result", informando o nome parâmetro. (URI abaixo e Obter parâmetro da query string, conforme as informações abaixo e a Figura 2.5) 

.

Rode o projeto, abra a aplicação no navegador Web e cole o endereço abaixo, alterando as informações conforme seu projeto:

<Domínio>/api/cronapi/REST/WebServiceREST:Cliente/3123?param1=Cronapp&param2=low-code

• ?Domínio: separa o endereço URI dos parâmetros query string;
• Parâmetro=valor: nome do parâmetro e seu valor;
• &: (ampersand) permite adicionar outro parâmetro=valor.

Image Removed

Figura 2.5 - Obtendo parâmetros via Rest e Query string

Consulta ao banco de dados

Como informado anteriormente, a função irá receber como parâmetro um identificador de cliente "idC" e retornar os dados telefônicos desse cliente. Para isso, arraste o bloco "Abrir consulta" (menu lateral > Banco de dados) e encaixe no retorno da função cliente. 

Clique no ícone de engrenagem do bloco "Abrir consulta" e configure como na Figura 2.6. Após salvar a configuração do Assistente JPQL, será exibido um parâmetro de entrada do identificador do cliente, encaixe o bloco da variável "idC".

Image Removed

Figura 2.6 - Configurando o bloco de programação e consulta

Salve todas as janelas para que o Cronapp gere as anotações necessárias, e assim que a aplicação estiver em execução a requisição REST estará disponível.

Endereço

• é o domínio da aplicação. Nesse tutorial estamos utilizando o domínio temporário. Ex.: https://app-

• 30-

• 205-

• 11680.ide.cronapp.io

• ;
• Endereço REST: é encontrado nas Propriedades do bloco (item 3 da Figura 2.4), contendo o nome do bloco, o nome da função e o nome de entrada definidos. Observação: Note que o <idCliente> foi passado na URI como 3123; 
• ?: separa o endereço URI dos parâmetros query string;
• Parâmetro=valor: nome do parâmetro e seu valor. Ex.: param1=Cronapp;
• & (ampersand): permite adicionar outro parâmetro=valor.

O endereço possui os seguintes elementos:

<Domínio>/api/cronapi/rest/blockly.<Nome do Blockly>:<Nome da Função>[/<Parâmetro 1>[/Parâmetro N]]

Considerando os elementos abaixo:

• Domínio: https://app-19-33-61591.ide.cronapp.io/
• Arquivo Blockly: WebServiceRest
• Função: cliente
• Parâmetro: 2 (valor do parâmetro passado na função)

O endereço Rest completo ficará:

O endereço REST completo ficará:

https://app-

30-

205-

11680.ide.cronapp.io/api/cronapi/

REST/

WebServiceREST:

Cliente/3123?param1=Cronapp&param2=low-code

Image Added

Figura 2.5 - Obtendo parâmetros via Rotas e Query string

Via Fonte de dados

Crie Vamos iniciar criando uma Fonte de dados seguindo os seguintes passos: acesse Projeto > Fonte de dados . Acesse Projeto (Figura 3.1) no menu do sistema para abrir a e selecione a opção Fonte de Dados, na janela Buscar Fonte de dados e Dados clique no botão Nova Fonte fonte de dados ao final (Figura 3.1).

Image Modified

Figura 3.1 - Criando nova Fonte de dados

Configuração

Com a janela da Fonte de dados aberta, vamos configurar as informações da fonte de dados , sua e a consulta ao banco e permissão de acesso. ÂncoraconfigFonteconfigFontena aba Filtros.

Figura 3.2 - Configuração das informações da fonte e sua consulta

1. Identificador: fonte de dados que será usado na URI do serviço REST. Estamos utilizando TelefonesCliente;
2. Nome da consulta: nome que será exibido na lista de fonte de dados do projeto.
3. Entidade: botão de seleção das entidades.
4. Configura consulta: personaliza a consulta da fonte de dados;
5. Parâmetros: nome do parâmetro usado na consulta e na query string do endereço;
6. Estamos utilizando TelefonesCliente;
7. Endereço REST: trecho final (URN) do endereço do serviço REST, será concatenado após o domínio do sistema.

1. ;
2. Entidade: clique no botão e selecione a entidade Telefone;
3. Configura consulta: clique no botão para personalizar a consulta da fonte de dados. Na nova janela, clique em Nova Regra e escolha t.cliente.id (conforme a Figura 2.4);
4. Parâmetros: após salvar a consulta, o parâmetro aparecerá, não é necessário definir nenhum valor. Ele é usado na consulta e na query string do endereço.

Agora vamos configurar as permissões de acesso. Vá até a aba Ações, clique no cadeado do verbo Permitir Obter para .Após a configuração da aba Filtro, acesse a aba Permissões e clique nos cadeados dos verbos Permitir Obter, Permitir Filtrar e Permitir Contar para abrir a janela Permissão de Segurança, deixe apenas a opção Todos selecionados em todas as janelas (Figura 3.3)selecionada. Repita em Permitir Filtrar e Permitir Contar.

Figura 3.3 - Configuração das permissões da fonte de dados

Após Por fim, vamos salvar tudo, execute executar a aplicação e a requisição REST por via fonte de dados já estará disponível.

Testando o serviço

Existem diversas aplicações para testar serviços REST, para demostrar os resultados desse tutorial usaremos sites externos com o método GET. Antes de partir para os próximos passos, é necessário que os dados estejam cadastrado. Por isso, rode a aplicação, abra no navegador Web e cadastre os dados que quiser nos formulários Cliente e Telefone. 

Bloco de programação

Primeiro vamos entender como o endereço REST é formado e, em seguida, vamos testar o serviço.

Endereço

Para esse tutorial vamos usar o domínio temporário gerado no debug do Cronapp (ex.: https://app-30-205-11680.ide.cronapp.io/).  Quando o seu sistema estiver em produção e com domínio próprio (ex.: https://www.cronapp.io), utilize-o para concatenar com o endereço (URN) do serviço REST apontado no campo Endereço REST da Figura 2.5. 

Considere que endereço REST é formado pelos principais elementos abaixo:

<Domínio>/api/cronapi/REST/blockly.<Nome do Blockly>:<Nome da Função>[/<Parâmetro 1>[/Parâmetro N]]

• Domínio: é o domínio da aplicação. Nesse tutorial estamos utilizando o domínio temporário. Ex.: https://app-30-205-11680.ide.cronapp.io/;
• Nome do Blockly: é o arquivo Blockly ou bloco de programação. Ex.: WebServiceREST;
• Nome da Função: é o nome da função que se deseja acessar. Ex.: Cliente;
• Parâmetro: é o valor do parâmetro passado na função, nesse tutorial estamos utilizando o ID do cliente como parâmetro. Ex.: 2.

O endereço REST completo ficará: https://app-30-205-11680.ide.cronapp.io/api/cronapi/rest/WebServiceRest:Cliente/2

Requisição

Vamos testar o serviço abrindo a página do ReqBin, colando o endereço REST completo no campo, selecionando o método GET e clicando em Send. Requisições REST de um bloco de programação pode retornar qualquer formato, porém, como estamos obtendo o conteúdo do bloco Abrir consulta, o conteúdo é exibido através de uma lista de objetos em formato JSON.

Image Added

Figura 4.1 - Retorno do serviço via Bloco de programação

Fonte de dados

Primeiro vamos entender como o endereço REST é formado e, em seguida, vamos testar o serviço.

Endereço

Quando o seu sistema estiver em produção e com domínio próprio (ex.: https://www.cronapp.io), utilize-o para concatenar com o endereço (URN) do serviço REST apontado no item 6 da figura 3.2. Para esse tutorial usaremos o domínio temporário gerado no debug do Cronapp (ex.:  https://app-1930-33205-6159111680.ide.cronapp.io/). 

O trecho do endereço formado no item 6 é uma query string formado com os seguintes elementos:

<Domínio>/api/cronapi/odata/v2/app/<Identificador <Identificador da fonte>fonte>[?<Parâmetro 1>=<Valor <Parâmetro 1>=<Valor do Parâmetro 1>1>[&<Parâmetro n>=<Valor <Parâmetro n>=<Valor do Parâmetro n>n>]]

Considerando os elementos abaixo:

• Domínio:  é o domínio da aplicação. Nesse tutorial estamos utilizando o domínio temporário. Ex.: https://app-1930-33205-6159111680.ide.cronapp.io/;
• Identificador da fonte: é o identificador da Fonte de dados: TelefonesClienteDados (item 1 da Figura 3.2). Ex.: TelefonesCliente;
• Parâmetro: idCliente (obtido através da lista de parâmetros, destaque 5 da Figura 3.2);
• Valor do parâmetro: é o valor do parâmetro passado na função, nesse tutorial estamos utilizando o ID do cliente como parâmetro. Ex.: 2.

O endereço Rest REST completo ficará:https://app-

30-

205-

11680.ide.cronapp.io/api/cronapi/odata/v2/app/TelefonesCliente?idCliente=2 Âncoratesteteste

Teste do serviço

Existem diversas aplicações para testar serviços REST, para demostrar os resultados desse tutorial usaremos o Postman. Para utilizá-lo, basta selecione o Verbo ou método HTTP, nesse caso usaremos só o GET, informar o endereço completo do serviço e clicar em "Send" para exibir o conteúdo retornado. 

Bloco de programação

Requisições Rest de um bloco de programação pode retornar qualquer formato, porém, como estamos obtendo o conteúdo do bloco "Abrir consulta", o conteúdo é exibido através de uma lista de objetos em formato JSON. Na figura 4.1 utilizamos a URI informado no tópico Endereço do bloco de programação.

Image Removed

Figura 4.1 - Retorno do serviço via Bloco de programação

Fonte de dados

Requisição

Vamos testar o serviço abrindo a página http://4alltests.com.br/testeapis/, selecionando o método GET, colando o endereço REST completo no campo Endpoint e clicando em Enviar. Requisições via fonte de dados sempre retornam uma lista de objetos em XML. Na figura 4.2 utilizamos a URI informado no tópico Endereço da fonte de dados. 

Image Modified

Figura 4.2 - Retorno do serviço via Fonte de dados