Ir para o conteúdo

Expor uma operação como API REST no Jitterbit Studio

Introdução

O API Manager permite publicar uma operação do Studio como um endpoint HTTP que qualquer chamador autorizado pode invocar sob demanda. Após publicada, o endpoint aceita uma requisição HTTP, executa a operação vinculada de forma síncrona e retorna a saída da operação como resposta HTTP.

Esse padrão é útil quando um sistema externo ou uma ferramenta interna precisa solicitar dados ou disparar processamento sob demanda, por exemplo um aplicativo web que consulta registros de clientes, um sistema parceiro que envia pedidos para processamento ou um painel interno que dispara a geração de relatórios.

Este guia usa a opção Publish as an API integrada do Studio, que abre a configuração de API diretamente da operação. Como alternativa, o mesmo resultado pode ser obtido na interface do API Manager (consulte Custom API).

Este guia assume o seguinte:

  • Uma API customizada está configurada e publicada no API Manager no mesmo ambiente do projeto.
  • A operação a ser exposta como uma API já está construída e implantada.

Para o padrão complementar (receber webhooks acionados por eventos de sistemas externos), consulte Acionar uma operação do Studio a partir de um webhook.

Padrão de design

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A[Cliente API] -->|Requisição HTTP| B[API Manager custom API] --> C[Operação do Studio] -->|Resposta HTTP| A

Parte 1: Publicar a operação como uma API

Etapa 1: Abrir a configuração de API

  1. Na tela de design, localize a operação a publicar.

  2. Clique no ícone de menu de ações da operação e selecione Publish as an API.

    A gaveta de configuração de API se abre na parte inferior do designer de projeto.

    Nota

    Essa opção fica disponível apenas se a operação não tiver alterações não implantadas. Implante a operação primeiro se a opção não estiver disponível.

Etapa 2: Configurar o perfil de API

Na etapa Profile, insira os detalhes básicos da API:

  1. API Name: Insira um nome para identificação interna (por exemplo, Customer Query API). Esse nome aparece no API Manager e nos logs de operação.

  2. Service Root: Insira o segmento de caminho base usado na URL do endpoint público (por exemplo, customers). Este campo é preenchido previamente com o nome da operação em camel case. Espaços não são permitidos.

  3. Version number: Insira uma cadeia de versão (por exemplo, v1). Isso se torna parte da URL do endpoint.

  4. Clique em Next.

Etapa 3: Configurar definições

Na etapa Settings, configure o comportamento do tempo de execução:

  1. SSL only: Deixe ativado. Isso exige HTTPS e é recomendado para todos os endpoints de produção.

  2. Timeout: Defina o tempo máximo que o API Manager espera pela operação ser concluída antes de retornar um erro de timeout. O padrão é 30 segundos; o máximo é 180 segundos.

  3. Verbose logging: Ative durante o desenvolvimento para incluir dados de requisição e resposta nos logs de API. Desative em produção para evitar arquivos de log grandes.

  4. Clique em Next.

Etapa 4: Configurar o endpoint de serviço

Na etapa Services, defina como os chamadores alcançam a operação:

  1. Method: Selecione o método HTTP que os chamadores usarão. Para operações de leitura, selecione GET. Para operações que aceitam um corpo de requisição (envio de dados, criação de registro), selecione POST.

  2. Path: Insira o subcaminho anexado à URL base (por exemplo, /records ou /submit).

  3. Response Type: Selecione como a operação retorna sua resposta ao chamador:

    • System Variable: O corpo da resposta é o valor atribuído a $jitterbit.api.response na operação. Use isso na maioria dos casos, pois oferece controle total sobre o conteúdo e o código de status da resposta. Consulte a Parte 2 para obter detalhes.
    • Final Target: A resposta é a saída de uma atividade API Response no final da cadeia de operações. Use isso quando a operação já terminar com uma atividade API Response.
    • No Response: O API Manager retorna um 202 Accepted vazio imediatamente sem esperar a operação ser concluída. Use isso para operações de longa duração fire-and-forget em que o chamador não precisa de um resultado.

  4. Clique em Próximo.

Etapa 5: Adicionar um perfil de segurança

Na etapa Perfis de segurança, atribua pelo menos um perfil de segurança para restringir o acesso ao endpoint.

  1. Para usar um perfil existente, ative o botão de alternância Atribuir ao lado dele.

  2. Para criar um novo perfil, clique em Novo perfil de segurança e siga os prompts. Chave de API e autenticação básica são as opções mais comuns para integrações máquina a máquina. Para APIs voltadas para o usuário que exigem identidade, use OAuth 2.0.

    Dica

    Deixar o endpoint sem um perfil de segurança atribuído o torna acessível publicamente para qualquer pessoa com a URL. Sempre atribua um perfil de segurança antes de publicar para produção.

  3. Clique em Próximo.

Etapa 6: Publicar

  1. Na etapa Funções de usuário, opcionalmente restrinja o acesso por função organizacional. Clique em Próximo se nenhuma restrição de função for necessária.

  2. Clique em Publicar.

    A API estará ativa em cinco minutos. O API Manager exibe a URL completa do endpoint no formato https://<host>/<service-root>/<version>/<path>. Copie esta URL para compartilhar com o chamador da API.

    Nota

    Uma API publicada conta como uma URL de API em relação à sua cota de assinatura Harmony. Salve como Rascunho em vez disso se deseja concluir a configuração antes de deixar o endpoint ativo.

Parte 2: Retornar uma resposta da operação

Quando o Tipo de resposta é definido como Variável de sistema, a operação deve atribuir o corpo da resposta a $jitterbit.api.response antes de ser concluída. Adicione uma etapa de script no final da operação (ou no final da cadeia de operações) para definir este valor.

  • Retornar uma resposta JSON:

    <trans>
$jitterbit.api.response = JSONStringify($result_dict);
$jitterbit.api.response.status_code = 200;
</trans>

  • Retornar uma resposta de texto simples:

    <trans>
$jitterbit.api.response = "Processing complete";
$jitterbit.api.response.status_code = 200;
</trans>

  • Retornar uma resposta de erro:

    <trans>
$err_response = Dict();
$err_response["error"] = "Record not found";
$jitterbit.api.response = JSONStringify($err_response);
$jitterbit.api.response.status_code = 404;
</trans>

Se $jitterbit.api.response não for definido antes da operação ser concluída, o API Manager retorna uma resposta 200 OK vazia.

Para obter a lista completa de variáveis API Jitterbit, consulte Variáveis API Jitterbit.

Verificar a integração

  1. Implante o projeto se tiver feito alterações desde a publicação.

  2. No API Manager, copie a URL do endpoint publicado na página APIs.

  3. Envie uma solicitação de teste para o endpoint usando uma ferramenta como curl ou Postman, incluindo o cabeçalho de autorização apropriado para o perfil de segurança atribuído.

  4. Confirme que o corpo da resposta HTTP e o código de status correspondem aos valores definidos na operação.

  5. Abra os logs de API no API Manager e os logs de operação no Studio para confirmar que a solicitação foi recebida e a operação foi concluída com sucesso.

Para adicionar autenticação à própria operação (por exemplo, para validar um JWT em uma etapa de script antes de processar a solicitação), consulte Autenticar endpoints de API usando JWT.