As Fontes de dados do tipo Web Services necessitam de algumas configurações a mais em relação aos demais tipos (Consulta a Entidade, Bloco de programação e SQL Nativo), essas configurações são necessárias para adaptar a comunicação entre a Fonte de dados e a API externa. Quando algum recurso da aplicação Cronapp necessita de algum dado, ele solicita a Fonte de dados (destaque 1 da figura 1), que por sua vez direciona essa requisição no padrão que a API externa reconheça (2), recebe uma resposta (3), trata e retorna o conteúdo ao componente que fez a solicitação (4).

Open

Veremos alguns exemplos de como configurar a Fonte de dados para receber recursos no padrão REST e SOAP. Para outros detalhes, acesse a documentação da Fonte de dados.

Definição inicial

De modo a simplificar os exemplos apresentados nessa documentação, vamos assumir algumas nomenclaturas para os endereços de APIs utilizadas nessa documentação.

Open

• Domínio: endereço base onde a API está hospedada. Para essa definição, o domínio pode ou não conter subdomínios. Ex: https://subdominio.dominio.com.br

• URL base: ponto de partida comum (domínio e parte da rota) para todos os recursos de uma determinada API. Muitas APIs não possuem uma rota fixa para agrupar vários de seus recursos, nesses casos, a URL base será o próprio domínio.

• Rotas: especifica o caminho final do endereço para um recurso.

• Endpoint: é a combinação da URL base (domínio), rota e, opcionalmente, query string que define uma operação específica na API.

• Query string: define um ou mais parâmetros, no formato chave=valor, para o recurso.

Web Service - REST

Antes de criarmos uma Fonte de dados REST, precisamos ter em mãos o endpoint (verbo HTTP GET) do serviço que iremos usar e, em seguida, realizar os passos abaixo:

1. Obter campos do serviço: executa alguns passos para obter os campos do objeto.

2. Aba Ações: configura os demais métodos do serviço e seus parâmetros. Os recursos de paginação e ordenação devem ser configurados aqui.

3. Aba Campos: se necessário, é possível personalizar os campos obtidos na primeira etapa.

4. Aba Cabeçalho: se necessário, é possível configurar o cabeçalho da requisição.

Nova Fonte de dados

Para criar a Fonte de dados, acesse o Botão do menu do sistema > Fonte de dados (destaque 1 da figura 2) e após abrir a janela, clique no botão Nova Fonte de dados (destaque 2). 

Open

Passos para obter campos do serviço

Com a janela da Fonte de dados aberta, preencha os campos Identificador e Nome da consulta, em seguida, selecione a opção Web Services (destaque 1 da figura 2.1) e informe o endereço do endpoint REST (verbo Get) no campo ao lado (destaque 2), por fim, clique no botão Obter campos do serviço (destaque 3) para abrir a janela de configuração.

Open

Durante os passos a seguir, o Cronapp tentará obter todas as informações automaticamente, necessitando apenas que o usuário avance as telas até finalizar. Os dados obtidos podem ser modificados durante ou após o processo.

Passo 1

A primeira janela exibe os campos necessários para realizar a requisição.

Open

1. URL: endpoint do verbo Get que informamos no passo anterior (destaque 2 da figura 2.1).

2. Novo Cabeçalho: se o recurso REST necessita de cabeçalhos próprios, como os de autenticação (exemplos: authorization ou x-auth-token), é possível informar o nome do cabeçalho e adicioná-lo à lista clicando no ícone (+).

3. Lista de cabeçalhos: essa lista aceita apenas valores estáticos, após obter os campos, utilize a aba Cabeçalho para configurar os cabeçalhos com valores dinâmicos, 

Clique em Avançar.

Passo 2

Na próxima tela (Figura 2.3), o campo Resultado exibirá o retorno da requisição e o Cronapp tentará preencher automaticamente os dois primeiros campos. Esses campos podem ser editados posteriormente na aba Ações.

• Para Obter: esse campo deve conter o caminho JSON até o atributo que contém a lista com os objetos.  

• Para Contar: esse campo deve conter o caminho JSON até o atributo que contém o número total de registros, usado para realizar a paginação do conteúdo. 

• Resultado: retorno da requisição.

Open

Clique em Avançar.

Passo 3

Após identificar a lista de objetos no passo anterior, o Cronapp exibirá um objeto com todos os seus campos em Resultado (Figura 2.4). 

• Resultado: primeiro objeto da lista.

• Contagem: exibe o total de registros com base no atributo informado no campo Para Contar (Figura 2.3).

• Chaves: o Cronapp tentará identificar qual a chave do objeto, porém, clicando no campo (figura 2.4), é possível escolher, manualmente, os campos chaves. Essa configuração poderá ser feita depois na aba Campos.

Open

Clique em Avançar.

Passo 4

A janela a seguir permite ajustar os campos já mapeados pela Fonte de dados ou adicionar Novos Campos. Informe na coluna Caminho o JSON Path do atributo que alimentará esse campo. Essa configuração poderá ser feita depois a partir da aba Campos.

Open

Na maioria das vezes não é necessário realizar qualquer ação nessa janela.

Clique em Avançar.

Passo final

A última janela exibirá um objeto completo, com as configurações feitas até aqui. Clique em Finalizar para retornar as configurações da Fonte de dados.

Open

Após Finalizar, a aba Campos será exibida com todos os atributos configurados.

Obter campos com e sem metadados

Se o endpoint usado pertencer a uma Fonte de Dados (OData) de outro projeto Cronapp, e esse projeto estiver configurado com a opção "Expor Metadados" ativada nas Configurações do Projeto, ao tentar acessar o recurso, a janela Obter campos do serviço será capaz de extrair os metadados do projeto de origem. Isso permitirá acessar informações detalhadas sobre os campos, como tipos de dados, se eles aceitam valores nulos, quais são os campos chave e a definição do campo "ObjectKey".

No caso de serviços externos sem metadados, a janela Obter campos do serviço irá identificar os campos dos objetos retornados e inferir quais os tipos desses campos (exemplo: String, Boolean, Date, ...), porém, nem sempre isso é possível, nesses casos, o desenvolvedor pode ajustar esses atributos na aba Campos.

Requisição personalizada

A Fonte de dados permite criar rotas dinâmica para o endpoint e adicionar chaves query string diferentes nas requisições de cada verbo HTTP. Esses parâmetros são configuráveis na aba Filtro (acesse o tópico "Aba Filtro" da documentação Fonte de Dados).

Rotas

Para definir rotas dinâmicas a partir dos parâmetros informados à Fonte de dados, basta substituir parte do endereço (ou o endereço inteiro) pela expressão ":<parâmetro>" (dois pontos + nome do parâmetro) no endereço do endpoint (ex.: http://www.ws.com/usuario/:rotaDinamica/dados) (destaque 1 da figura 2.7), o parâmetro definido ("rotaDinamica") será criado na lista de parâmetros da aba Filtro (2). Isso permitirá que a mesma Fonte de dados faça requisições para endereços diferentes, mudando o parâmetro informado.

Vale ressaltar que os endereços montados devem ser compatíveis com as demais configurações da Fonte de dados: abas Cabeçalhos, Campos e Ações.

Open

No exemplo da figura 2.7, ao executar a Fonte de dados informando um valor para o parâmetro "rotaDinamica" (ex.: post), o endpoint será montado da seguinte forma: https://meusistema.com.br/post/comentarios

Query String

Na aba Ações da Fonte de dados é possível configurar parâmetros Query String que serão incluídos nas requisições de cada verbo HTTP. Assim, após o endereço do endpoint será adicionado o caractere "?" (interrogação) para informar onde começa a lista com os parâmetros (Chave=Valor) e, entre cada parâmetro, será adicionado o caractere separador "&" (ampersand),

No exemplo da figura 2.8 foram configurados 2 parâmetros querystring para as requisições Para Obter (GET): postid e id.

O valor do parâmetro "id" (destaque 2) foi definido de forma estática, sendo assim, em todas as requisições GET dessa Fonte de dados, o valor do "id" sempre será "21". 

Open

A querystring "postId" (destaque 1 da figura 2.8) foi configurada de forma dinâmica a partir de um parâmetro da Fonte de dados nomeado como "identificadorPost", esse parâmetro será exibido na lista de parâmetros da aba Filtro (destaque 1 da figura 2.9). Sendo assim, em todas as requisições GET feita para essa Fonte de dados será possível alimentar a querystring "idenficadorPost" que, por sua vez, alimentará a querystring "postId" da requisição montada pela Fonte de dados (destaque 2 da figura 2.9).

Open

O endpoint abaixo é um exemplo de requisição feita para a Fonte de dados da figura 2.9 (query881058), passando o valor "101" para a querystring "identificadorPost" da Fonte de dados (destaque 1 da figura 2.9). Em seguida, a Fonte de dados realiza uma requisição à API configurada (4 da figura 2.9), incluindo as quesrystrings "id" (estática, definida no destaque 2 da figura 2.8) e "postId" (obtida a partir do parâmetro "identificadorPost", destaques 1 das figuras 2.8 e 2.9). Esse fluxo é representado pelos itens 1 e 2 da figura 1.

Parâmetros do Sistema

O Cronapp também permite que o endereço de uma API possa ser montado a partir de um parâmetro do sistema. Isso pode ser útil em situações onde a API referenciada muda de domínio, gerando um endpoint diferente para os ambientes (perfis) de desenvolvimento ou produção, por exemplo.

Para configurar, basta criar um parâmetro na janela de Parâmetros do Sistema, passando como Valor, o domínio, a rota ou a parte do endpoint que deseja substituir e definir o Perfil (Figura 2.10).

Open

Na janela de configurações da Fonte de dados podemos substituir parte do endpoint pelo parâmetro criado, utilizando os caracteres ${} em volta, exemplo: ${domainAPI} (destaque 1 da figura 2.11). Ao executar, a Fonte de dados identificará o perfil e montará o endpoint com base no parâmetro configurado (2). 

Open

Aba Ações

Essa aba permite configurar as rotas de comunicações entre a Fonte de dados e a API externa através dos verbos HTTP (Get, Post, Put, Delete), filtrar ou contar; definir a segurança e configurar os parâmetros de querystring usados por cada ação. Nesse momento é importante conhecer como funciona o serviço REST que será utilizado ou acessar sua documentação, pois a API pode utilizar uma mesma URL Base para todas as requisições, possuir um endpoint igual ou diferente para cada verbo HTTP. Além disso, será necessário configurar os parâmetros utilizados para filtrar, ordenar e paginar.

Por padrão, a Fonte de dados sempre inclui automaticamente o valor do identificador do registro no final do endereço da requisição para as ações Para Atualizar e Para Remover, ficando "<Endpoint>/{id}".

Como cada ação pode ter parâmetros e endpoint diferentes, toda requisição feita a uma Fonte de dados Web services em modo debug imprimirá no Console do depurador os parâmetros de querystring gerados e a URL com a requisição completa (Console do depurador, figura 3.1). 

Open

1. Campo com o Endereço principal: esse endereço pode ser completo (endpoint do verbo Get) ou parcial (URL base), nesse caso, a Fonte de dado irá concatenar a URL base com a Rota definida no campo URL de cada Ação (destaque 8 da figura 3.1). Veja mais detalhes no item 8 dessa lista.

2. "...": abre a janela "Obter campos do serviço" para personalizar os parâmetros da requisição de cada ação.

3. Campo Parâmetro: nome do novo parâmetro de querystring a ser passado na requisição.

4. (+): inclui o novo parâmetro na lista de querystrings.

5. Coluna Nome: lista de parâmetros.

6. Coluna Valor do campo: define como será o valor a ser passado, podendo ser tipos estáticos (texto, numérico, data e hora, hora ou lógico), Bloco de programação, Parâmetro ou Expressões. Acesse o tópico "Parâmetros e constantes" da documentação Fonte de Dados para mais detalhes.

7. Coluna Remover: remove o parâmetro querystring selecionado.

8. Parâmetros fixos:

   • URL: substitui ou modifica o endpoint da requisição para a ação selecionada (verbo HTTP). Esse campo pode estar vazio, com um endereço relativo ou absoluto:

     • Campo URL vazio: se o campo URL estiver vazio, a requisição será feita a partir do endereço principal (destaque 1 da figura 3.1).

       • Exemplo:
         Campo Endereço principal (1): https://www.ws.com.br/user
         Campo URL da ação Para Obter (8): <vazio>
         Requisição Para Obter (13): https://www.ws.com.br/user

       • Exemplo 2:
         URL Base (1): https://www.ws.com.br/user
         Campo URL da ação Para Atualizar (8): <vazio>
         Requisição Para Atualizar (13): https://www.ws.com.br/user/{id} 

     • Campo URL com valor relativo: algumas APIs possuem uma estrutura de endereço igual (URL base) e altera apenas a rota final. Assim, é possível utilizar a mesma estrutura do campo Endereço principal (destaque 1 da figura 3.1) "<URL BASE>/" e alterar apenas o campo URL (destaque 8 da figura 3.1) para cada verbo HTTP (Ação), com a rota específica da ação (Ex.:  " /list/"), gerando o endpoint completo ao final "<URL Base>/list/". 
       
       

        

       • Exemplo:
         Campo Endereço principal (1): https://www.ws.com.br/user/
         Campo URL da ação Para Obter (8): list/
         Requisição Para Obter (13): https://www.ws.com.br/user/list/

       • Exemplo 2:
         URL Base (1): https://www.ws.com.br/user/
         Campo URL da ação Para Remover (8): /remove/
         Requisição Para Remover (13): https://www.ws.com.br/remove/{id}

     • Campo URL com valor absoluto: é possível informar um endpoint completo no campo URL e ignorar totalmente o endpoint no campo Endereço principal (destaque 1 da figura 3.1).

       • Exemplo:
         Campo Endereço principal (1): https://www.ws.com.br/user
         Campo URL da ação Para Obter (8): https://www.ws-2.io/list
         Requisição Para Obter (13): https://www.ws-2.io/list

       • Exemplo 2:
         Campo Endereço principal (1): https://www.ws.com.br/user
         Campo URL da ação Para Remover (8): https://www.ws-2.io/list/{id}
         Requisição Para Remover (13): https://www.ws-2.io/list/123

   • Caminho: o campo espera receber um JSON Path e é usado para informar qual parte do JSON recebido possui a lista de objetos (ex.: $.data - tudo que estiver dentro do atributo data no objeto JSON). Caso não seja preenchido, será obtido todo o conteúdo da resposta da requisição. 

9. Parâmetros: devem ser adicionados e configurados os parâmetros querystring que serão enviados juntos com o endpoint. 

10. Parâmetro compartilhado: nos casos em que várias ações utilizam o mesmo parâmetro, é possível selecionar a opção "Parâmetro" na coluna Valor do campo (6) e informar um nome ao lado (10.a). Esse parâmetro passará a ser configurável a partir da aba Filtro da Fonte de dados (destaque 1 da figura 2.9) e todas as outras ações poderão receber o mesmo valor após selecionar a opção "Parâmetro" e informar o mesmo nome.

11. Copiar: permite selecionar e copiar os parâmetros da janela "Obter campos do serviço" para utilizá-los em outra ação na aba "Ações".

12. Colar: permite colar os parâmetros previamente copiados de outra ação, facilitando suas configurações. Esse botão só ficará disponível após a cópia de algum parâmetro.

13. Endereço requisitado à API: endereço da requisição montado com o que foi definido no campo URL Base (1), URL (8) e nos parâmetros passados (9 e 10), 

Nos subtópicos abaixo listamos as principais ações utilizadas e apresentamos exemplos de como configurá-las. Veja o que representa cada elemento da lista numerada nos exemplos:

1. Endereço principal: endereço usado para configurar a Fonte de dados (destaque 1 da figura 3.1).

2. Campo URL: usado para personalizar o endpoint de cada Ação em sua respectiva janela (destaque 8 da figura 3.1).

3. Caminho: endereço JSON (JSON Path) até a lista de objetos no retorno da requisição (destaque 8 da figura 3.1). 

4. Método: método HTTP utilizado: GET, PUT, POST, DELETE.

5. Requisição final: endereço da requisição montado a partir da configuração dos campos Endereço principal (destaque 1 da figura 3.1), campo URL (destaque 8 da figura 3.1) e parâmetros de querystring (destaques 9 e 10 da figura 3.1).

6. Corpo da requisição enviado para a API: corpo da requisição enviado pela Fonte de dados para a API, utilizado apenas nas ações Para inserir e Para Atualizar.
   Em um formulário Cronapp, o corpo do objeto da requisição é montado e enviado automaticamente pela Fonte de dados, que obtém esses dados dos campos (inputs) do formulário que estão com a propriedade Valor (ng-model) vinculada com a Fonte de dados (ex: <FonteDados>.active.nome).

7. Corpo da requisição retornada pela API: estrutura JSON retornado pela API.

8. Conteúdo do caminho na requisição de retorno: após obter a resposta da API, a Fonte de dados utiliza o caminho (JSON Path) informado (destaque 8 da figura 3.1) para acessar a lista de objetos.
   Durante a configuração da Fonte de dados web services, o caminho é informado no passo 2, a partir do campo Para Obter.

Para Obter (Get)

Essa ação é responsável por obter os dados do recurso e, dependendo da chamada, pode retornar um único elemento ou uma lista de elementos.

Exemplo 1 (Get)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço Principal: https://meusistema.com.br/api/users

2. Campo URL: <vazio>

3. Caminho: $.data

4. Método: GET

5. Requisição final: https://meusistema.com.br/api/users

6. Corpo da requisição enviado para a API: <vazio>

7. Corpo da requisição retornada pela API:

   { "page": 1, "per_page": 6, "total": 12, "total_pages": 2, "data": [ { "id": 1, "email": "js@cronapp.io", "nome": "João Souza" }, { "id": 2, "email": "ma@cronapp.io", "nome": "Maria Andrade" }, ... ], "support": { "url": "https://www.cronapp.io", "text": "this is an example" } }

8. Conteúdo do caminho na requisição de retorno:

   [ { "id": 1, "email": "js@cronapp.io", "nome": "João Souza" }, { "id": 2, "email": "ma@cronapp.io", "nome": "Maria Andrade" }, ... ]

Exemplo 2 (Get)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço Principal: https://meusistema.com.br/api/user

2. Campo URL: expression: ${primaryKey}

3. Caminho: <vazio>

4. Método: GET

5. Requisição final: https://meusistema.com.br/api/user/2

6. Corpo da requisição enviado para a API: <vazio>

7. Corpo da requisição retornada pela API:

   { "id": 2, "email": "ma@cronapp.io", "nome": "Maria Andrade" }

8. Conteúdo do caminho na requisição de retorno:
   
   

   { "id": 2, "email": "ma@cronapp.io", "nome": "Maria Andrade" }

Exemplo 3 (Get)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço principal: https://meusistema.com.br/v2/api/list

2. Campo URL: /api/users

3. Caminho: $.data

4. Método: GET

5. Requisição: https://meusistema.com.br/api/users?page=1&per_page=6

   • page: top

   • per_page: per_page 

6. Corpo da requisição enviado para a API: <vazio>

7. Corpo da requisição retornada pela API:

   { "page": 1, "per_page": 6, "total": 12, "total_pages": 2, "data": [ { "id": 1, "email": "js@cronapp.io", "nome": "João Souza" }, { "id": 2, "email": "ma@cronapp.io", "nome": "Maria Andrade" }, ... ], "support": { "url": "https://www.cronapp.io", "text": "this is an example" } }

8. Conteúdo do caminho na requisição de retorno:

   [ { "id": 1, "email": "js@cronapp.io", "nome": "João Souza" }, { "id": 2, "email": "ma@cronapp.io", "nome": "Maria Andrade" }, ... ]

Para Inserir (Post)

Ação utilizada para incluir novos elementos ao serviço. O conteúdo a ser adicionado é enviado no corpo da requisição e alguns serviços retornam o próprio elemento, sinalizando sucesso na operação.

Exemplo 1 (Post)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço principal: https://meusistema.com.br/api/user

2. Campo URL: <vazio>

3. Caminho: <vazio>

4. Método: POST

5. Requisição final: https://meusistema.com.br/api/user

6. Corpo da requisição enviada para a Fonte de dados: 
   
   

   { "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }

7. Corpo da requisição retornada pela API:

   { "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }

8. Conteúdo do caminho na requisição de retorno:

   { "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }

Exemplo 2 (Post)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço principal: https://meusistema.com.br/api/user