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.
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 ehFixo
(Lógico). Por fim, vamos adicionar o relacionamento 1 to N (destaque 1 da figura 1) entre a classe Cliente e a classe Telefone.
Figura 1 - 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.
Figura 1.1 - Gerando o CRUD e a camada de persistência
Cliente
, selecionar Criar visão para a entidade (2), escolher o modelo de formulário CRUD Web na nova janela e avançar até finalizar.Repita o procedimento 2 na classe Telefone
.
Veremos a seguir como disponibilizar serviço REST via Bloco de programação e depois via Fonte de dados.
Para configurar o serviço REST via bloco, vamos iniciar criando um bloco de programação do lado Servidor (Figura 2). Siga os passos abaixo.
Figura 2 - Nova função de bloco de programação
Vamos começar a configuração criando o parâmetro idCliente
que passará como argumento para a função o identificador do cliente. Clique na engrenagem da função Cliente (destaque 1 da Figura 2.1), arraste o bloco nome de entrada para dentro do bloco entradas e altere o nome da entrada para idCliente (destaque 2). Ele ficará disponível na categoria Variáveis (destaque 3).
Figura 2.1 - 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.2) e configure-o conforme os passos abaixo.
Caso tenha dúvidas de como configurar a consulta, acesse a documentação do Assistente de consulta JPQL. |
Figura 2.2 - Configurando o bloco de programação e consulta
Agora precisamos alterar as propriedades do bloco de programaçã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.3). Nessa janela, é importante entender os campos que estão descritos abaixo:
Figura 2.3 - Configuração da chamada REST
Por fim, vamos salvar tudo, executar a aplicação, pois a requisição REST via bloco de programação já estará disponível.
Também é possível obter parâmetros por query string. Ele não será utilizado nesse tutorial, mas explicaremos nesse tópico extra.
Os parâmetros via query string também pode ser passados junto com os parâmetros de rotas, dessa forma, é possível efetuar uma requisição como no trecho da URI abaixo, em que após o parâmetro "3123" (identificador do cliente), usamos o caractere interrogação "?" para informar os parâmetros query string e seus valores.
Diferentemente dos parâmetros por Rotas, não é necessário se preocupar com a ordem dos parâmetros query string definidos na URI. Para obter seus valores, basta utilizar o bloco 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¶m2=low-code
https://app-30-205-11680.ide.cronapp.io
;<idCliente>
foi passado na URI como 3123
; param1=Cronapp
;O endereço REST completo ficará: https://app-30-205-11680.ide.cronapp.io/api/cronapi/REST/WebServiceREST:Cliente/3123?param1=Cronapp¶m2=low-code
Figura 2.4 - Obtendo parâmetros via Rotas e Query string
Vamos iniciar criando uma Fonte de dados, clique no ícone da Fonte de Dados e na janela Buscar Fonte de Dados clique no botão Nova fonte de dados (Figura 3).
Figura 3 - Criando nova Fonte de dados
Com a janela da Fonte de dados aberta, vamos configurar as informações da fonte de dados e a consulta ao banco na aba Filtros.
Para mais informações, acesse a documentação da Fonte de dados. |
Figura 3.1 - Configuração das informações da fonte e sua consulta
TelefonesCliente
.TelefonesCliente
.Telefone.
t.cliente.id
(conforme a Figura 2.2).Agora vamos configurar as permissões de acesso. Vá até a aba Ações, clique no cadeado do verbo Permitir Obter para abrir a janela Permissão de Segurança, deixe apenas a opção Todos selecionada. Repita em Permitir Filtrar e Permitir Contar.
Figura 3.2 - Configuração das permissões da fonte de dados
Por fim, vamos salvar tudo, executar a aplicação e a requisição REST via fonte de dados já estará disponível.
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.
Para acessar diretamente as páginas Cliente e Telefone, configure a URL do projeto concatenando a pasta (nome no modo avançado) e o nome do formulário. Exemplo: para acessar o formulário |
Primeiro vamos entender como o endereço REST é formado e, em seguida, vamos testar o serviç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]]
O endereço REST completo ficará: https://app-30-205-11680.ide.cronapp.io/
api/cronapi/rest/WebServiceRest:Cliente/2
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.
Figura 4.1 - Retorno do serviço via Bloco de programação
Primeiro vamos entender como o endereço REST é formado e, em seguida, vamos testar o serviç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-30-205-11680.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 da fonte>[?<Parâmetro 1>=<Valor do Parâmetro 1>[&<Parâmetro n>=<Valor do Parâmetro n>]]
Considerando os elementos abaixo:
O endereço REST completo ficará: https://app-30-205-11680.ide.cronapp.io/
api/cronapi/odata/v2/app/TelefonesCliente?idCliente=2
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.
Figura 4.2 - Retorno do serviço via Fonte de dados