Configuração do Serviço OData

Introdução

Esta página descreve como criar e configurar um serviço OData a partir de Minhas APIs página do Harmony API Manager. Um serviço OData é um dos três tipos de APIs configurado 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 Harmony API para consumo, tal operação deve primeiro ser criada e implantada no Harmony. A operação que um serviço OData aciona deve ser um Design Studio operação de entidade da API. A operação de entidade 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 API

Crie um Novo Serviço OData

Ao acessar o API Manager Minhas APIs, 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 Nova API:

Ao clicar em Nova API, a tela de configuração do serviço OData é 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 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 API Manager get started 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. Esses 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 com 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 clonar a 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 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. Usar caracteres especiais diferentes de um sublinhado (_) não é recomendado. Esses 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 (.) 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.

• Timeout: Insira o número de segundos antes que a API expire. 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 Cloud 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 de API (recomendado).

  Quando desmarcado, os dados passados por solicitações e respostas de API não são criptografados e podem ser interceptados e visualizados por outros. Isso pode expor informações confidenciais.

• Habilitar CORS: Selecione para habilitar 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 log de API para ajudar a monitorar dados de entrada e saída e facilitar a depuração. Como isso pode criar grandes arquivos de log, o padrão é que o log verbose 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 nas quais o modo de depurar será desabilitado. A duração máxima da 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 travessia 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 preocupações com espaço de armazenamento e segurança. Não recomendamos usar o 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 da 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 estar habilitado na operação ou você deve definir EnableLogging=true no [APIOperation] seção do arquivo de configuração do agente privado.

    As 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: Depois que todos os menus suspensos forem concluídos, 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 no remover ícone.

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

• Salvar alterações: Clique para salvar a configuração para esta etapa e navegar para 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 de dentro das páginas do API Manager listadas abaixo. As funções para escolher são aquelas definidas dentro da página Gerenciamento de Usuário do Management Console.

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

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

  Acesso aos Perfis de Segurança página 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 Administrator e Operations 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 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 para esta etapa e continuar para a próxima etapa. Se a API não tiver um perfil de segurança necessário atribuído, esta opção será desabilitada.

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

• Ignorar esta etapa: Se presente, clique para continuar para a próxima etapa sem armazenar a configuração para esta etapa. Se a API não tiver um perfil de segurança necessário atribuído, esta opção não estará presente.

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 desta etapa em vez de precisar retornar à primeira etapa.

• Operações: As operações atribuídas em Etapa 2: Selecionar tipo de serviço e atribuir operações com as informações correspondentes para o tipo de serviço selecionado. Para fazer alterações, clique no í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 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 é prefixado com Cópia de, a Raiz do Serviço é prefixada com Cópia de e a Versão é anexada com -2. A cópia da API é imediatamente aberta por conta própria Etapa 4: Resumo e confirmação.

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

  Nota

  Se o status da API era Publicado ou Publicado com Rascunho no momento da exclusão, ele também é removido do número de URLs de API usados 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 usados em relação ao seu limite de assinatura não muda, 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 seu limite de assinatura de API URL.

• Publicado com Rascunho: Uma API cujo status era Publicado no momento em que Salvar como Rascunho é usada. Uma API que é publicada com um rascunho conta contra seu limite de assinatura de API URL, pois a API é acessível, embora seu rascunho não seja.

• Salvar e publicar: Salva a API no status Publicado. A API fica ativa e acessível em cinco minutos. Uma API publicada conta contra seu limite de assinatura de API URL, 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 Portal Manager 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.
• Dismiss: Fecha o 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.