Fontes de dados do tipo Web Services necessitam de algumas configurações a mais em relação aos demais tipos (bloco de programação e Entidades), essas configurações são necessárias para adaptar a comunicação entre a fonte de dados e a API externa.

Quando um componente 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).

Figura 1 - Fluxo de comunicação entre um componente, fonte de dados e API

Veremos aqui como configurar a fonte de dados para receber recursos no padrão REST e SOAP <TODO: Ainda não feito>.

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, configurar realizar os campos dos objetos que serão retornados. O Cronapp tentará obter todas as informações automaticamente, necessitando apenas que o usuário avance as telas até finalizar. Porém, como veremos aqui, podemos modificar essas informações durante ou após o processo.

Para criar a fonte de dados, clique no ícone Fonte de dados (destaque 1 da figura 2.0) e após abrir a janela, clique no botão Nova fonte de dados (destaque 2), 

Image Removed

Figura 2.0 - Criando uma fonte de dados

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.

Passos para obter campos do serviço

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. Porém, como veremos aqui, podemos modificar essas informações durante ou após o processo.

Para criar a fonte de dados, clique no ícone Fonte de dados Com a janela da Fonte de dados aberta, selecione a opção Web Services (destaque 1 da figura 2.0) e após abrir a janela, clique no botão Nova fonte de dados (destaque 2), 

Image Added

Figura 2.0 - Criando uma fonte de dados

Com a janela da Fonte de dados aberta, selecione a opção Web Services (destaque 1 da figura 2.1) para o campo ao lado (destaque 2) ficar habilitável e informe o 1) para o campo ao lado (destaque 2) ficar habilitável e informe o endereço do endPoint REST, em seguida, clique no botão Obter campo do serviço (destaque 3) para abrir a janela de configuração.

Figura 2.1 - Informando o endpoint e iniciando a configuração

A primeira janela exibe o campo URL com o endPoint que informamos no passo anterior e mais os campos dos cabeçalhos Accept e Content-Type usados na requisição. Esse e outros cabeçalhos podem ser configurados posteriormente na aba Cabeçalhos. Por padrão, todos os campos já vêm configurados, clique em Avançar.

Figura 2.2 - Configuração da URL e Cabeçalhos

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 endereço JSON até o atributo que contém a lista com os dados.  
• Para Contar: esse campo deve conter o endereço 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.

Clique em Avançar.

Image Removed

Figura 2.3 - Localizando os dados no JSON

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

Clique em Avançar.

Image Removed

Image Added

Figura 2.4 - Configuração dos identificadores do objeto

A janela a seguir permite configurar os campos já mapeados pela fonte de dados e adicionar novos campos, informando o caminho JSON que alimentará esse campo. Essa configuração poderá ser feita depois a partir da aba Campos.

Image Removed

Figura 2.5 - Configuração dos campos do serviço REST

A última janela exibirá um objeto com as configurações feitas após a tela anterior. Clique em Finalizar para retornar as configurações da fonte de dados.

Image Removed

Figura 2.6 - Resultado final

Após finalizar e salvar a fonte de dados, já é possível associar esta fonte de dados a um componente visual, como a Grade, por exemplo, e exibir o conteúdo obtido da API externa que acabamos de configurar.

Image Removed

Figura 2.7 - Vinculando a fonte de dados criada ao componente visual Fonte de dados

Aba Ações

A aba Ações 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 atributos usados por cada ação. Nesse momento é importante conhecer como funciona o serviço REST que será utilizado ou acessar sua documentação, pois o serviço pode utilizar uma mesma URLBase para todas as requisições ou possuir um endPoint para cada uma delas. Além disso, será necessário configurar os parâmetros utilizado.

Image Removed

Figura 3.1 - Acesso a janela de parâmetro das ações

Na coluna Nome (destaque 1 da figura 3.1) devemos configurar os parâmetros utilizados pela API externa, já na coluna Valor do campo (2) configuramos como os parâmetros serão alimentados.

Os campos URL e Caminho existem nas configurações de todas as ações. 

