Consumir APIs REST externas no Jitterbit App Builder

Introdução

Este guia oferece uma visão geral de como conectar e consumir APIs REST externas como fontes de dados dentro do App Builder. A configuração do servidor de fonte de dados REST é utilizada em todos os endpoints REST.

Configurar e usar uma fonte de dados REST envolve estas etapas principais:

1. Criar um servidor de fonte de dados REST: Estabelecer a conexão inicial com a URL base da API REST.

2. Configurar e adicionar endpoints: Definir os endpoints específicos da API que você deseja acessar, incluindo seus parâmetros, cabeçalhos e métodos.

3. Usar Objetos REST para integração completa: Abstrair a API configurada em um Objeto REST para operações CRUD e integração de UI sem interrupções.

Ao longo deste guia, a gratuita Alpha Vantage API de dados de ações é utilizada como um exemplo prático.

Criar um servidor de fonte de dados REST

Para criar um servidor de dados REST, siga estas etapas:

1. Selecione IDE > Servidores de Dados.

2. Clique no botão + Servidor.

3. Na seção Configurações do Servidor, preencha os seguintes campos:

   • Nome do Servidor: Insira um nome descritivo para o servidor. Para nosso exemplo, use Alpha Vantage.

   • Tipo: Selecione API REST.

   • URL: Insira a URL base fornecida na documentação da sua API. Para Alpha Vantage, esta é https://www.alphavantage.co/.

     Nota

     Endpoints específicos são configurados em uma etapa posterior.

   • Tipo de Conteúdo da Solicitação e Tipo de Conteúdo da Resposta: Selecione os tipos de conteúdo da solicitação e da resposta. Normalmente, isso é JSON.

4. (Opcional) Expanda a seção Configurações de Segurança se sua API exigir autenticação de nome de usuário/senha no nível do servidor.

   Dica

   A maioria das APIs REST, incluindo a Alpha Vantage, usa uma chave de API no cabeçalho ou na string de consulta. Isso é configurado na próxima seção.

5. (Opcional) Descrição: Insira uma descrição para este servidor.

6. Clique no botão Salvar e, em seguida, feche o diálogo. Você deve ver seu novo servidor de dados REST na lista.

Configurar e adicionar endpoints REST

Após criar o servidor de fonte de dados, é necessário configurar seus parâmetros e definir os endpoints da API que você deseja acessar.

Configurar parâmetros comuns (cabeçalhos e strings de consulta)

Você pode definir parâmetros que se aplicam a todos os endpoints no servidor, como para autenticação. A maioria dos serviços REST exige que você passe uma chave de API.

Para configurar um parâmetro comum, siga estas etapas:

1. Na lista de Servidores de Dados, clique no botão Abrir registro para seu novo servidor de dados REST.

2. Na janela pop-up Servidor, em Configurações do Servidor, clique no ícone Endpoints.

3. No painel Parâmetros do Serviço Web, clique no botão + Parâmetro. Uma nova linha aparecerá.

4. Defina os valores com base nos requisitos da sua API. Para nosso exemplo da Alpha Vantage, precisamos adicionar a chave da API como um parâmetro de string de consulta:

   • Tipo: Selecione Consulta.

   • Nome: Insira o nome do parâmetro. Para este exemplo, use apikey. O nome deve corresponder ao que a API espera.

   • Valor: Cole sua chave de API única.

   • Tipo de Uso: (Opcional) Selecione um tipo de uso.

5. Clique no ícone para salvar o parâmetro.

Adicionar um endpoint REST

Uma vez que seu servidor de dados REST tenha sido configurado, você pode adicionar endpoints específicos da API.

Para adicionar um endpoint, siga estas etapas:

1. No painel Endpoints, clique no botão + Endpoint. Uma nova linha aparecerá.

2. Defina os valores na linha da seguinte forma. Para nosso exemplo, criaremos um endpoint para obter uma cotação de ações global:

   • Nome: Dê ao endpoint um nome descritivo. Para este exemplo, use global_quote. Este nome é usado para identificar a tabela de dados resultante no App Builder.

   • Endpoint: Insira a parte da URL que especifica o recurso. Para este exemplo, uma cotação global é obtida inserindo o seguinte, que inclui um espaço reservado {{ticker}} para um parâmetro definido a seguir:

query?function=GLOBAL_QUOTE&symbol={{ ticker }}

• Método: Selecione o método HTTP. Para este exemplo, selecione GET.

• Clique no ícone para salvar o endpoint.

Definir parâmetros específicos do endpoint

Agora adicione um parâmetro para o ticker da ação a ser consultado:

1. No painel Parâmetros do Serviço Web, clique em + Parâmetro novamente.

