- Criado por Igor Andrade, última alteração em 09/08/2021
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 17 Próxima »
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, realizar os passos abaixo:
- Obter campos do serviço: executa alguns passos para obter os campos do objeto;
- 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.
- Aba Campos: se necessário, é possível personalizar os campos obtidos na primeira etapa.
- 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 (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.
Caso a API externa necessite de autenticação para obter dados (Verbo Get), será necessário configurar previamente a aba Cabeçalhos e só então executar esses passos.
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.
O endereço JSON (JSON Path) é uma notação utilizada para navegar em uma estrutura JSON. O objeto principal é definido com o símbolo dólar ($
), o colchete ([]
) é utilizado para selecionar um elemento em uma lista e o ponto ( .
) é utilizado para acessar um objeto vinculado a um atributo.
Utilizando como exemplo a figura 2.3, para obtermos o nome do usuário do primeiro elemento do array, usaríamos o endereço: $.data[0].name
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 (figura 2.7), 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
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.
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.
- Campo vazio: a requisição será feita a partir de "
- 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 atributodata
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:
- URL Base: endereço usado para configurar a fonte de dados (destaque 1 da figura 3.1).
- URL: campo usado para personalizar o endPoint em cada Ação (destaque 2 da figura 3.1).
- 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).,
- Requisição: endereço da requisição montado a partir da configuração dos campos URL Base (1) e URL (2).
- 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.
Resultado da requisição: corpo do retorno da API.
- 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)
- URL Base: https://meusistema.com.br/api/user
- URL: <vazio>
- Caminho: $.data
- Requisição: https://meusistema.com.br/api/users
- Corpo do conteúdo enviado pela fonte de dados: <vazio>
Resultado da requisição:
{ "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" } }
Conteúdo obtido pela fonte de dados:
[ { "id": 1, "email": "js@cronapp.io", "nome": "João Souza" }, { "id": 2, "email": "ma@cronapp.io", "nome": "Maria Andrade" }, ... ]
Exemplo 2 (Get)
- URL Base: https://meusistema.com.br/api/user
- URL: expression: ${primaryKey}
- Caminho: <vazio>
- Requisição final: https://meusistema.com.br/api/user/2
- Corpo do conteúdo enviado pela fonte de dados: <vazio>
Resultado da requisição:
{ "id": 2, "email": "ma@cronapp.io", "nome": "Maria Andrade" }
Conteúdo obtido pela fonte de dados:
{ "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)
- URL Base: https://meusistema.com.br/api/user
- URL: <vazio>
- Caminho: <vazio>
- Requisição final: https://meusistema.com.br/api/user
Corpo do conteúdo enviado pela fonte de dados:
{ "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }
Resultado da requisição:
{ "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }
Conteúdo obtido pela fonte de dados:
{ "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }
Exemplo 2 (Post)
- URL Base: https://meusistema.com.br/api/user
- URL: insert
- Caminho: $.inserted
- Requisição final: https://meusistema.com.br/api/user/insert
Corpo do conteúdo enviado pela fonte de dados:
{ "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" }
Resultado da requisição:
{ "inserted": { "id": 3, "email": "pp@cronapp.io", "nome": "Pedro Porto" } }
Conteúdo obtido pela fonte de dados::
{ "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)
- URL Base: https://meusistema.com.br/api/user
- URL: /api/insert
- Caminho: <vazio>
- Requisição final: https://meusistema.com.br/api/insert/3
Corpo do conteúdo enviado pela fonte de dados:
{ "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }
Resultado da requisição:
{ "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }
Conteúdo obtido pela fonte de dados::
{ "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }
Exemplo 2 (Put)
- URL Base: https://meusistema.com.br/api/user
- URL: expression: update/${primaryKey}
- Caminho: $.updated
- Requisição final: https://meusistema.com.br/api/user/update/<Primary key>
Corpo do conteúdo enviado pela fonte de dados:
{ "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }
Resultado da requisição:
{ "updated": { "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" } }
Conteúdo obtido pela fonte de dados::
{ "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)
- URL Base: https://meusistema.com.br/api/user
- URL: <vazio>
- Caminho: <vazio>
- Requisição final: https://meusistema.com.br/api/user/update/<Primary key>
Corpo do conteúdo enviado pela fonte de dados: <desconsiderado>
Resultado da requisição:
{ "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }
Conteúdo obtido pela fonte de dados: <desconsidereado>
Exemplo 2 (Delete)
- URL Base: https://meusistema.com.br/api/user
- URL: expression: delete/${primaryKey}
- Caminho: <vazio>
- Requisição final: https://meusistema.com.br/api/user/delete/<Primary key>
Corpo do conteúdo enviado pela fonte de dados: <desconsiderado>
Resultado da requisição:
{ "id": 3, "email": "hd@cronapp.io", "nome": "haila Dimitrescu" }
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 web.
Um exemplo de uso dos cabeçalhos são em serviços REST privados que necessitam de algum tipo de autenticação e normalmente 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
Nesta página
- Sem rótulos