Configuração da API Proxy no Jitterbit API Manager

Introdução

Esta página descreve como criar e configurar uma API proxy a partir da página de 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 API OData, consulte Configuração da API personalizada e Configuração da API OData.

Pré-requisitos

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

• Gateway de API em nuvem: Se você usar o gateway de API em nuvem (hospedado pelo Jitterbit), a API existente deve ser acessível publicamente, mesmo que esteja segura. A API que você está tentando proxy não pode estar atrás de um firewall. Para permitir que os endereços IP do gateway de API em nuvem acessem a API que está sendo proxy, consulte as informações de lista de permissão 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 vários serviços sejam atribuídos a uma URL única, a URL proxy base consome a cota.

Criar uma nova API proxy

Quando você acessa a página APIs do Gerenciador de API, se não houver APIs personalizadas, APIs OData ou APIs proxy na organização selecionada, esta tela estará em branco.

Para criar uma nova API proxy, clique em Novo > API Proxy.

Configurar uma API proxy

A tela de configuração inclui várias abas, com três abas obrigatórias e três abas opcionais. Cada aba é abordada nas seções a seguir:

• Aba de Perfil (obrigatória)
• Aba de Configurações (opcional)
• Aba de API Existente (obrigatória)
• Aba de Serviços (obrigatória)
• Aba de Perfis de Segurança (opcional)
• Aba de Cabeçalhos de Solicitação (opcional)

Aba de Perfil

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

Configure as seguintes definições:

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

• Raiz do Serviço: 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 Nome da Proxy convertido para camel case. Este campo não permite espaços ou certos caracteres especiais. O uso de caracteres especiais além de um sublinhado (_) não é recomendado. Os seguintes caracteres especiais são permitidos: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

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

• Ambiente: 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 tecla pressionada.

  Nota

  Após a criação da API, você não pode mudar o ambiente. Para mover uma API entre ambientes, você pode clonar a API ou exportar e importar a API em outro ambiente.

• Número da versão: Insira uma versão opcional para usar como parte da URL de serviço da API. Este campo permite um máximo de 48 caracteres e não permite espaços ou certos caracteres especiais. O uso de caracteres especiais além de um ponto (.) ou um hífen (-) não é recomendado. Convenções comuns de nomenclatura 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 completar a aba Perfil, clique em Próximo para prosseguir para a aba Configurações, ou clique em Salvar como rascunho para salvar seu progresso.

Aba Configurações

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

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

• Tempo limite: Insira o número de segundos antes que a API atinja o tempo limite. O padrão é 30 segundos. O valor máximo permitido é 180 segundos.

  Nota

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

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

  Aviso

  Quando desativado, 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 potencialmente expor informações sensíveis.

• CORS: Ative este botão para suportar CORS (Compartilhamento de Recursos entre Diferentes Origens). CORS é um mecanismo que permite que aplicativos web executando em um navegador em um domínio acessem recursos de um servidor em um domínio diferente.

  Aviso

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

• Registro detalhado: Ative este botão para registrar cabeçalhos de solicitação e cargas úteis quando uma solicitação de API for feita.

  Aviso

  O registro detalhado pode incluir dados sensíveis, como credenciais de autenticação ou informações pessoalmente identificáveis. 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, em seguida, clique no ícone do calendário para selecionar uma data até duas semanas a partir de hoje, quando o modo de depuração será desativado automaticamente. Quando você ativa o modo de depuração para operações acionadas por esta API, os logs da API incluem dados de solicitação e resposta (mantidos por 30 dias) que você pode acessar através da página Runtime do Console de Gerenciamento. Por padrão, o Gerenciador de API registra apenas operações de API com erros.

  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 pessoalmente identificáveis (PII). Esses dados aparecem em texto claro nos logs da nuvem Harmony por 30 dias.

Após configurar a aba Configurações, clique em Próximo para prosseguir para a aba API Existente, ou clique em Anterior para retornar à aba Perfil.

Aba API Existente

Use a aba API Existente para especificar a URL base da API que você deseja proxy e, opcionalmente, forneça um documento OpenAPI para descoberta automática de serviços.

Configure as seguintes configurações:

• URL base da API: Insira a URL base da API a ser proxy.

  Nota

  Se a API fornecer 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 aba Serviços.

• Fornecer documento OpenAPI: Se você fornecer um documento OpenAPI, o Gerenciador de API o usará para descobrir automaticamente os serviços da API. Selecione Não para pular ou Sim para expandir uma área adicional para fornecer o documento OpenAPI:

  

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

    

  • Enviar arquivo: Abre um diálogo para enviar um documento OpenAPI em formato YAML ou JSON após você usar Procurar para selecionar o arquivo:

    

  • Limpar: Limpa um documento OpenAPI que já foi fornecido e altera a seleção Fornecer Documento OpenAPI para Não.

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

Após configurar a aba API Existente, clique em Próximo para prosseguir para a aba Serviços, ou clique em Anterior para retornar à aba Configurações.

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 você ter fornecido um documento OpenAPI na aba API Existente.

Definição manual de serviços

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

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

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

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

  Nota

  Você não pode usar caracteres como chaves ({ }) em um caminho de serviço ao definir 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, insira 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 da API: Clique para copiar o URL do serviço da API.
  • Duplicar: Clique para duplicar o serviço.
  • Excluir: Clique para excluir o serviço.

Você deve 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 Gerenciador de API descobre e lista automaticamente os serviços em uma tabela:

• Atribuir: Use o botão 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 da API: Clique para copiar o URL do serviço da API.
  • Ir para o Serviço da 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 de Perfis de Segurança, ou clique em Anterior para retornar à aba de API Existente.

Aba de Perfis de Segurança

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

Configure as seguintes configurações:

• Atribuir: Use o botão 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ásico, OAuth 2.0 ou Chave da API.

• Nome de Usuário: Para autenticação básica, isso exibe o nome de usuário. Para outros tipos de autenticação, isso 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 instruções, veja Configurar perfis de segurança.

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

Aba Cabeçalhos de solicitação

A aba Cabeçalhos de solicitação é opcional e permite que você adicione novos cabeçalhos de solicitação ou substitua cabeçalhos de solicitação existentes.

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

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

• Valor: Insira um valor para o cabeçalho de solicitação.

• Substituir Entrada: Ative este botão para substituir um cabeçalho de solicitação existente que usa 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.

Depois de configurar a aba 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

Depois de configurar todas as abas obrigatórias, você pode salvar ou publicar a API:

• Salvar como rascunho: Salva a API no status Rascunho ou Publicado com Rascunho. APIs em rascunho não contam para o limite de assinatura do seu 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 para o limite de assinatura do seu URL de Proxy, mesmo que seu rascunho não esteja acessível.

• Publicar: Salva a API no status Publicado. A API está ao vivo e acessível em cinco minutos. Uma API publicada conta para o limite de assinatura do seu URL de Proxy. Um diálogo indica que a API está ao vivo:

  

  O diálogo fornece estas opções:

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

Editar a API

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

• Usando visualização em bloco na página de APIs, clique em Ver/Editar.
• Usando visualização em lista na página de APIs, clique em Editar na coluna Ações.