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 20 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:

  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 (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, definindo uma constante Cronapp, expressão FTL ou bloco de programação. Veja mais detalhes sobre as constantes no tópico "Parâmetros e Constantes" da Fonte de dados.

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 em exemplo2 (post)), 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 em exemplo1 (put)).
    • 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 da requisição enviada 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. Corpo da requisição retornada pela API: corpo do retorno da API.

  7. Corpo da requisição retornada pela API após o filtro: 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 da requisição enviado pela fonte de dados: <vazio>

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

  7. Corpo da requisição retornada pela API após o filtro:

    [
    {
        "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 da requisição enviada pela fonte de dados: <vazio>

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

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

  7. Corpo da requisição retornada pela API após o filtro:

    {
    "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 da requisição enviada pela fonte de dados: 

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


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

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

  7. Corpo da requisição retornada pela API após o filtro:

    {
    "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 da requisição enviada pela fonte de dados:

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


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

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

  7. Corpo da requisição retornada pela API após o filtro::

    {
    "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 da requisição enviada pela fonte de dados:

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


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

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

  7. Corpo da requisição retornada pela API após o filtro:

    {
    "id": 3,
    "email": "hd@cronapp.io",
    "nome": "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 da requisição enviada pela fonte de dados:

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


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

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

  7. Corpo da requisição retornada pela API após o filtro:

    {
    "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 da requisição enviada pela fonte de dados: <desconsiderado>

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

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

  7. Corpo da requisição retornada pela API após o filtro: <desconsiderado>

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 da requisição enviada pela fonte de dados: <desconsiderado>

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

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

  7. Corpo da requisição retornada pela API após o filtro: <desconsiderado>

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

Cabeçalhos são utilizados, por exemplo, em serviços REST privados que necessitam de algum tipo de autenticação e normalmente são enviados via 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

Conteúdo complementar

Fonte de Dados

  • Sem rótulos