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

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.

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.

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:

    {
    "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:

    [
    {
        "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:

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

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

  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: 

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


  6. Resultado da requisição:

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

  7. Conteúdo obtido pela fonte de dados:

    {
    "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:

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


  6. Resultado da requisição:

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

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

  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:

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


  6. Resultado da requisição:

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

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

    {
    "id": 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 ???

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:

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


  6. Resultado da requisição:

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

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

  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:

    {
    "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:

    {
    "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)


Nesta página

  • Sem rótulos