Configuração de API personalizada no Jitterbit API Manager

Introdução

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

Alternativamente, você pode criar APIs personalizadas usando o Assistente de IA ou no Studio usando a opção Publicar como uma API no menu de ações de uma operação.

APIs personalizadas (publicadas e em rascunho) são exibidas nestes locais:

• A página de APIs do API Manager.
• A aba Recursos do painel do projeto associado à API personalizada.

Pré-requisitos

Uma API personalizada expõe uma operação do Harmony para consumo. Você deve primeiro criar e implantar essa operação no Harmony antes de poder configurar a API personalizada. A operação que uma API personalizada aciona pode ser uma operação do Studio ou do Design Studio.

Para instruções sobre como criar e implantar uma operação, consulte estes recursos:

• Studio
  • Criação e configuração de operação
  • Implantação e execução de operação
• Design Studio
  • Criando uma operação

Criar uma nova API personalizada

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 personalizada, clique em Novo > API Personalizada.

Configurar uma API personalizada

A tela de configuração inclui várias abas, com duas 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 Serviços (obrigatória)
• Aba de Perfis de Segurança (opcional)
• Aba de Papéis de Usuário (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 a ser usado 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 API 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 usadas, a menos que um agente privado seja utilizado e a configuração EnableAPITimeout no arquivo de configuração do agente privado esteja habilitada.

• Apenas SSL: Este alternador 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 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 alternador para suportar CORS (Compartilhamento de Recursos de Origem Cruzada). CORS é um mecanismo que permite que aplicações web executadas em um navegador 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.

• Registro detalhado: Habilite este alternador para registrar cabeçalhos de solicitação e cargas úteis quando uma solicitação da 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.

• Habilitar modo de depuração até: Habilite este alternador para ativar o registro detalhado para solução de problemas, em seguida, clique no ícone do calendário para selecionar uma data de até duas semanas a partir de hoje, quando o modo de depuração será desativado automaticamente. Quando você habilita 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 da 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 Serviços, ou clique em Anterior para retornar à aba Perfil.

Aba de Serviços

A aba Serviços é onde você configura os serviços da API que definem como a API responde às solicitações. É possível configurar múltiplos serviços para uma única API personalizada. Cada serviço deve ter uma combinação única de método HTTP e caminho.

Clique em Novo Serviço para adicionar um novo serviço de API. Configure as seguintes definições para cada serviço:

• Nome do Serviço: Insira um nome descritivo para este serviço de API.

• Método: Selecione o método HTTP para este serviço no menu suspenso. Os métodos disponíveis incluem GET, POST, PUT, DELETE e ALL. 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.

• Caminho: Insira o caminho da URL que aciona este serviço. O caminho é anexado à raiz do serviço na URL do serviço da API.

• Projeto: Selecione o projeto Harmony que contém a operação que este serviço aciona.

  • Ir para o projeto: Clique para abrir um projeto do Studio em uma nova aba do navegador. Esta opção está desativada para projetos do Design Studio.

• Operação a Acionar: Selecione a operação específica do projeto escolhido que este serviço executa quando chamado.

  Importante

  Por padrão, operações bem-sucedidas configuradas para uma API personalizada não são incluídas nos logs de operação a menos que uma dessas configurações esteja habilitada:

  • Agentes em nuvem: Para operações de API em um agente em nuvem, o registro de depuração de operação deve estar habilitado na operação.
  • Agentes privados: Para operações de API em um agente privado, ou o registro de depuração de operação deve estar habilitado na operação ou você deve definir EnableLogging=true na seção [APIOperation] do arquivo de configuração do agente privado.

Operações malsucedidas estão incluídas nos logs de operação independentemente de as configurações acima estarem habilitadas ou não.

• Tipo de Resposta: Selecione como a API retorna a resposta da operação. As opções disponíveis incluem Destino Final, Variável do Sistema e Sem Resposta.

  • Destino Final: A resposta da API é o destino final da cadeia de operações. Ao selecionar este tipo de resposta, a operação selecionada deve ter, como destino final da cadeia de operações, uma atividade de Resposta da API ou uma atividade de Gravação de Variável do Studio, ou um destino de Resposta da API do Design Studio ou um destino de Variável Global. Se a operação usar qualquer outro destino final, a resposta da API estará vazia.

  • Variável do Sistema: A resposta da API é definida em uma variável Jitterbit na cadeia de operações. Ao selecionar este tipo de resposta, a operação selecionada deve ter, como parte da cadeia de operações, um script que define a variável Jitterbit jitterbit.api.response igual à resposta que você deseja que a API retorne. Se o script não definir essa variável, a resposta da API estará vazia.

  • Sem Resposta: A resposta da API está em branco. Se o pedido para executar a operação selecionada for aceito, a API retornará uma resposta vazia imediata com o código HTTP 202.

• 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 ver uma visão geral em uma única página da configuração da API personalizada.
  • Duplicar: Clique para duplicar o serviço da API.
  • Excluir: Clique para excluir o serviço da API.

Após configurar as configurações básicas do serviço, você pode configurar parâmetros adicionais usando as abas abaixo da configuração do serviço:

Aba de parâmetros de caminho

Quando os parâmetros de solicitação estão incluídos no Caminho, esta aba exibe os parâmetros definidos no caminho:

• Parâmetro: Exibe cada parâmetro de solicitação definido no Caminho.

• Descrição: Opcionalmente, insira uma descrição para o parâmetro de solicitação.

Aba de parâmetros de consulta

Esta aba permite que você adicione parâmetros de consulta ao serviço da API:

• Adicionar Parâmetro: Clique para adicionar um parâmetro de consulta ao serviço da API. Os seguintes campos ficam disponíveis:

  • Parâmetro: Insira o nome do parâmetro de consulta.

  • Descrição: Opcionalmente, insira a descrição do parâmetro de consulta.

  • Excluir: Clique no ícone de excluir ao lado de um parâmetro de consulta para excluir esse parâmetro.

Aba de cabeçalhos

Esta aba permite que você adicione cabeçalhos de solicitação ao serviço da API:

• Adicionar Cabeçalho: Clique para adicionar um cabeçalho de solicitação ao serviço da API. Os seguintes campos ficam disponíveis:

  • Parâmetro: Insira o nome do cabeçalho de solicitação.

  • Descrição: Opcionalmente, insira uma descrição para o cabeçalho de solicitação.

  • Obrigatório: Selecione a caixa de seleção para tornar este cabeçalho obrigatório para as solicitações da API.

  • Excluir: Clique no ícone de excluir ao lado de um cabeçalho de solicitação para excluir esse cabeçalho.

Você pode configurar vários serviços para uma única API personalizada. Cada serviço deve ter uma combinação única de método HTTP e caminho.

Use a coluna Ações para editar ou excluir serviços existentes.

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 Configurações.

Aba 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.

Após configurar a aba Perfis de Segurança, clique em Próximo para prosseguir para a aba Funções de Usuário, ou clique em Anterior para retornar à aba Serviços.

Aba de papéis de usuário

A aba Papéis de usuário é opcional e determina quais papéis da organização têm acesso à API dentro do Gerenciador de API.

Configure as seguintes configurações:

• Papel de Usuário: O nome do papel da organização conforme definido na aba Papéis da página de Gerenciamento de Usuários.

• Permissões: As permissões atribuídas a este papel, como Ler ou Admin.

• Status: Indica se o papel está atribuído a esta API. Altere o status para atribuir ou desatribuir papéis.

• Ações: Passe o mouse sobre uma linha de papel de usuário para revelar ações adicionais.

  • Ir para papel de usuário: Clique para abrir a configuração do papel de usuário.

Os papéis que você selecionar aqui determinam o acesso a esta API específica a partir destas páginas:

• APIs
• Gerenciador de Portal, incluindo a geração de documentação da API
• Portal da API
• Logs da API
• Análises

O acesso à página de Perfis de Segurança e o acesso para consumir a API não são afetados por esta seleção. O acesso para consumir uma API é controlado por perfis de segurança.

Quaisquer papéis de usuário definidos com a permissão Admin sempre têm acesso total a todas as APIs e, portanto, não podem ser removidos da seleção.

Clique em Novo papel de usuário para criar um novo papel de usuário. Para instruções, veja Papéis em Gerenciamento de Usuários.

Após configurar a aba Papéis de usuário, 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 abas necessá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 da API. 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 da API, 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 da API. 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.
  • Gerar Documento OpenAPI: Abre a página do Portal Manager, onde você pode gerar documentação da API para a página do Portal da API.
  • 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.