- Criado por Igor Andrade, última alteração em 24/02/2022
Você está vendo a versão antiga da página. Ver a versão atual.
Comparar com o atual Ver Histórico da Página
« Anterior Versão 22 Próxima »
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
- Projeto do tipo mobile ou web criado, caso haja dúvidas de como criar esse tipo de projeto acesse o link criar projeto;
- Saber utilizar as funcionalidades do diagrama, como criar classes e gerar persistência, caso haja dúvidas acesse o link diagrama;
- Saber criar um bloco de programação, caso haja dúvidas acesse o link bloco de programação;
- 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 - 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.2 - Gerando o CRUD e a camada de persistência
- 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;
- 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
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.
Figura 2.1 - Nova função de bloco de programação
- Clique com o botão direito na pasta Servidor e escolher Novo;
- Em seguida, vamos clicar em Bloco de Programação;
- 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.
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.
Caso tenha dúvidas de como configurar a consulta, acesse a documentação do Assistente de consulta JPQL.
Figura 2.3 - Configurando o bloco de programação e consulta
- Clique na engrenagem do bloco Abrir consulta;
- Na janela Configurar Bloco de Programação:
- Selecione a entidade Telefone em "..." e clique em Adicionar;
- Adicione um Novo Campo e escolha a opção Obter t;
- Adicione uma Nova Regra e selecione t.cliente.id, o restante da expressão será preenchido de forma automática;
- Clique em OK ao final;
- 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 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 campos que estão descritos abaixo e, após entendê-los, seguir para os passos abaixo da Figura 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:
- Interno: o bloco só é consumido no projeto;
- 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 outra janela que nos permite dar autorização de CRUD e Execução aos permissionáveis do sistema.
Figura 2.4 - Configuração da chamada REST
- Após clicar na engrenagem, altere o campo Tipo para Externa;
- No campo Segurança, clique no botão e altere as permissões Permitir Executar e Permitir Obter para Todos;
- 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 de rotas, dessa forma, é possível efetuar uma requisição como no trecho da URI abaixo, em que após o parâmetro "3123", 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
- 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
; - 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 como3123
; - ?: 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 REST completo ficará: https://app-30-205-11680.ide.cronapp.io/api/cronapi/REST/WebServiceREST:Cliente/3123?param1=Cronapp¶m2=low-code
Figura 2.5 - Obtendo parâmetros via Rotas e Query string
Via Fonte de dados
Vamos iniciar criando uma Fonte de dados. Acesse Projeto (Figura 3.1) no menu do sistema e selecione a opção Fonte de Dados, na janela Buscar Fonte de Dados clique no botão Nova fonte de dados.
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 e a consulta ao banco na aba Filtros.
Para mais informações, acesse a documentação da Fonte de dados.
Figura 3.2 - Configuração das informações da fonte e sua consulta
- Identificador: fonte de dados que será usado na URI do serviço REST. Estamos utilizando TelefonesCliente;
- Nome da consulta: nome que será exibido na lista de fonte de dados do projeto. Estamos utilizando TelefonesCliente;
- Endereço REST: trecho final (URN) do endereço do serviço REST, será concatenado após o domínio do sistema;
- Entidade: clique no botão e selecione a entidade Telefone;
- 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); - 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 abrir a janela Permissão de Segurança, deixe apenas a opção Todos selecionada. Repita em Permitir Filtrar e Permitir Contar.
Figura 3.3 - 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.
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.
Dica
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 cliente
que está dentro da pasta logged
(Autenticado), deve-se adicionar /logged/cliente
. O endereço deverá ficar assim: https://app-30-205-11680.ide.cronapp.io/#/home
/logged/cliente
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.
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-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:
- 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/;
- Identificador da fonte: é o identificador da Fonte de Dados (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 completo ficará: https://app-30-205-11680.ide.cronapp.io/
api/cronapi/odata/v2/app/TelefonesCliente?idCliente=2
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.
Figura 4.2 - Retorno do serviço via Fonte de dados
- Sem rótulos