Ir para o conteúdo

Configuração de API Customizada

Introdução

Esta página descreve como criar e configurar uma API Customizada em Minhas APIs página do Harmony API Manager. APIs personalizadas são um dos três tipos de APIs configurado por meio do API Manager. Para os outros dois tipos — Serviço OData e proxy de API — consulte configuração do Serviço OData e configuração da proxy de API.

Como alternativa, APIs personalizadas podem ser criadas no Cloud Studio usando Publicar como API opção acessada a partir de um menu de ação da operação.

Nota

Depois de publicada, cada API Customizada conta como um URL da API em relação ao seu limite de assinatura do Harmony.

Pré-requisitos

Como uma API Customizada expõe uma operação do Harmony para consumo, tal operação deve primeiro ser criada e implantada no Harmony. A operação existente é então referenciada durante a configuração da API Customizada. A operação que uma API Customizada aciona pode ser um Cloud Studio ou Design Studio operação.

Para obter instruções sobre como criar e implantar uma operação, consulte estes recursos:

Criando uma Nova API Customizada

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 uma nova API Customizada, clique em Nova API:

sem APIs nova API

Ao clicar em Nova API, a tela de configuração da API Customizada é aberta. Detalhes sobre como configurar uma nova API Customizada são fornecidos em Configurando uma API Customizada abaixo.

Configurando uma API Customizada

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 após a conclusão da etapa 1:

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

selecione o tipo de serviço

  • Tipo de serviço: Selecione API Customizada.

  • Adicionar serviço de API: Clique para adicionar um serviço de API para expor uma operação Harmony para consumo. Uma vez clicado, a configuração individual do serviço API é aberta (descrita abaixo). Vários serviços de API podem ser adicionados a uma API Customizada.

Após clicar em Adicionar Serviço API, a configuração de um serviço API é aberta:

publicar nova etapa 2 da API atribuir operações personalizadas

  • Método de solicitação: Use o menu para selecionar o método de solicitação para o serviço API, um de GET, POST, PUT, DELETE, ALL ou PERSONALIZADO. Selecionar TODOS criará GET, PUT, POST, e DELETE métodos para a Operação selecionada (o CUSTOM método não está incluído). Por padrão, o método de solicitação é definido como GET.

    Nota

    Serviços de API usando um CUSTOM método não terá documentação OpenAPI gerada através do Gerenciador de Portal devido a uma limitação da especificação OpenAPI.

  • Nome do serviço: Insira um nome para o serviço API.

  • Caminho: Opcionalmente, insira um caminho para a solicitação. O caminho deve começar com uma barra / e deve ter todos os parâmetros de solicitação entre chaves { }. Quaisquer outros caracteres especiais não são permitidos.

    Nota

    A combinação do método de solicitação e Path deve ser exclusiva para cada serviço de API na API Customizada.

  • Nome do método personalizado: Visível quando CUSTOM é selecionado como Método de solicitação. Insira o nome do método a ser usado, por exemplo, PATCH. (Somente caracteres alfabéticos, hifens - e sublinhados _).

  • Operação: Na aba Operação, você seleciona um projeto e uma operação para atribuir ao serviço de API (necessário para ativar o botão Salvar):

    • Atribuir projeto: Use o menu para selecionar um projeto implantado no ambiente onde a API está sendo configurada (especificado em Etapa 1: Configurações).

    • Editar projeto: Quando um projeto do Cloud Studio é selecionado, este botão é ativado. Clicar em Editar projeto abre o projeto no Cloud Studio em uma nova aba.

      Nota

      Você deve implantar quaisquer alterações feitas no projeto para que elas entrem em vigor.

    • Atribuir operação(ões): Use os menus para selecionar uma Operação e um Tipo de resposta para o serviço de API:

      • Operação: Selecione uma das operações implantadas no projeto selecionado.

        Importante

        Por padrão, as operações bem-sucedidas configuradas para uma API Customizada 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.

      • Tipo de resposta: Selecione entre Alvo final, Variável do sistema ou Sem resposta:

        • Alvo Final: A resposta da API é o alvo final da cadeia de operação. Quando este tipo de resposta é selecionado, a operação selecionada deve ter, como destino final da cadeia de operação, uma atividade de resposta de API do Cloud Studio ou Atividade de gravação de variável ou um destino de resposta da API do Design Studio ou alvo de variável global. Se qualquer outro destino final for usado, a resposta da API estará vazia.

        • Variável de Sistema: A resposta da API é definida em uma variável Jitterbit na cadeia de operação. Quando este tipo de resposta é selecionado, a operação selecionada deve ter, como parte da cadeia de operação, um script que configure a variável Jitterbit jitterbit.api.response igual à resposta que você deseja que a API retorne. Se esta variável não for definida, a resposta da API estará vazia.

        • Sem resposta: A resposta da API está em branco. Se a solicitação para executar a operação selecionada for aceita, a API retornará uma resposta vazia imediata com o código HTTP 202.

  • Parâmetros de caminho: Quando parâmetros de solicitação são incluídos em Caminho, esta aba é preenchida com estes campos:

    aba de parâmetros do caminho

    • Parâmetro: Exibe os parâmetros da solicitação definidos em Caminho.

    • Descrição: Opcionalmente, insira uma descrição para os parâmetros da solicitação.

  • Parâmetros de consulta: Esta aba permite adicionar quaisquer parâmetros de consultar ao serviço API:

    aba parâmetros de consultar

    • Adicionar parâmetro: Clique para adicionar um parâmetro de consultar ao serviço API. Depois de clicados, estes campos ficam disponíveis:

      • Parâmetro: Insira o nome do parâmetro de consultar.

      • Descrição: Opcionalmente, insira a descrição do parâmetro de consultar.

      • Excluir: Clique no ícone excluir ao lado de um parâmetro de consultar para excluir esse parâmetro.

  • Cabeçalhos: Esta aba permite adicionar qualquer cabeçalho de solicitação ao serviço de API:

    aba de cabeçalhos

    • Adicionar parâmetro: Clique para adicionar um cabeçalho de solicitação ao serviço de API. Depois de clicados, estes campos ficam disponíveis:

      • Parâmetro: Insira o nome do cabeçalho da solicitação.

      • Descrição: Opcionalmente, insira a descrição do cabeçalho da solicitação.

      • Obrigatório: Selecione se o cabeçalho da solicitação deve ser obrigatório para cada solicitação de serviço de API.

      • Excluir: Clique no ícone excluir ao lado de um cabeçalho de solicitação para excluir esse cabeçalho.

  • Duplicar: Clique no ícone duplicado para criar uma duplicata do serviço API.

    Nota

    Depois que o serviço de API for duplicado, você deverá alterar o método de solicitação ou o Path, pois cada serviço de API deve ter uma combinação exclusiva desses campos.

  • Excluir: Clique no ícone excluir ao lado de um serviço de API para excluí-lo da API Customizada.

  • Salvar: Clique para salvar o serviço API. Quando a configuração de todos os serviços da API for concluída, os botões Próximo e Salvar alterações serão ativados. Uma configuração de serviço de API incompleta é indicada com um ícone de erro ao lado do nome do serviço API:

    serviço API incompleto

    Para resolver e ativar os botões Próximo e Salvar alterações, conclua a configuração ou exclua o serviço API.

  • Cancelar: Clique para cancelar a configuração do serviço API.

  • 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 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, a papel Administrador não pode ser apagada 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 ao 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 da API).

  • Gerar documento OpenAPI: Abre o Gerenciador do Portal, onde você pode gerar a documentação da API para o Portal página.
  • Dispensar: Fecha a caixa de diálogo.