Configuração de API proxy no Jitterbit API Manager

Introdução

Esta página descreve como criar e configurar uma API proxy a partir da página APIs do Jitterbit API Manager. Uma API proxy é um dos três tipos de APIs configurados através do API Manager. Para os outros dois tipos, API personalizada e serviço OData, consulte Configuração de API personalizada e Configuração de serviço OData.

Alternativamente, crie serviços OData usando o Assistente de IA do APIM.

Pré-requisitos

Diferentemente de uma API personalizada ou serviço OData, que expõe uma operação Harmony para consumo, uma API proxy é usada com uma API existente. APIs proxificadas não são roteadas através de agentes Jitterbit. O gateway que processa a API deve ser capaz de acessar a API sendo proxificada:

• Gateway de API na nuvem: Se você usar o gateway de API na nuvem (hospedado pela Jitterbit), a API existente deve estar acessível publicamente, mesmo que protegida. A API que você está tentando proxificar não pode estar atrás de um firewall. Para adicionar os endereços IP do gateway de API na nuvem à lista de permissões e permitir que o gateway acesse a API sendo proxificada, consulte Informações de lista de permissões e navegue até https://services.jitterbit para sua região.

• Gateway de API privado: Se você usar um gateway de API privado (hospedado em uma rede privada), o gateway de API privado deve ser capaz de acessar a API existente.

Embora cada API proxy permita que múltiplos serviços sejam atribuídos a uma URL única, a URL proxy base consome o direito.

Criar uma nova API proxy

Para criar uma nova API proxy, clique em Novo e selecione uma das seguintes opções:

• Criar com IA: Abre o Assistente APIM para criar uma API usando prompts em linguagem natural. Para mais informações, consulte Usando o Assistente de IA.

  Nota

  Para usar o Assistente de IA do APIM, sua licença Harmony deve incluir a opção Assistente de IA do APIM. Entre em contato com seu Gerenciador de Sucesso do Cliente (CSM) para adicionar esta opção à sua licença.

• API proxy: Abre a tela de configuração de API proxy para criar manualmente uma nova API proxy. Esta opção é habilitada apenas se uma URL de API correspondente estiver disponível.

Configurar uma API proxy

Ao configurar uma API proxy manualmente, a tela de configuração inclui múltiplas abas. A tela de configuração inclui três abas obrigatórias e três abas opcionais:

• Aba Perfil (obrigatória)
• Aba Configurações (opcional)
• Aba API existente (obrigatória)
• Aba Serviços (obrigatória)
• Aba Perfis de segurança (opcional)
• Aba Cabeçalhos de solicitação (opcional)

Aba Perfil

Use a aba Perfil para inserir informações básicas que identificam a API.

Configure as seguintes configurações:

• API Name: Insira um nome para a API proxy a ser usada para fins de identificação interna. Os seguintes caracteres especiais são permitidos: ( ) - _.

• Service Root: O nome público da API a ser usado como parte da URL do serviço da API. Por padrão, este campo é preenchido com o Proxy Name convertido para camel case. Este campo não permite espaços ou certos caracteres especiais. Não é recomendado usar caracteres especiais diferentes de um underscore (_). Os seguintes caracteres especiais são permitidos: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

• Description: Insira uma descrição opcional para a API.

• Environment: Use o menu para selecionar o ambiente onde a API residirá. Você pode digitar qualquer parte do nome do ambiente no menu para filtrar a lista de ambientes. Os resultados do menu são filtrados em tempo real a cada digitação.

  Nota

  Após a criação da API, não é possível alterar o ambiente. Para mover uma API entre ambientes, é possível clonar a API ou exportar e importar a API em outro ambiente.

• Version number: Insira uma versão opcional a ser usada como parte da URL do serviço da API. Este campo permite um máximo de 48 caracteres e não permite espaços ou certos caracteres especiais. Não é recomendado usar caracteres especiais diferentes de um ponto (.) ou um hífen (-). As convenções de nomenclatura comuns incluem versões incrementais como v1.0, v1.1, v1.2, ou usar uma data em que a API foi publicada, como 2025-08-28.

