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 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
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
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
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:
Figura 2.4 - Configuração da chamada REST
Por fim, vamos salvar tudo, executar a aplicação e a requisição REST via bloco de programação já estará disponível.
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
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.5 - Obtendo parâmetros via Rotas e Query string
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
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
t.cliente.id
(conforme a Figura 2.4);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.
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