• URL: altera o valor da URLBase informada para a ação selecionada. É possível configurar o campo de 3 formas:
  • Campo vazio: a requisição será feita a partir de "<URLBASE>/" (nas ações Para Obter e Para Inserir) ou "<URLBASE>/{id}" (demais ações)
  • Valor relativo: alguns serviços REST geram recursos a partir de um endPoint dentro da URL Base, dessa forma, é possível informar apenas o endereço final (ex.: insert/) para a requisição ser montada a partir da concatenação da URL BASE e o endereço final (ex.: "<URLBASE>/insert/"). Podemos configurar de 2 formas: Se o primeiro caractere do campo URL não for uma "/" (barra), será concatenado a URLBASE com o conteúdo do campo URL, já se o primeiro caractere do campo URL for uma "/" (barra), será concatenado somente o domínio da URLBASE com o campo URL.
  • Valor absoluto: é possível informar um endPoint completo e ignorar totalmente a URLBase.
• Caminho: o campo espera receber um JSON Path e é usado para informar qual parte do JSON recebido será aproveitado (ex.: $.data - tudo que estiver dentro do atributo data no JSON). Caso não seja preenchido, será obtido todo o conteúdo do corpo da requisição.

3 - Localizando os dados no JSON

Após identificar a lista de objetos no passo anterior, o Cronapp identificará e 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, clique no campo para selecionar outros campos chaves. Essa configuração poderá ser feita depois na aba Campos.

Clique em Avançar.

Image Added

Figura 2.4 - Configuração dos identificadores do objeto

A janela a seguir permite configurar os campos já mapeados pela fonte de dados e adicionar novos campos, informando o caminho JSON que alimentará esse campo. Essa configuração poderá ser feita depois a partir da aba Campos.

Image Added

Figura 2.5 - Configuração dos campos do serviço REST

A última janela exibirá um objeto com as configurações feitas após a tela anterior. Clique em Finalizar para retornar as configurações da fonte de dados.

Image Added

Figura 2.6 - Resultado final

Após finalizar e salvar a fonte de dados, já é possível associar esta fonte de dados a um componente visual, como a Grade (figura 2.7), e exibir o conteúdo obtido da API externa que acabamos de configurar.

Image Added

Figura 2.7 - Vinculando a fonte de dados criada ao componente visual Fonte de dados

Vale destacar que até esse momento só temos configurado os campos e as ações Para Filtrar e Para Obter, sem os parâmetros de filtro, ordenação e paginação. Essas configurações faremos na aba Ações.

Aba Ações

A aba Ações 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 atributos usados por cada ação. Nesse momento é importante conhecer como funciona o serviço REST que será utilizado ou acessar sua documentação, pois o serviço pode utilizar uma mesma URLBase para todas as requisições ou possuir um endPoint para cada uma delas. Além disso, será necessário configurar os parâmetros utilizado para filtrar, ordenar e paginar.

Image Added

Figura 3.1 - Acesso a janela de parâmetro das ações

Na coluna Nome (destaque a da figura 3.1) devemos configurar os parâmetros utilizados pela API externa, já na coluna Valor do campo (b) configuramos como os parâmetros serão alimentados.

Os campos URL e Caminho existem nas configurações de todas as ações. 

• URL: altera o valor da URLBase informada para a ação selecionada. É possível configurar o campo de 3 formas:
  • Campo vazio: a requisição será feita a partir de "<URLBASE>/" (nas ações Para Obter e Para Inserir) ou "<URLBASE>/{id}" (demais ações).
  • Valor relativo: alguns serviços REST geram recursos a partir de um endPoint dentro da URL Base, dessa forma, é possível informar apenas o endereço final (ex.: insert/) para a requisição ser montada a partir da concatenação da URL BASE e o endereço final (ex.: "<URLBASE>/insert/"). Podemos configurar de 2 formas: Se o primeiro caractere do campo URL não for uma "/" (barra), será concatenado a URLBASE com o conteúdo do campo URL (veja exemplo), já se o primeiro caractere do campo URL for uma "/" (barra), será concatenado somente o domínio da URL BASE com o campo URL (veja exemplo).
  • Valor absoluto: é possível informar um endPoint completo e ignorar totalmente a URLBase.
• Caminho: o campo espera receber um JSON Path e é usado para informar qual parte do JSON recebido será aproveitado (ex.: $.data - tudo que estiver dentro do atributo data no JSON). Caso não seja preenchido, será obtido todo o conteúdo do corpo da requisição.