2. Defina os valores da seguinte forma:

   • Tipo: Selecione Consulta.

   • Nome: Insira um nome para este parâmetro. Para este exemplo, ticker.

   • Valor: Deixe em branco, pois queremos fornecer isso dinamicamente.

   • Tipo de Uso: Selecione Entrada.

   • Valor de Teste: Insira AAPL (para Apple Corp.) para fins de teste.

3. Clique no ícone para salvar o parâmetro.

Testar a conexão

Por fim, teste o endpoint para garantir que sua configuração está correta.

1. No painel Endpoints, selecione o endpoint global_quote recém-criado.

2. Clique em Testar Conexão, depois em Prosseguir.

Se a configuração estiver correta, uma mensagem "Teste de conexão bem-sucedido" aparecerá, e os dados retornados da API (as informações para AAPL) serão exibidos na seção Resultados de Texto.

Seu endpoint de API agora está conectado. O App Builder cria automaticamente uma tabela de dados chamada global_quote (do nome do endpoint) na fonte de dados Alpha Vantage, que você pode usar para construir componentes de UI.

Alternativa: Importar de um documento OpenAPI

Se você tiver um documento OpenAPI (Swagger) para sua API REST, pode importá-lo para gerar endpoints automaticamente. Consulte Importar um documento OpenAPI para instruções detalhadas.

Usar Objetos REST para integração completa

Objetos REST permitem que os desenvolvedores do App Builder utilizem APIs REST de maneira semelhante aos objetos de dados do App Builder, possibilitando operações completas de CRUD (Criar, Ler, Atualizar, Excluir), eventos personalizados e integração avançada de UI.

Para APIs REST que suportam operações no estilo CRUD, configurar um Objeto REST é uma maneira fácil de integrar uma API com seu aplicativo App Builder.

Configurar endpoints CRUD

Para uma API REST no estilo CRUD, você deve configurar endpoints que permitam que os registros passem por operações de Criar, Ler, Atualizar e Excluir. Isso geralmente envolve a configuração dos seguintes endpoints em sua fonte de dados REST:

Siga os passos em Adicionar um Endpoint REST para cada operação CRUD que você precisar, fornecendo o Nome, Endpoint, Método e qualquer Entrada de Exemplo necessária para os métodos POST ou PUT.

Criar um Objeto REST

Uma vez que seus endpoints CRUD tenham sido configurados, você pode criar o Objeto REST.

1. Selecione IDE > Servidores de Dados.

2. Selecione seu servidor de dados REST e clique em Abrir registro para a API REST. A janela pop-up API REST é aberta.

3. Em API REST, clique em Endpoints.

4. Em Serviço Web, clique em Mais > Super Objetos. A caixa de diálogo Objetos REST é aberta.

5. Clique em + Objeto REST.

6. Insira um nome para seu objeto REST (por exemplo, Clientes), em seguida, clique no ícone Salvar.

7. Clique no ícone de edição de lápis , ative Inserir, Atualizar e Excluir conforme apropriado, em seguida, clique novamente no ícone Salvar.

Configurar e vincular o objeto REST

Após criar o Objeto REST, é necessário configurar seu Single Comp e Many Comp e vincular as operações CRUD aos seus endpoints.

1. Configurar Single e Many Comps: Abra o Objeto REST e configure o Single Comp e Many Comp adicionando as tabelas apropriadas (por exemplo, customers(get)/items) e colunas do seu endpoint de leitura.

2. Configurar Endpoints CRUD: Para cada operação CRUD (Excluir, Inserir, Atualizar), selecione o endpoint correspondente que você criou e vincule os campos do Objeto REST aos parâmetros de entrada do endpoint.

Agora você deve ser capaz de usar este Objeto REST na interface do usuário do seu aplicativo e adicionar, excluir ou atualizar linhas como se fosse uma tabela nativa do App Builder.

Recursos avançados: Classificação, paginação e filtragem

Os Objetos REST também suportam recursos avançados de interação com dados. Para habilitá-los, é necessário configurar parâmetros específicos em sua fonte de dados REST com o tipo de Uso correto:

• Classificação: Adicione um parâmetro com o tipo de Uso definido como Request Sort. O nome do parâmetro deve corresponder ao que sua API espera (por exemplo, $sort).

• Paginação: Configure parâmetros para Request Limit, Request Offset (ou Request Page Number) e Request Count. Você também precisa definir o tipo de Uso da coluna count em sua tabela de resposta como Response Total Rows.

• Filtragem: Adicione um parâmetro com o tipo de Uso definido como Request Filter (OData) para filtragem no estilo OData. O nome do parâmetro deve corresponder ao que sua API espera (por exemplo, $filter).