Configuração do serviço OData no Jitterbit API Manager

Introdução

Esta página descreve como criar e configurar um serviço OData a partir da página APIs do Jitterbit API Manager. Um serviço 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 Configuração de API personalizada e Configuração de API proxy.

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

Os serviços OData (publicados e rascunho) são exibidos nestes locais:

• A página APIs do API Manager.
• A guia Recursos do painel de projetos para o projeto do Design Studio associado ao serviço OData.

Pré-requisitos

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

Para obter informações sobre como criar e implantar uma operação de entidade de 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 de API

Criar um novo serviço OData

Para criar um novo serviço OData, clique em Novo e selecione uma das seguintes opções:

• Criar com IA: Abre o Assistente de IA do APIM para criar uma API usando prompts em linguagem natural. Para obter 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 essa opção à sua licença.

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

Configurar um serviço OData

Ao configurar um serviço 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 Perfil (obrigatória)
• Aba Configurações (opcional)
• Aba Serviços (obrigatória)
• Aba Perfis de segurança (opcional)
• Aba Funções de usuário (opcional)

Aba Perfil

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

Configure as seguintes opçõ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. Não é recomendado usar caracteres especiais diferentes de um sublinhado (_). Os seguintes caracteres especiais são permitidos: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

• Descrição: Digite 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 digitação.

  Nota

  Após a criação da API, não é possível alterar 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: Digite uma versão opcional para usar 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.

Aba Settings

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

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

• Timeout: Digite 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 no Studio ou Design Studio. As configurações de timeout da operação não são usadas a menos que um agente privado seja usado e 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 por meio 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 dos headers mascarados são ocultados, mas parâmetros e corpos são registrados na íntegra. Use esta configuração com cuidado.

• Enable debug mode until: Habilite este toggle 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 debug se desativa automaticamente. Quando habilitado, os dados de solicitação e resposta (mantidos por 30 dias) aparecem na página API Logs, na página Runtime do Management Console e nos logs de operação do Studio para execuções bem-sucedidas e malsucedidas. O registro de debug em nível de atividade também é habilitado, capturando dados de entrada e saída de componentes na aba Debug Logging. Esta configuração substitui Verbose logging e Show Request & Response Payloads in Logs: quando o modo de debug está habilitado, os dados de solicitação e resposta são incluídos nos logs independentemente de essas configurações estarem habilitadas.

• Mostrar Payloads de Solicitação e Resposta nos Logs: Ative esta opção para capturar e exibir payloads de solicitação e resposta na página API Logs e na página Runtime do Console de Gerenciamento quando uma solicitação de API é 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 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. Esta opção se aplica apenas a APIs personalizadas e serviços OData.

  Aviso

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

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

Guia Services

A guia Services é onde você configura os serviços de API que definem como a API responde às solicitações. Para serviços 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 opções para cada serviço:

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

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

• Operation: Selecione entre as operações de entidade de API do Design Studio implantadas 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 ativar logs adicionais, consulte Dados de solicitação e resposta de 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 GET, PUT, POST, DELETE, PATCH e MERGE separados para a operação selecionada. Para usar um método não listado, digite o nome do método na caixa de texto Type a new method 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 a URL do serviço da API.
  • Go to API Service: Clique para ver uma visão geral de página única da configuração do serviço OData.
  • Duplicate: Clique para duplicar o serviço de API.
  • Delete: Clique para excluir o serviço de API.

Você pode configurar vários serviços para um único serviço OData. Você deve adicionar pelo menos uma entidade para prosseguir para a próxima guia.

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

Guia Security profiles

A guia Security profiles é opcional e permite restringir o acesso ao consumo da API.

Configure as seguintes definições:

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

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

• Tipo: O tipo de autenticação do 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 da 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 Funções de usuário, ou clique em Anterior para retornar à guia Serviços.

Guia Funções de usuário

A guia Funções de usuário é opcional e determina quais funções da organização têm acesso à API no API Manager.

Configure as seguintes definições:

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

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

• Status: Indica se a função está atribuída a esta API. Alterne o status para atribuir ou desatribuir funções.

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

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

As funções selecionadas aqui determinam o acesso a esta API específica a partir destas páginas:

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

O acesso à página 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.

Qualquer função de usuário definida com permissão de Admin sempre tem acesso total a todas as APIs e, portanto, não pode ser removida da seleção.

Clique em Nova função de usuário para criar uma nova função de usuário. Para obter instruções, consulte Funções em Gerenciamento de Usuários.

Após configurar a guia Funções 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 guias obrigatórias, é possível 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 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 contra o limite de assinatura de URL de API, mesmo que seu rascunho não esteja acessível.

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

  

  O diálogo oferece estas opções:

  • Copiar URL: Copia a URL do serviço da API para a área de transferência.
  • Gerar Documento OpenAPI: Abre a página do Portal Manager. Para gerar documentação de 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

É possível filtrar os dados retornados adicionando parâmetros de consulta OData à URL do serviço de um serviço OData. 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 nestes 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 na visualização de lista, uma aba Documentação também fica disponível. Use esta aba para visualizar, editar e publicar documentação OpenAPI de APIs individuais. Para detalhes, consulte aba 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:

• OData $count ou $inlinecount retorna um erro quando nenhum registro corresponde