Chamar uma API REST usando o conector HTTP v2 no Jitterbit Studio

Introdução

O conector HTTP v2 estabelece acesso por meio do protocolo HTTP ou HTTPS a serviços como APIs REST, APIs GraphQL e formulários da web.

Este guia aborda dois padrões comuns para trabalhar com APIs REST no Studio:

• Usar uma atividade HTTP v2 GET como origem para recuperar dados de um endpoint de API REST.
• Usar uma atividade HTTP v2 POST como destino para enviar dados para um endpoint de API REST, incluindo webhooks.

Os mesmos princípios se aplicam aos tipos de atividade PUT, PATCH e DELETE.

Configurar uma conexão HTTP v2

Antes de criar atividades HTTP v2, configure uma conexão com a API REST.

1. No Studio, abra um projeto e clique na aba Endpoints e conectores do projeto na paleta de componentes de design.

2. Clique no conector HTTP v2 para abrir a tela de configuração de conexão.

3. Nome da conexão: Digite um nome exclusivo que identifique o serviço de API REST, por exemplo Customer API. O nome não pode conter barras / ou dois-pontos :.

4. URL base: Digite a URL base da API, por exemplo https://api.example.com/v1. Atividades individuais podem estender esta URL com um sufixo de caminho ou substituí-la inteiramente por uma URL completa.

5. Autorização: Use o menu para selecionar o tipo de autenticação exigido pela API. As opções comuns incluem:

   • Sem autenticação: Para endpoints públicos que não exigem autenticação.
   • Chave de API: Envia um par chave-valor como cabeçalho ou parâmetro de consulta.
   • Token de portador: Envia um token de portador no cabeçalho Authorization.
   • Autenticação básica: Envia um nome de usuário e senha codificados em base64 no cabeçalho Authorization.

   Para uma descrição completa de todos os tipos de autenticação, consulte Tipos de autenticação de conexão HTTP v2.

   Dica

   Os campos de conexão suportam variáveis de projeto. Use variáveis de projeto para credenciais como chaves de API, tokens de portador e senhas para evitar armazenar valores sensíveis diretamente na configuração de conexão.

6. Clique em Testar para verificar a conexão. Um teste é bem-sucedido se a API retorna qualquer código de status 2xx (ou 405 Method Not Allowed).

7. Clique em Salvar alterações.

Recuperar dados usando uma solicitação GET

Uma atividade HTTP v2 GET é usada como uma origem em uma operação. Ela envia uma solicitação HTTP GET para a API REST e fornece a resposta como entrada para a próxima etapa na operação, geralmente uma transformação.

A operação segue o padrão de transformação:

Criar uma atividade GET

Na paleta de componentes de design, expanda o endpoint HTTP v2 que você criou. Arraste o tipo de atividade GET para a tela de design para criar uma instância de atividade. Clique duas vezes na atividade para abrir sua configuração.

Etapa 1: Inserir um nome e especificar configurações

1. Nome: Digite um nome exclusivo para a atividade, por exemplo Get Customer.

2. Caminho: Digite o caminho do recurso relativo à URL base, por exemplo /customers/{id}. A URL de runtime completa é mostrada no campo URL abaixo de Caminho.

   • Se deixado em branco, a URL base da conexão é usada no runtime.
   • Um caminho parcial é acrescentado à URL base.
   • Uma URL completa substitui a URL base.

Para incluir um parâmetro de caminho, coloque-o entre chaves, por exemplo {id}. Para mais informações, consulte Usar variáveis no caminho da URL abaixo.

1. Parâmetros de Solicitação: Clique no ícone adicionar para adicionar parâmetros de consulta como linhas chave-valor, por exemplo limit / 100. Os parâmetros de solicitação são codificados automaticamente na URL.

2. Cabeçalhos de Solicitação: Clique no ícone adicionar para adicionar cabeçalhos de solicitação como linhas chave-valor, por exemplo Accept / application/json. Os cabeçalhos definidos aqui são aplicados além de quaisquer cabeçalhos definidos na conexão.

3. Clique em Próximo.

Etapas 2 e 3: Fornecer esquemas

A Etapa 2 permite fornecer um esquema de solicitação personalizado (opcional para solicitações GET, que normalmente não possuem corpo). A Etapa 3 permite fornecer um esquema de resposta personalizado.

