Ir para o conteúdo

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 Customizada e proxy de API — consulte Configuração de API Customizada ou configuração da proxy de API.

Nota

Quando publicado, cada Serviço OData conta como um URL de API em relação ao seu limite de assinatura do Harmony.

Pré-requisitos

Como um Serviço OData expõe uma operação de entidade da API Harmony para consumo, tal operação deve primeiro ser criada e implantada no Harmony. A operação que um Serviço OData aciona deve ser uma operação de entidade de API do Design Studio. A operação da 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:

Crie um Novo Serviço OData

Ao acessar o API Manager Minhas APIs, se não existirem 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:

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

O URL de serviço de uma API é o URL usado para consumir a API usando um método de autenticação configurado. As partes do 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:

publicar novo URL do serviço de configurações da etapa 1 da API

Etapa 1: Configurações

publicar novas configurações da etapa 1 da API

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

    ( ) - _

  • Ambiente: O ambiente onde a API reside.

    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: A nome público da API a ser usada como parte do 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 determinados caracteres especiais. Usando 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 do URL de serviço da API. Este campo permite no máximo 48 caracteres e não permite espaços ou determinados caracteres especiais. Usando caracteres especiais diferentes de ponto final (.) ou um hífen (-) não é recomendado. As convenções de nomenclatura comuns incluem versões incrementais, como v1.0, v1.1, v1.2ou 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 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 em 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á ativado.

  • Somente SSL: Selecione exigir o uso de criptografia SSL (recomendado). Somente SSL é selecionado por padrão.

  • Ativar CORS: Selecione para ativar Compartilhamento de recursos entre origens (CORS) (não recomendado). Ativar CORS é selecionado por padrão.

    Aviso

    Habilitar o CORS faz com que operações usando o OPTIONS método para ser executado sem autenticação.

  • Ativar registro detalhado: Selecione para ativar 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 arquivos de log grandes, o padrão é que o log detalhado esteja desabilitado.

  • Ativar modo de depuração até: Selecione para ativar o modo de depurar e ativar a inserção de uma data e hora correspondentes nas quais o modo de depurar será desativado. A duração máxima da habilitação é de duas semanas. O modo de depuração permite o rastreamento completo de cada solicitação recebida por meio do URL de serviço da API. Quando ativado, 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 passagem pelos dados do evento pode se tornar difícil com grandes volumes (testes de carga, testes de pré-produção, etc.). O aumento nos dados retidos pode resultar em problemas de 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

publicar nova etapa 2 da API atribuir entidades jitterbit odata

  • 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 API Entity Operation 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. Somente 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:

      As operações malsucedidas são incluídas nos logs de operação estejam as configurações acima 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 ativar o botão Próximo.

    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 ícone remover .

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

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

Etapa 3: Atribuir Funções de Usuário e Perfis de Segurança

publicar novos perfis de segurança de funções de usuário da etapa 3 da API

  • 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 Organizações do Management Console (consulte Gerenciamento de funções e permissões em Organizações).

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

    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 apagadas da seleção. (Na captura de tela de exemplo mostrada acima, as funções Administrador e Operações não podem ser apagadas por esse motivo.)

    Nota

    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. 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 Nome do perfil e Tipo conforme configurado para o perfil de segurança em Configuração do perfil de segurança. Se Tipo for Básico, a coluna Nome de usuário exibirá o Nome de usuário fornecido durante a configuração. Se Type for qualquer outro tipo, a coluna Username exibirá o mesmo valor que Type. Para remover um perfil atribuído, clique no ícone de remoção .
    • 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 continuar para a próxima etapa. Se a API não receber um perfil de segurança obrigatório, esta opção será desativada.

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

  • Pular esta etapa: Se presente, clique para continuar na próxima etapa sem armazenar a configuração desta etapa. Se não for atribuído à API um perfil de segurança obrigatório, esta opção não estará presente.

Etapa 4: Resumo e Confirmação

publicar novo resumo da etapa 4 da API

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

    • Descrição, Tempo limite, Somente SSL, CORS ativado e Log detalhado ativado: A descrição da API e outras configurações que estão ativadas () ou desativado (). Para fazer alterações nessas configurações, clique no ícone de edição para retornar ao Etapa 1: Configurações.
    • Ativar 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, em vez de precisar retornar à primeira etapa.
  • Operações: As operações atribuídas na 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 à Etapa 2: Selecionar tipo de serviço e atribuir operações.

  • Funções de usuário e Perfis de segurança: As funções e perfis de segurança atribuídos na 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 à 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, Nome da API é prefixado com Copy of, Service Root é prefixado com Copyof e Version é anexado com -2. A cópia da API é imediatamente aberta Etapa 4: Resumo e confirmação.

  • Excluir: Exclui permanentemente a API e fecha a configuração. Uma caixa de diálogo solicitará que você confirme 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 será removido do número de URLs de API usados em 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 Publicada com status Rascunho:

  • Rascunho: Uma nova API ou uma API cujo status era Rascunho no momento em que Salvar como rascunho foi usado. Os rascunhos não contam para o 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 publicada com um rascunho conta para seu limite de assinatura de API URL, pois a API é acessível, mas seu rascunho não.

  • Salvar e publicar: Salva a API no status Publicado. A API está ativa e acessível em cinco minutos. Uma API publicada é contabilizada em seu limite de assinatura de API URL, pois a API está acessível. Uma caixa de diálogo indica que a API está ativa:

    tudo configurado, sua API é uma API personalizada ao vivo

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

  • Gerar documento OpenAPI: Abre o Gerenciador do Portal, onde você pode gerar a documentação da 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 apenas.
  • Dispensar: Fecha a caixa de diálogo.