As ações devem ser configuradas com base na API utilizada, por isso é necessário acessar a sua documentação e verificar se a API possui suporte a todos os recurso de CRUD e também paginação, ordenação e filtro, 

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. URL Base: endereço usado para configurar a fonte de dados (destaque 1 da figura 3.1).
2. URL: campo usado para personalizar o endPoint em cada Ação (destaque 2 da figura 3.1).
3. Caminho: endereço (JSON Path) que representa o que será filtrado do JSON obtido a partir do retorno da requisição (destaque 3 da figura 3.1)., 
4. Requisição: endereço da requisição montado a partir da configuração dos campos URL Base (1) e URL (2).
5. Corpo do conteúdo enviado pela fonte de dados: corpo da requisição enviado da fonte de dados para a API, utilizado apenas nas ações Para inserir e Para Atualizar.

6. Resultado da requisição: corpo do retorno da API.

7. Conteúdo obtido pela fonte de dados: corpo do retorno da API após o filtro. De todo o conteúdo retornado, a fonte de dados irá obter apenas o conteúdo do atributo informado no campo Caminho (destaque 3 da figura 3.1).

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.

Se o serviço REST utilizado possui parâmetros para os recursos de paginação e ordenação, esses campos devem ser configurados aqui. A fonte de dados possui uma série de constantes que facilitam essa conversão, acesse o tópico "Parâmetros e Constantes" da Fonte de dados para mais detalhes.

Exemplo 1 (Get)

1. URL Base: https://meusistema.com.br/api/user
2. URL: <vazio>
3. Caminho: $.data
4. Requisição: https://meusistema.com.br/api/users
5. Corpo do conteúdo enviado pela fonte de dados: <vazio>

6. Resultado da requisição:

   Bloco de código
   language js firstline 1 linenumbers true
   { "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" } }

   
   

7. Conteúdo obtido pela fonte de dados:

   Bloco de código
   language js firstline 1 linenumbers true
   [ { "id": 1, "email": "js@cronapp.io", "nome": "João Souza" }, { "id": 2, "email": "ma@cronapp.io", "nome": "Maria Andrade" }, ... ]

   
   

Exemplo 2 (Get)

1. URL Base: https://meusistema.com.br/api/user
2. URL: expression: ${primaryKey}
3. Caminho: <vazio>
4. Requisição final: https://meusistema.com.br/api/user/2
5. Corpo do conteúdo enviado pela fonte de dados: <vazio>

6. Resultado da requisição:

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 2, "email": "ma@cronapp.io", "nome": "Maria Andrade" }

   
   

7. Conteúdo obtido pela fonte de dados:

   Bloco de código
   language js firstline 1 linenumbers true
   { "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)

1. URL Base: https://meusistema.com.br/api/user
2. URL: <vazio>
3. Caminho: <vazio>
4. Requisição final: https://meusistema.com.br/api/user

5. Corpo do conteúdo enviado pela fonte de dados: 
   

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }

   
   

6. Resultado da requisição:

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }

   
   

7. Conteúdo obtido pela fonte de dados:

   Bloco de código
   language js linenumbers true
   { "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }

   
   

Exemplo 2 (Post)

1. URL Base: https://meusistema.com.br/api/user
2. URL: insert
3. Caminho: $.inserted
4. Requisição final: https://meusistema.com.br/api/user/insert

5. Corpo do conteúdo enviado pela fonte de dados:
   

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }

   
   

6. Resultado da requisição:

   Bloco de código
   language js firstline 1 linenumbers true
   { "inserted": { "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" } }

   
   

7. Conteúdo obtido pela fonte de dados::

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }

   
   

Para Atualizar (Put)

Ação utilizada para modificar algum registro. O conteúdo a ser atualizado é enviado no corpo da requisição e alguns serviços retornam o próprio elemento sinalizando sucesso na operação.

Exemplo 1 (Put)

1. URL Base: https://meusistema.com.br/api/user
2. URL: /api/insert
3. Caminho: <vazio>
4. Requisição final: https://meusistema.com.br/api/insert/3

5. Corpo do conteúdo enviado pela fonte de dados:
   

   Bloco de código
   language js firstline 1 linenumbers true
   { "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }

   
   

6. Resultado da requisição:

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }

   
   