Se a API REST retorna uma estrutura JSON conhecida, forneça um esquema JSON personalizado na Etapa 3 selecionando Sim, Fornecer Novo Esquema e inserindo ou colando o esquema. Isso permite que a transformação mapeie campos individuais da resposta da API.

Se nenhum esquema de resposta personalizado for fornecido, o esquema de resposta padrão do conector será utilizado. O esquema padrão expõe o corpo da resposta completa como um único campo responseContent.

Etapa 4: Revisar os esquemas de dados

Os esquemas de solicitação e resposta configurados são exibidos. Clique em Concluído para salvar a configuração da atividade. Os esquemas também estão disponíveis em qualquer transformação adjacente na tela de design.

Acessar a resposta em uma transformação

Na transformação a jusante, mapeie campos do esquema de resposta da atividade GET para o esquema de destino:

• Se um esquema de resposta personalizado foi fornecido, os campos individuais da resposta JSON analisada estão disponíveis para mapeamento.
• Se o esquema de resposta padrão for utilizado, o campo responseContent contém o corpo da resposta bruta como uma string. Use a função JSONParser em um script para analisá-lo, se necessário.

Enviar dados usando uma solicitação POST

Uma atividade POST HTTP v2 é utilizada como um destino em uma operação. Uma transformação mapeia dados de origem para o corpo da solicitação POST, e a atividade os envia para o ponto de extremidade da API REST. Esse padrão também se aplica ao envio de dados para pontos de extremidade de webhook.

A operação segue o padrão de transformação:

Criar uma atividade POST

Na paleta de componentes de design, arraste o tipo de atividade POST do ponto de extremidade HTTP v2 para a tela de design. Clique duas vezes na atividade para abrir sua configuração.

Etapa 1: Inserir um nome e especificar configurações

1. Nome: Insira um nome único para a atividade, por exemplo Criar Pedido.

2. Caminho: Insira o caminho do recurso relativo à URL Base, por exemplo /orders. Para enviar para um webhook, insira a URL completa do webhook aqui: uma URL completa substitui a URL Base da conexão.

3. Cabeçalhos de Solicitação: Adicione quaisquer cabeçalhos necessários pela API. Para APIs REST que aceitam JSON, adicione Content-Type / application/json.

4. Clique em Próximo.

Etapas 2 e 3: Fornecer esquemas

A Etapa 2 (Esquema de solicitação) define a estrutura do corpo da solicitação. A Etapa 3 (Esquema de resposta) é opcional e captura a resposta da API.

Para definir a estrutura do corpo da solicitação:

1. Na Etapa 2, selecione Sim, Fornecer Novo Schema e insira ou cole o schema JSON que corresponde ao corpo da solicitação esperado pela API. Os campos neste schema ficam disponíveis na transformação upstream para mapeamento.

2. Na Etapa 3, opcionalmente forneça um schema de resposta para capturar os campos retornados pela API, por exemplo um ID de recurso criado.

3. Clique em Concluído.

Mapear dados de origem para o corpo da solicitação

Na transformação upstream, mapeie os campos de origem para os campos definidos no schema de solicitação da atividade POST. A saída da transformação se torna o corpo da solicitação HTTP em tempo de execução.

Usar variáveis no caminho da URL

Os caminhos de URL podem ser tornados dinâmicos usando três técnicas:

• Parâmetros de caminho são placeholders no campo Caminho colocados entre chaves, por exemplo /customers/{customerId}. Em tempo de execução, o conector substitui o valor do campo correspondente do schema de solicitação. Na transformação upstream, mapeie o valor de origem para o campo customerId no schema de solicitação.

• Variáveis de projeto podem ser usadas em qualquer lugar onde um ícone de variável apareça nos campos de conexão ou atividade. Digite um colchete aberto [ no campo ou clique no ícone de variável para selecionar uma variável de projeto. Isto é útil para valores específicos do ambiente, como uma URL base que difere entre desenvolvimento e produção. Consulte variáveis de projeto para mais informações.

• Variáveis globais podem ser definidas por um script executado antes da operação HTTP v2 em uma cadeia de operações. O script atribui um valor a uma variável global (por exemplo, $gv_customer_id = "12345"), e o campo Caminho referencia a variável (por exemplo, /customers/$gv_customer_id). Consulte variáveis globais para mais informações.