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 publicação, 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 ferramenta interna precisa solicitar dados ou disparar processamento sob demanda, por exemplo uma aplicação 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 da API diretamente da operação. Alternativamente, o mesmo resultado pode ser obtido pela interface do API Manager (consulte Custom API).

Este guia pressupõe o seguinte:

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

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

Padrão de design

flowchart LR A[Cliente da API] -->|Requisição HTTP| B[API Manager custom API] --> C[Operação do Studio] -->|Resposta HTTP| A

Parte 1: Publicar a operação como API

Etapa 1: Abrir a configuração da API

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

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

    A gaveta de configuração da API abre na parte inferior do designer de projetos.

    Nota

    Esta opção só está disponível 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 da 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). Este 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 string de versão (por exemplo, v1). Isso se torna parte da URL do endpoint.

  4. Clique em Next.

Etapa 3: Configurar as definições

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

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

  2. Timeout: Defina o tempo máximo que o API Manager aguarda a 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 da 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 acessam 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 registros), 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 código de status da resposta. Consulte a Parte 2 para 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á termina com uma atividade API Response.
    • No Response: O API Manager retorna um 202 Accepted vazio imediatamente sem aguardar a conclusão da operação. Use isso para operações de longa duração do tipo "disparar e esquecer" 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 a alternância Atribuir ao lado dele.

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

    Dica

    Deixar o endpoint sem nenhum 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 em 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 fica ativa em até 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 do Harmony. Salve como Rascunho se preferir concluir a configuração antes de tornar o endpoint ativo.

Parte 2: Retornar uma resposta da operação

Quando o Tipo de resposta está 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 vazia 200 OK.

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

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 que você atribuiu.

  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.