Após concluir a aba Profile, clique em Next para prosseguir para a aba Settings, ou clique em Save as draft para salvar seu progresso.

Settings tab

A aba Settings é opcional e contém opções de configuração avançadas para a API.

Configure as seguintes configurações conforme necessário:

• Timeout: Insira o número de segundos antes da API expirar. O padrão é 30 segundos. O valor máximo permitido é 180 segundos.

  Nota

  Esta configuração é independente da configuração de timeout da operação em Studio ou Design Studio. As configurações de timeout da operação não são usadas a menos que a configuração EnableAPITimeout no arquivo de configuração do agente privado esteja habilitada.

• SSL only: Este toggle está habilitado por padrão e requer HTTPS para a API. Quando habilitado, os dados são criptografados por SSL e uma solicitação HTTP retorna um erro. Quando desabilitado, tanto solicitações HTTP quanto HTTPS são suportadas.

  Aviso

  Quando desabilitado, os dados transmitidos através de solicitações e respostas da API não são criptografados e podem ser interceptados e visualizados por outros. Isso pode expor informações sensíveis.

• CORS: Habilite este toggle para suportar CORS (Cross-Origin Resource Sharing). CORS é um mecanismo que permite que aplicações web executadas em um navegador web em um domínio acessem recursos de um servidor em um domínio diferente.

  Aviso

  Habilitar CORS faz com que operações usando o método OPTIONS sejam executadas sem autenticação.

• Verbose logging: Habilite este toggle para adicionar dados brutos de solicitação e resposta — incluindo headers, parâmetros e corpos — ao log de chamadas quando uma solicitação de API é feita. Estes dados aparecem na página API Logs e na página Runtime do Management Console para execuções bem-sucedidas e malsucedidas. O verbose logging não gera entradas de log de operação do Studio para execuções bem-sucedidas. Para registrar execuções de operação bem-sucedidas no Studio, use Enable debug mode until em vez disso.

  Aviso

  O verbose logging pode incluir dados sensíveis, como credenciais de autenticação ou informações de identificação pessoal. Os valores para masked headers são ocultados, mas parâmetros e corpos são registrados na íntegra. Use esta configuração com cuidado.

• Ativar modo de depuração até: Ative este botão para ativar o registro detalhado para solução de problemas e clique no ícone de calendário para selecionar uma data até duas semanas a partir de hoje quando o modo de depuração se desativa automaticamente. Quando ativado, os dados de solicitação e resposta (mantidos por 30 dias) aparecem na página API Logs, na página Runtime do Console de Gerenciamento e nos logs de operação do Studio para execuções bem-sucedidas e malsucedidas. O registro de depuração em nível de atividade também é ativado, capturando dados de entrada e saída de componentes na guia Debug Logging. Esta configuração substitui Verbose logging: quando o modo de depuração está ativado, os dados de solicitação e resposta são incluídos nos logs independentemente de Verbose logging estar ativado.

  Aviso

  Os logs de depuração contêm todos os dados de solicitação e resposta, incluindo informações sensíveis como senhas e informações de identificação pessoal (PII). Além dos valores para cabeçalhos mascarados, esses dados aparecem em texto simples nos logs da nuvem Harmony por 30 dias.

• Mostrar Payloads de Solicitação e Resposta nos Logs: Este botão é visível nas configurações de API proxy, mas não tem efeito. O registro de payload de solicitação e resposta não é suportado para APIs proxy.

Após configurar a guia Settings, clique em Next para prosseguir para a guia Existing API ou clique em Prev para retornar à guia Profile.

Guia Existing API

Use a guia Existing API para especificar a URL base da API que deseja fazer proxy e, opcionalmente, forneça um documento OpenAPI para descoberta automática de serviços.

Configure as seguintes configurações:

• Base API URL: Digite a URL base da API para fazer proxy.

  Nota

  Se a API fornece um único serviço, você pode inserir a URL completa da API, incluindo o caminho do serviço. Caminhos de serviço adicionais são definidos na guia Services.

