Ir para o conteúdo

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 por meio do API Manager. Para os outros dois tipos, API personalizada e API de proxy, consulte Configuração de API personalizada e Configuração de API de proxy.

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

Nota

Após a publicação, cada serviço OData conta como uma URL de API em relação à sua cota de assinatura do Harmony.

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

  • A página APIs do API Manager.
  • A aba 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 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 API do Design Studio.

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

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 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 do 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 fica habilitada apenas se uma URL de API correspondente estiver disponível.

no APIs new API

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

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

profile tab

Configure as seguintes opções:

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

  • Raiz do Serviço: O nome público da API para usar 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 além do sublinhado (_). 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 com cada teclada.

    Nota

    Após a criação da API, não é possível alterar o ambiente. para mover uma API entre ambientes, clone a API ou exporte e importe 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. 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 a data em que a API foi publicada, como 2025-08-28.

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

guia Settings

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

guia settings

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

  • Timeout: insira o número de segundos antes de a API atingir 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 da operação no Studio ou Design Studio. as configurações de tempo limite 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 ativada.

  • SSL only: esta opção está ativada por padrão e requer HTTPS para a API. quando ativada, os dados são criptografados por SSL e uma solicitação HTTP retorna um erro. quando desativada, há suporte para solicitações HTTP e HTTPS.

    Aviso

    quando desativada, os dados transmitidos em solicitações e respostas de API não são criptografados e podem ser interceptados e visualizados por outras pessoas. isto pode expor informações confidenciais.

  • CORS: ative esta opção para oferecer suporte a CORS (Cross-Origin Resource Sharing). CORS é um mecanismo que permite que aplicativos web executados 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 que usam o método OPTIONS sejam executadas sem autenticação.

  • Verbose logging: ative esta opção para adicionar dados brutos de solicitação e resposta — incluindo cabeçalhos, 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. 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

    verbose logging pode incluir dados confidenciais, como credenciais de autenticação ou informações de identificação pessoal. os valores dos cabeçalhos mascarados estão ocultos, mas parâmetros e corpos são registrados na íntegra. use esta configuração com cuidado.

  • Enable debug mode until: ative esta opção para ativar o registro detalhado para solução de problemas e clique no ícone do calendário para selecionar uma data até duas semanas a partir de hoje quando o modo de depuração desativará automaticamente. quando ativada, 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 depuração no nível de atividade também é ativado, capturando dados de entrada e saída do componente na guia Debug Logging. esta configuração substitui Verbose logging e Show Request & Response Payloads in 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 registros de debug contêm todos os dados de requisição e resposta, incluindo informações sensíveis como senhas e dados de identificação pessoal (PII). Com exceção dos valores para cabeçalhos mascarados, esses dados aparecem em texto simples nos registros da nuvem Harmony por 30 dias.

  • Exibir Payloads de Requisição e Resposta nos Registros: Ative esta opção para capturar e exibir payloads de requisição e resposta na página API Logs e na página Runtime do Console de Gerenciamento quando uma requisição de API é feita. Os payloads aparecem em uma visualização formatada com painéis separados para os corpos de requisição e resposta, tanto para execuções bem-sucedidas quanto malsucedidas. Esta configuração não gera entradas de registro 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 debug até em vez disso. Esta opção se aplica apenas a APIs personalizadas e serviços OData.

    Aviso

    Payloads de requisição e resposta podem incluir dados sensíveis como credenciais de autenticação ou dados de identificação pessoal. Use esta configuração com cuidado.

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

Aba Services

A aba Services é onde você configura os serviços de API que definem como a API responde às requisições. Para serviços OData, você atribui operações de entidade Jitterbit que expõem dados por meio do protocolo OData.

aba services

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. É possível atribuir apenas uma operação usando cada método.

    Para obter informações sobre o que aparece nos registros de operação para operações acionadas por API e como ativar registros adicionais, consulte Dados de requisição e resposta de API em Registros 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 que não está 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 de API.
    • Duplicate: Clique para duplicar o serviço de API.
    • Delete: Clique para excluir o serviço de API.

É possível configurar múltiplos serviços para um único serviço OData. Você deve adicionar pelo menos uma entidade para prosseguir para a próxima aba.

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

Aba Security profiles

A aba Security profiles é opcional e permite que você restrinja o acesso para consumo da API.

aba security profiles

Configure as seguintes configurações:

  • Atribuir: Use a opção 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 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, talvez seja 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.

Dica

As alterações nas atribuições de perfis de segurança são salvas como rascunhos. É necessário publicar a API usando Salvar e Publicar para aplicar as alterações e permitir a exclusão de perfis atribuídos anteriormente. Perfis de segurança não podem ser excluídos enquanto aparecem na configuração publicada de qualquer API, mesmo que tenha os desatribuído em uma versão de rascunho.

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 voltar à 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 no API Manager.

aba funções de usuário

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 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:

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 Admin sempre tem acesso total a todas as APIs e, portanto, não pode ser removida da seleção.

Nota

As APIs criadas antes do Harmony 10.22 têm todas as funções de usuário selecionadas por padrão para garantir acesso contínuo para todos os usuários.

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 aba 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 abas obrigatórias, é possível salvar ou publicar a API:

  • Salvar como rascunho: Salva a API com status Rascunho ou Publicado com Rascunho. APIs de rascunho não contam contra o limite de assinatura URL de API. Uma API cujo status era Publicado no momento em que usa Salvar como rascunho é salva como Publicado com Rascunho. Uma API publicada conta contra o limite de assinatura 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 seu limite de assinatura de URL de API. Um diálogo indica que a API está ativa:

    all set your API is live custom API

    O diálogo fornece estas opções:

Parâmetros de consulta OData

Você pode filtrar os dados retornados anexando 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:

Parâmetro Descrição
$filter Filtra os resultados com base em uma expressão booleana.
$select Especifica quais propriedades incluir na resposta.
$orderby Classifica os resultados por uma ou mais propriedades.
$top Retorna apenas os primeiros n resultados.
$skip Ignora os primeiros n resultados.
$count Retorna a contagem dos resultados correspondentes.

Exemplo

Para recuperar os 10 principais clientes classificados por nome, anexe os parâmetros de consulta à URL do serviço:

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

Observação

Quando nenhum dado corresponde a uma consulta de sistema $inlinecount ou $count, o serviço OData retorna um erro por padrão. Quando você usa a versão 11.32 do agente ou posterior, pode configurar $noErrorOnZeroCount como true para retornar 0 (em vez de um erro) para consultas de sistema $count.

Editar a API

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

Ao editar uma API publicada na visualização em 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 mais detalhes, consulte a guia Documentação na página APIs.

Solução de problemas

Para solução de problemas relacionados, consulte os itens a seguir no guia de solução de problemas do API Manager: