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 das APIs página do Jitterbit API Manager. Um serviço OData é um dos três tipos de APIs configurada por meio do API Manager. Para os outros dois tipos — API personalizada e API proxy — consulte Configuração de API customizada ou Configuração da proxy de API.

Pré-requisitos

Como um serviço OData expõe uma operação de entidade da API Jitterbit iPaaS para consumo, tal operação deve ser criada e implantada primeiro. A operação que um serviço OData aciona deve ser uma operação de entidade da API do Design Studio. A operação de entidade da API existente é então referenciada durante a configuração do serviço OData. Nesta página, a palavra API é usada para se referir a um serviço OData.

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

Ao acessar o API ManagerAPIs, se não houver APIs personalizadas, serviços OData ou APIs de proxy na organização selecionada, esta tela ficará em branco.

Para criar um novo serviço OData, clique em Novo > API customizada:

Ao clicar em API customizada, a tela de configuração da API é aberta. Detalhes sobre como configurar um novo serviço OData são fornecidos em Configurar um serviço OData abaixo.

Configurar um serviço OData

A tela de configuração inclui quatro etapas de configuração, cada uma abordada abaixo:

• Etapa 1: Configurações
• Etapa 2: Selecione o tipo de serviço e atribua as operações
• Etapa 3: Atribuir funções de usuário e perfis de segurança
• Etapa 4: Resumo e confirmação

A URL de serviço de uma API é a URL usada para consumir a API usando um método de autenticação configurado. As partes da URL de serviço de uma API são descritas em Introdução ao API Manager em URL do serviço API.

O URL do serviço é exibido na parte superior de cada etapa:

Etapa 1: Configurações

• Nome da API: Insira um nome para a API usar para fins de identificação interna. Estes caracteres especiais são permitidos:

  ( ) - _

• 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 pressionamento de tecla.

  Nota

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

• Raiz do Serviço: O nome público da API a ser usado como parte da URL de 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 diferentes de sublinhado (_) não é recomendado. Estes caracteres especiais são permitidos:

  . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -

• 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. Usar caracteres especiais diferentes de um ponto final (.) ou um hífen (-) não é recomendado. Convenções de nomenclatura comuns incluem versões incrementais, como v1.0, v1.1, v1.2, ou usando uma data em que a API foi publicada, como 2021-08-28.

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

• Tempo limite: Insira o número de segundos antes do tempo limite da API. O padrão é 30 segundos. O máximo é 180 segundos.

  Nota

  Esta configuração é independente da configuração de tempo limite de operação no Integration Studio ou Design Studio. As configurações de tempo limite de operação não são usadas, a menos que um agente privado é usado e o EnableAPITimeout configuração no arquivo de configuração do agente privado está habilitado.

• Somente SSL: Quando selecionado (padrão), os dados são criptografados por meio de SSL e o HTTPS é aplicado para todas as solicitações e respostas da API (recomendado).

  Quando desmarcada, os dados transmitidos por meio de solicitações e respostas da API não são criptografados e podem ser interceptados e visualizados por terceiros. Isso pode expor informações confidenciais.

• Ativar CORS: Selecione para ativar Compartilhamento de Recursos de Origem Cruzada (CORS) (não recomendado). Habilitar CORS é selecionado por padrão.

  Aviso

  Habilitar o CORS causa operações usando o OPTIONS método para executar sem autenticação.

• Habilitar registro detalhado: Selecione para habilitar o registro detalhado. O registro detalhado para APIs inclui dados de solicitação e resposta em cada registro de API para ajudar a monitorar dados de entrada e saída e facilitar a depuração. Como isso pode criar arquivos de log grandes, o padrão é que o registro detalhado esteja desabilitado.

• Habilitar Modo de Depuração Até: Selecione para habilitar o modo de depurar e habilite a inserção de uma data e hora correspondentes em que o modo de depurar será desabilitado. O período máximo de habilitação é de duas semanas. O modo de depuração habilita o rastreamento completo para cada solicitação recebida por meio da URL de serviço da API. Quando habilitado, o sistema retém o conteúdo completo de cada solicitação e resposta da API por até 24 horas a partir do momento em que a chamada da API foi recebida e se aplica a todas as operações acionadas pela API.

  Nota

  A navegação pelos dados do evento pode se tornar difícil com grandes volumes (testes de carga, testes de pré-produção, etc.). O aumento de dados retidos pode resultar em problemas de espaço de armazenamento e segurança. Não recomendamos o uso do modo de depurar em um ambiente de produção.

• Próximo: Clique para armazenar temporariamente a configuração desta etapa e continuar para a próxima etapa.

• Salvar alterações: Clique para salvar a configuração desta etapa e navegar até Etapa 4: Resumo e confirmação.

Etapa 2: Selecione o tipo de serviço e atribua operações

• Tipo de serviço: Selecione serviço OData.

• Atribuir Entidades Jitterbit: Use os menus suspensos para selecionar uma Entidade (Projeto), Operação e Método para o serviço OData:

  • Entidade (Projeto): Selecione entre os projetos implantados que contêm um Design Studio operação de entidade de API no ambiente onde a API está sendo configurada.

  • Operação: Selecione no Design Studio implantado operações de entidade de API na Entidade (Projeto) selecionada. Apenas uma operação usando cada método pode ser atribuída.

    Importante

    Por padrão, as operações bem-sucedidas configuradas para um serviço OData não são incluídas nos logs de operação a menos que uma destas configurações esteja habilitada:

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

    Operações malsucedidas são incluídas nos registros de operação se as configurações acima estão habilitadas ou não.

  • Método: Selecione um dos GET, PUT, POST, DELETE, PATCH, MERGE, ou ALL o método a ser criado para a Operação selecionada. Selecionando ALL criará separado GET, PUT, POST, DELETE, PATCH, e MERGE métodos para a Operação selecionada.

• Atribuir Entidade: Após preencher todos os menus suspensos, clique em Atribuir Entidade para adicionar a entidade à tabela abaixo. Pelo menos uma entidade deve ser adicionada para habilitar o botão Avançar.

  Nota

  Após clicar em Atribuir Entidade, você não poderá mais alterar o Tipo de Serviço.

• Entidades Atribuídas: Uma tabela exibe todas as entidades que foram atribuídas. Para remover uma entidade atribuída, clique em Remover ícone.

• Próximo: Clique para armazenar temporariamente a configuração desta etapa e prosseguir para a próxima.

• Salvar alterações: Clique para salvar a configuração desta etapa e navegar até Etapa 4: Resumo e confirmação.

Etapa 3: atribuir funções de usuário e perfis de segurança

• Atribuir Funções de Usuário: Selecione as funções da organização cujos membros terão acesso à API nas páginas do API Manager listadas abaixo. As funções disponíveis são aquelas definidas na página Gerenciamento de Usuários do Management Console.

  Isso determina o acesso a esta API específica a partir destas páginas:

  • APIs
  • Gerenciador do Portal, incluindo geração de documentação de API
  • Portal
  • Registros da API
  • Análise

  Acesso aos 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 funções de usuário definidas com a permissão Admin sempre têm acesso total a todas as APIs e, portanto, não podem ser desmarcadas da seleção. (Na captura de tela de exemplo mostrada acima, as funções Administrador e Operações não podem ser desmarcadas por esse motivo.)

  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.

• Atribuir Perfil(es) de Segurança: Use o menu suspenso para selecionar um perfil de segurança existente que será usado para restringir o acesso para consumo da API. Você pode digitar qualquer parte do nome do perfil de segurança no menu para filtrar a lista de perfis de segurança. Os resultados do menu são filtrados em tempo real a cada pressionamento de tecla. Pode ser necessário atribuir um perfil de segurança para salvar a API, dependendo das políticas da organização Harmony.

  • Atribuir Perfil: Clique para atribuir um perfil de segurança selecionado à API. Os perfis de segurança atribuídos são listados na tabela com o Nome do Perfil e o Tipo conforme configurado para o perfil de segurança em Configuração do perfil de segurança. Se o Tipo for Básico, a coluna Nome de usuário exibirá o Nome de usuário fornecido durante a configuração. Se o Tipo for qualquer outro tipo, a coluna Nome de usuário exibirá o mesmo valor que o Tipo. Para remover um perfil atribuído, clique no botão Remover ícone.

  • Criar Novo Perfil: Clique para criar um novo perfil de segurança. Para obter instruções, consulte Configuração do perfil de segurança.

• Próximo: Clique para armazenar temporariamente a configuração desta etapa e prosseguir para a próxima. Se a API não tiver um perfil de segurança obrigatório, esta opção será desabilitada.

• Salvar alterações: Se habilitada, clique para salvar a configuração desta etapa. Se a API não tiver um perfil de segurança obrigatório, esta opção será desabilitada.

• Ignorar esta etapa: Se presente, clique para prosseguir para a próxima etapa sem armazenar a configuração desta etapa. Se a API não tiver um perfil de segurança obrigatório, esta opção não estará disponível.

Etapa 4: Resumo e confirmação

• Nome da API e Ambiente: O nome da API seguido pelo ambiente entre parênteses, conforme configurado em Etapa 1: Configurações.

  • Descrição, Tempo limite, Somente SSL, CORS habilitado e Registro detalhado habilitado: A descrição da API e outras configurações que estão habilitadas () ou desabilitado (). Para fazer alterações nessas configurações, clique em ícone de edição para retornar para Etapa 1: Configurações.
  • Habilitar Modo de Depuração Até: Esta opção é a mesma descrita em Etapa 1: Configurações. Você pode alterar essa configuração diretamente nesta etapa, sem precisar retornar à primeira.

• Operações: As operações atribuídas na Etapa 2: Selecionar o tipo de serviço e atribuir operações com as informações correspondentes ao tipo de serviço selecionado. Para fazer alterações, clique no botão ícone de edição para retornar para Etapa 2: Selecione o tipo de serviço e atribua operações.

• Funções de Usuário e Perfis de Segurança: As funções e os perfis de segurança atribuídos em Etapa 3: Atribuir funções de usuário e perfis de segurança. Para fazer alterações, clique no ícone de edição para retornar para Etapa 3: Atribuir funções de usuário e perfis de segurança.

• Exportar: Gera e inicia o download de um arquivo APK (apis-export.apk) contendo uma exportação da API (consulte Exportando e importando APIs).

• Clone: Cria uma cópia de uma API existente. Na cópia da API, o nome da API é precedido por Cópia de, a Raiz do Serviço é precedida por Cópia de e a Versão é anexada por -2. A cópia da API é aberta imediatamente Etapa 4: Resumo e confirmação.

• Excluir: Exclui permanentemente a API e fecha a configuração. Uma caixa de diálogo solicita que você confirme se deseja excluir a API.

  Nota

  Se o status da API era Publicado ou Publicado com Rascunho no momento da exclusão, ela também será removida do número de URLs de API usadas em relação ao seu limite de assinatura. Se o status da API era Rascunho no momento da exclusão, o número de URLs de API usadas em relação ao seu limite de assinatura não será alterado, pois a API não estava acessível enquanto estava no status Rascunho.

• Salvar como rascunho: Salva a API no status Rascunho ou Publicado com rascunho:

• Rascunho: Uma nova API ou uma API cujo status era Rascunho no momento em que Salvar como Rascunho foi usado. Rascunhos não contam para o seu limite de assinatura de URL da API.

• Publicada com Rascunho: Uma API cujo status era Publicada no momento em que Salvar como Rascunho é usada. Uma API publicada com um rascunho é contabilizada no seu limite de assinaturas de URL da API, pois a API está acessível, embora seu rascunho não esteja.

• Salvar e Publicar: Salva a API no status Publicada. A API fica ativa e acessível em até cinco minutos. Uma API publicada é contabilizada no seu limite de assinaturas de URL da API, pois a API está acessível. Uma caixa de diálogo indica que a API está ativa:

  

• Copiar URL: Copia a URL do serviço da API (consulte URL do serviço da API).

• Gerar Documento OpenAPI: Abre o Gerenciador de Portal página, onde você pode gerar documentação de API para o Portal página. Embora este link apareça para serviços OData, a documentação OpenAPI pode ser gerada para APIs personalizadas somente.
• Descartar: Fecha a caixa de diálogo.

Consultas de serviço OData

Dependendo do banco de dados, você pode filtrar os dados retornados anexando parâmetros de consultar OData (como $count, $inlinecount, e $filter) para uma URL de serviço OData.