• Provide OpenAPI document: Se você fornecer um documento OpenAPI, o API Manager o usa para descobrir automaticamente os serviços da API. Selecione No para pular ou Yes para expandir uma área adicional para fornecer o documento OpenAPI:

  

  • Load URL: Abre um diálogo para carregar um documento OpenAPI em formato YAML ou JSON de uma URL:

    

  • Upload file: Abre um diálogo para fazer upload de um documento OpenAPI em formato YAML ou JSON após usar Browse para selecionar o arquivo:

    

  • Clear: Limpa um documento OpenAPI que já foi fornecido e altera a seleção Provide OpenAPI document para No. Um diálogo de confirmação Clear editor contents aparece, pedindo que você confirme antes de o documento ser removido. Limpar o documento também remove todos os serviços que foram descobertos automaticamente a partir dele (consulte OpenAPI document auto-discovery), mas não afeta os serviços adicionados manualmente ou outras configurações de API. Limpar o documento é tratado como uma alteração não salva até que você salve a configuração da API.

  • Document editor: Permite visualizar e editar um documento OpenAPI fornecido. Você também pode fornecer um documento OpenAPI inserindo-o aqui diretamente. Para visualizar e editar o documento OpenAPI em uma área maior, clique no ícone de expansão. Após abrir essa área, clique no ícone de retorno para voltar a esta tela.

Após configurar a guia Existing API, clique em Next para prosseguir para a guia Services ou clique em Prev para retornar à guia Settings.

Aba Serviços

Use a aba Serviços para definir os serviços e métodos HTTP que a API proxy irá expor. A forma como você define os serviços depende de ter fornecido um documento OpenAPI na aba API Existente.

Definição manual de serviço

Se você não forneceu um documento OpenAPI, é necessário definir serviços e métodos manualmente:

Clique em Novo Serviço para adicionar um serviço. Configure as seguintes opções:

• Nome do Serviço: Digite um nome para identificar o serviço.

• Caminho: Digite um caminho para o serviço. Se a API não tiver um caminho de serviço, digite uma barra (/).

  Nota

  Não é possível usar caracteres como chaves ({ }) em um caminho de serviço quando você define serviços manualmente. Para usar caracteres não permitidos em um caminho de serviço, forneça um documento OpenAPI que defina o caminho na aba API Existente.

• Métodos: Selecione cada método a ser criado para o serviço. Os métodos disponíveis incluem GET, PUT, POST e DELETE. Para usar um método não listado, digite o nome do método na caixa de texto Digite um novo método e pressione Enter.

• Ações: Passe o mouse sobre uma linha de serviço para revelar ações adicionais.

  • Copiar URL do serviço de API: Clique para copiar a URL do serviço de API.
  • Duplicar: Clique para duplicar o serviço.
  • Excluir: Clique para excluir o serviço.

É necessário adicionar pelo menos um serviço para prosseguir para a próxima aba.

Descoberta automática de documento OpenAPI

Se você forneceu um documento OpenAPI na aba API Existente, o API Manager descobre e lista automaticamente os serviços em uma tabela:

• Atribuir: Use a alternância para adicionar os serviços à API proxy.
• Nome do Serviço: O nome usado para identificar o serviço.
• Métodos: O método HTTP que se aplica ao serviço.
• Caminho: O caminho do serviço.

• Ações: Passe o mouse sobre uma linha de serviço para revelar ações adicionais.

  • Copiar URL do serviço de API: Clique para copiar a URL do serviço de API.
  • Ir para Serviço de API: Clique para configurar a API em uma interface de assistente.

Após configurar a aba Serviços, clique em Próximo para prosseguir para a aba Perfis de segurança, ou clique em Anterior para retornar à aba API Existente.

Aba Perfis de segurança

A aba Perfis de segurança é opcional e permite restringir o acesso ao consumo da API.

Configure as seguintes opções:

• Atribuir: Use a alternância para atribuir ou desatribuir perfis de segurança para a API.

• Nome do Perfil: O nome do perfil de segurança conforme configurado em Perfis de Segurança.

• Tipo: O tipo de autenticação para o perfil de segurança, como Básica, OAuth 2.0 ou Chave de API.

• Nome de Usuário: Para autenticação básica, exibe o nome de usuário. Para outros tipos de autenticação, exibe o mesmo valor que a coluna Tipo.

• Ações: Passe o mouse sobre uma linha de perfil de segurança para revelar ações adicionais.

  • Ir para perfil de segurança: Clique para abrir a configuração do perfil de segurança.

Dependendo das políticas da organização Harmony, pode ser necessário atribuir um perfil de segurança para salvar a API.

Clique em Novo perfil de segurança para criar um novo perfil de segurança. Para obter instruções, consulte Configurar perfis de segurança.

Após configurar a guia Perfis de segurança, clique em Próximo para prosseguir para a guia Cabeçalhos de solicitação, ou clique em Anterior para retornar à guia Serviços.

Guia Cabeçalhos de solicitação

A guia Cabeçalhos de solicitação é opcional e permite adicionar novos cabeçalhos de solicitação ou substituir cabeçalhos de solicitação existentes.

Clique em Novo cabeçalho para adicionar um cabeçalho de solicitação. Configure as seguintes configurações:

• Chave: Digite uma chave para o cabeçalho de solicitação.

• Valor: Digite um valor para o cabeçalho de solicitação. O valor deve conter apenas letras, números, espaços e pontuação, sem espaços à esquerda ou à direita, e não pode exceder 8192 caracteres. Isso acomoda valores como JSON Web Tokens (JWTs), que exigem pontos (.) como parte de seu formato.

• Substituir Entrada: Ative este botão para substituir um cabeçalho de solicitação existente que use a mesma Chave. O padrão é desativado.

• Ações: Passe o mouse sobre uma linha de cabeçalho para revelar ações adicionais.

  • Excluir: Clique para excluir o cabeçalho de solicitação.

Após configurar a guia Cabeçalhos de solicitação, clique em Publicar para publicar a API, ou clique em Salvar como rascunho para salvar seu progresso.

Opções de salvar e publicar

Após configurar todas as guias obrigatórias, você pode salvar ou publicar a API:

• Salvar como rascunho: Salva a API com status Rascunho ou Publicado com Rascunho. APIs em rascunho não contam contra o limite de assinatura de URL de Proxy. Uma API cujo status era Publicado no momento em que você usa Salvar como rascunho é salva como Publicado com Rascunho. Uma API publicada conta contra o limite de assinatura de URL de Proxy, mesmo que seu rascunho não seja acessível.

• Publicar: Salva a API com status Publicado. A API fica ativa e acessível em até cinco minutos. Uma API publicada conta contra o limite de assinatura de URL de Proxy. Uma caixa de diálogo indica que a API está ativa:

  

  A caixa de diálogo fornece estas opções:

  • Copiar URL: Copia a URL de serviço da API para sua área de transferência.
  • Fechar: Fecha a caixa de diálogo.

Editar a API

Após salvar a API, você pode editá-la a partir destes locais:

• Usando a visualização de cartão na página APIs, clique no cartão.
• Usando a visualização de lista na página APIs, clique em Editar na coluna Ações.

Ao editar uma API publicada a partir da visualização de lista, uma guia Documentação também fica disponível. Use esta guia para visualizar, editar e publicar documentação OpenAPI para APIs individuais. Para obter detalhes, consulte guia Documentação na página APIs.

Solução de problemas

Para solução de problemas relacionada, consulte o seguinte no guia de solução de problemas do API Manager:

• API Proxy: Parâmetros de caminho de serviço exigem um documento OpenAPI

• API proxy em nuvem: A API de destino deve ser acessível publicamente

• Proxy API: Hífens no cabeçalho de solicitação substituídos por sublinhados

• A configuração Mostrar Payloads de Solicitação e Resposta não tem efeito para APIs de proxy