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 REST e SOAP.

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 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), 

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 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.

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). 

• 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.

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.

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.

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.

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

Configuração da 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.

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.

Após executar os passos para obter os campos do serviço, a rota do método HTTP GET (Para Obter) já estará configurado

Para Obter (Get) - exemplo 1

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.

Abaixo listamos as principais ações utilizadas e apresentamos exemplos de como configurá-las.

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"

7. URL Base: https://meusistema.com.br/api/user
8. URL: <vazio>
9. Caminho: $.data
10. Requisição final: https://meusistema.com.br/api/users
11. Corpo do conteúdo enviado pela fonte de dados: <vazio>

12. 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": [ { }, ... ], "idsupport": 1,{ "emailurl": "js@cronapphttps://www.cronapp.io", "nometext": "João Souzathis is an example" },} }

    
    

13. Conteúdo obtido pela fonte de dados:

    Bloco de código
    language js firstline 1 linenumbers true
    [ { "id": 21, "email": "ma@cronappjs@cronapp.io", "nome": "MariaJoão AndradeSouza" }, ...{ ], "supportid": {2, "urlemail": "https://www.cronapp "ma@cronapp.io", "textnome": "this is an example" } }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 Conteúdo obtido pela fonte de dados: <vazio>

6. Resultado da requisição:

   Bloco de código
   language js firstline 1 linenumbers true
   [ { "id": 12, "email": "js@cronappma@cronapp.io", "nome": "JoãoMaria SouzaAndrade" }, { }

   
   

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" }, ... ]

1. }

   
   

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: expression: /${primaryKey}
3. Caminho: <vazio>
4. Requisição final: https://meusistema.com.br/api/user/2
5. : <vazio>
6. Caminho: <vazio>
7. Requisição final: https://meusistema.com.br/api/user

8. 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" }

   Corpo do conteúdo enviado pela fonte de dados: <vazio>

   
   

9. Resultado da requisição:

   Bloco de código
   language js firstline 1 linenumbers true
   { "id": 23, "email": "ma@cronapppp@cronapp.io", "nome": "MariaPedro AndradePorto" }

   
   

10. Conteúdo obtido pela fonte de dados:

    Bloco de código
    language js firstline 1 linenumbers true
    { "id": 23, "email": "ma@cronapppp@cronapp.io", "nome": "MariaPedro AndradePorto" }

Exemplo 2 (Post)

1. URL Base: https://meusistema.com.br/api/user
2. URL: <vazio>insert
3. Caminho: <vazio>$.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: $.inserted<vazio>
4. Requisição final: https://meusistema.com.br/api/userinsert/insert3

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

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

   
   

6. Resultado da requisição:

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

   
   

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

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

1. Dimitrescu" }

   
   

<TODO> O caminho no Put serve para filtrar o JSON no corpo da requisição da Fonte de dados para o serviço REST ou no corpo da resposta do serviço REST para a Fonte de dados ???

Exemplo 2 (Put)

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/3
5. expression: update/${primaryKey}
6. Caminho: $.updated
7. Requisição final: https://meusistema.com.br/api/user/update/<Primary key>

8. Corpo do conteúdo enviado pela fonte de dados

   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" }

   Resultado da requisição:
   

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

   
   

9. Conteúdo obtido pela fonte de dados:Resultado da requisição:

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

<TODO> O caminho no Put serve para filtrar o JSON no corpo da requisição da Fonte de dados para o serviço REST ou no corpo da resposta do serviço REST para a Fonte de dados ???

Para Atualizar (Put) - exemplo 2

1. "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" } }

   
   

2. Conteúdo obtido pela fonte de dados:

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

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

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

   Resultado da requisição:

   }

   
   

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
   { "updated": { "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" } }

   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. 
   

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

Exemplo 2 (Delete)

1. URL Base: https://meusistema.com.br/api/user
2. URL: <vazio>: expression: delete/${primaryKey}
3. Caminho: <vazio>
4. Requisição final: https://meusistema.com.br/api/user/updatedelete/<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)

Resultado da requisição:

{
    "id": 3,
    "email": "hd@cronapp.io",
    "nome": "haila Dimitrescu"  
}

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.

Image Added

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

Para Contar (Count)