7. Conteúdo obtido pela fonte de dados::

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }

1. "haila Dimitrescu" }

   
   

Exemplo 2 (Put)

1. URL Base: https://meusistema.com.br/api/user
2. URL: expression: update/${primaryKey}
3. Caminho: $.updated
4. Requisição final: https://meusistema.com.br/api/user/update/<Primary key>

5. Corpo do conteúdo enviado pela fonte de dados:
   

   Bloco de código
   language js firstline 1 linenumbers true
   { "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }

   
   

6. Resultado da requisição:

   Bloco de código
   language js firstline 1 linenumbers true
   { "updated": { "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" } }

   
   

7. Conteúdo obtido pela fonte de dados::

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }

   
   

Para Remover (Delete)

Operação utilizada para excluir algum recurso do serviço. Alguns serviços retornam o próprio elemento sinalizando sucesso na operação.

Exemplo 1 (Delete)

1. URL Base: https://meusistema.com.br/api/user
2. URL: <vazio>
3. Caminho: <vazio>
4. Requisição final: https://meusistema.com.br/api/user/update/<Primary key>

5. Corpo do conteúdo enviado pela fonte de dados: <desconsiderado>

6. Resultado da requisição:

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }

   
   

7. Conteúdo obtido pela fonte de dados: <desconsidereado>

Exemplo 2 (Delete)

1. URL Base: https://meusistema.com.br/api/user
2. URL: expression: delete/${primaryKey}
3. Caminho: <vazio>
4. Requisição final: https://meusistema.com.br/api/user/delete/<Primary key>

5. Corpo do conteúdo enviado pela fonte de dados: <desconsiderado>

6. Resultado da requisição:

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }

   
   

7. Conteúdo obtido pela fonte de dados: <desconsidereado>

Para Filtrar (Filter)

A ação Para Filtrar é utilizada em conjunto com a ação Para Obter, deve possuir os mesmos parâmetros utilizados em Para Obter e mais os parâmetros de filtros usados pelo recurso.

Na figura abaixo acrescentamos o parâmetro de filtro (search) usado pelo recurso e alimentamos com a constante da fonte de dados simpleFilter. A fonte de dados possui uma série de constantes que facilitam essa conversão, acesse o tópico "Parâmetros e Constantes" da Fonte de dados para mais detalhes.

Figura 3.2 - Configuração da ação Para Filtrar

Para Contar (Count)

A ação Para Contar é utilizada em conjunto com a ação Para Obter e não necessita de parâmetros próprios, mas o campo Caminho deve apontar (usando o JSON Path) para o atributos que informa a quantidade total de elementos. Esse campo normalmente é preenchido de forma automática pelo Cronapp quando executamos os passos que obtém os campos da requisição.

Figura 3.3 - Configuração da ação Para Contar

Aba Campos

A aba Campos deve conter os atributos do objeto obtido pelo serviço REST. Após executar os passos iniciais de configuração do Web Service (destaque 1 da figura 4.1), o Cronapp tenta obter e configurar automaticamente todos os campos na aba Campos, deixando o campo com o mesmo nome do atributo do objeto. É possível adicionar um novo campo (2) e em seguida configurar na janela Caminho (3) o nome do atributo do objeto que vai alimentar esse campo. O campo da janela Caminho espera receber um JSON Path a partir do objeto principal.

Figura 4.1 - Configuração da aba Campos

Aba Cabeçalhos

Permite configurar os cabeçalhos das requisições HTTP. Por padrão, os campos Accept e Content-Type já vem definidos em fontes de dados do tipo Web Services, porém é possível alterá-los e adicionar novos cabeçalhos usados pelo recurso RESTweb.

Serviços privados Um exemplo de uso dos cabeçalhos são em serviços REST privados que necessitam de algum tipo de autenticação e normalmente é enviado são enviados pelo cabeçalho. Para alimentar esses campos, podemos usar as constantes de token ou selecionar um bloco de programação que retorna esse dado (destaque 1 da figura 5.1). Para mais detalhes sobre as constantes, acesse o tópico "Parâmetros e Constantes" da Fonte de dados.

Figura 5.1 - Configuração da aba Cabeçalhos