Configuração da API OData no Jitterbit API Manager

Introdução

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

Alternativamente, crie APIs OData usando o Assistente de IA do APIM.

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

• A página de APIs do API Manager.
• A aba Recursos do painel do projeto para o projeto do Design Studio associado à API OData.

Pré-requisitos

Uma API OData expõe uma operação de entidade API do Jitterbit iPaaS para consumo. Você deve primeiro criar e implantar essa operação antes de poder configurar a API OData. A operação que uma API OData aciona deve ser uma operação de entidade API do Design Studio.

Para informações sobre como criar e implantar uma operação de entidade API no Design Studio, consulte estes recursos:

• Guia de início rápido do Design Studio
• Criar uma entidade Jitterbit
• Criar uma operação de entidade API

Criar uma nova API OData

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

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

  Nota

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

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

Configurar uma API OData

Quando você configura uma API OData manualmente, a tela de configuração inclui várias abas. A tela de configuração inclui duas abas obrigatórias e três abas opcionais:

• 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 Funções de Usuário (opcional)

Aba de Perfil

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

Configure as seguintes configuraçõ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 Next para prosseguir para a aba Settings, ou clique em Salvar como rascunho para salvar seu progresso.

Aba Configurações

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:

• 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 um agente privado seja usado e 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 interruptor para suportar CORS (Compartilhamento de Recursos entre Diferentes Origens). CORS é um mecanismo que permite que aplicativos da web executando em um navegador da web 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 interruptor para adicionar dados brutos de solicitação e resposta — incluindo cabeçalhos, parâmetros e corpos — ao registro de chamadas quando uma solicitação da API é feita. Esses dados aparecem na página Registros da API e na página Tempo de Execução do Console de Gerenciamento para execuções bem-sucedidas e malsucedidas. O registro detalhado não gera entradas de log de operação do Studio para execuções bem-sucedidas. Para registrar execuções de operações bem-sucedidas no Studio, use Ativar modo de depuração até em vez disso.

  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 interruptor 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 ativado, os dados de solicitação e resposta (mantidos por 30 dias) aparecem na página Registros da API, na página Tempo de Execução 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 aba de Registro de Depuração. Esta configuração substitui Registro detalhado e Mostrar Cargas Úteis de Solicitação e Resposta nos Logs: quando o modo de depuração está ativado, os dados de solicitação e resposta são incluídos nos logs, independentemente de essas configurações estarem ativadas.

  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.

• Mostrar Payloads de Solicitação e Resposta nos Logs: Ative este botão para capturar e exibir os payloads de solicitação e resposta na página de Logs da API e na página Runtime do Console de Gerenciamento quando uma solicitação de API for feita. Os payloads aparecem em uma visualização formatada com painéis separados para os corpos de solicitação e resposta, tanto para execuções bem-sucedidas quanto para malsucedidas. Esta configuração 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 Ativar modo de depuração até em vez disso. Este botão se aplica apenas a APIs personalizadas e OData.

  Aviso

  Os payloads de solicitação e resposta podem incluir dados sensíveis, como credenciais de autenticação ou informações pessoalmente identificáveis. Use esta configuração com cuidado.

Após configurar a aba Settings, clique em Next para prosseguir para a aba Serviços, ou clique em Anterior para retornar à aba Perfil.

Aba Serviços

A aba Serviços é onde você configura os serviços da API que definem como a API responde às solicitações. Para APIs OData, você atribui operações de entidade Jitterbit que expõem dados através do protocolo OData.

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

• Entidade: Selecione entre os projetos implantados que contêm uma operação de entidade API no ambiente onde você está configurando a API. O nome da entidade corresponde ao nome do projeto no Design Studio.

• Projeto: Exibe o nome do projeto do Design Studio que contém a entidade selecionada.

• Operation: Selecione entre as operações de entidade API do Design Studio implantado na entidade selecionada. Apenas uma operação usando cada método pode ser atribuída.

  Para informações sobre o que aparece nos logs de operação para operações acionadas por API e como habilitar logs adicionais, veja dados de solicitação e resposta da API em Logs de operação.

• Method: Selecione o método HTTP a ser criado para a operação selecionada. Os métodos disponíveis incluem GET, PUT, POST, DELETE, PATCH, MERGE ou ALL. Selecionar ALL cria métodos separados GET, PUT, POST, DELETE, PATCH e MERGE para a operação selecionada. 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.

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

  • Copy API service URL: Clique para copiar o URL do serviço da API.
  • Go to API Service: Clique para ver uma visão geral em uma única página da configuração da API OData.
  • Duplicar: Clique para duplicar o serviço da API.
  • Excluir: Clique para excluir o serviço da API.

Você pode configurar múltiplos serviços para uma única API OData. É necessário adicionar pelo menos uma entidade para prosseguir para a próxima aba.

Após configurar a aba Serviços, clique em Next 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 alternar 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 de 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.

• Actions: 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 Next para prosseguir para a aba Funções de Usuário, ou clique em Anterior para retornar à aba Serviços.

Aba Funções de Usuário

A aba Funções de Usuário é opcional e determina quais funções da organização têm acesso à API dentro do Gerenciador de API.

Configure as seguintes configurações:

• Função de Usuário: O nome da função da organização conforme definido na aba Funções da página de Gerenciamento de Usuários.

• Permissões: As permissões atribuídas a essa função, como Ler ou Admin.

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

• Actions: 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
• Portal Manager, incluindo a geração de documentação da API
• API Portal
• API Logs
• Analytics

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.

Depois de 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

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 seu limite de assinatura de 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 seu limite de assinatura de URL da API, mesmo que seu rascunho não esteja acessível.

• Publicar: Salva a API no status Publicada. A API está ativa e acessível em até cinco minutos. Uma API publicada conta contra o seu limite de assinatura de URL da API. Um diálogo indica que a API está ativa:

  

  O diálogo fornece estas opções:

  • Copiar URL: Copia a URL do serviço da API para a sua área de transferência.
  • Gerar Documento OpenAPI: Abre a página do Portal Manager. Para gerar documentação para APIs individuais, use a aba Documentação ao editar a API na página APIs.
  • Fechar: Fecha o diálogo.

Parâmetros de consulta OData

Você pode filtrar os dados retornados anexando parâmetros de consulta OData a uma URL de serviço OData API. Os parâmetros de consulta específicos suportados dependem do banco de dados subjacente.

Os parâmetros de consulta OData comuns incluem:

https://jbexample.jitterbit.net/Sandbox/customers?$top=10&$orderby=name

Editar a API

Após salvar a API, é possível editá-la a partir destes locais:

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

Ao editar uma API publicada na visualização em lista, uma aba Documentação também está disponível. Use esta aba para visualizar, editar e publicar a documentação OpenAPI para APIs individuais. Para mais detalhes, veja a aba Documentação na página de APIs.