Configuração de API Customizada

Introdução

Esta página descreve como criar e configurar uma API personalizada a partir de 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 API proxy — 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 uma API opção acessada a partir de um menu de ação da operação.

APIs personalizadas (publicadas e rascunhos) são exibidas nestes locais:

• As Minhas APIs página do API Manager.
• A aba Recursos do painel do projeto para o projeto do Cloud Studio associado à API personalizada.

Pré-requisitos

Como uma API personalizada expõe uma operação 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 personalizada. A operação que uma API personalizada 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:

• Cloud Studio
  • Criação e configuração da operação
  • Implantação e execução da operação
• Design Studio
  • Criando uma operação

Crie uma Nova API Personalizada

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

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

Configurar uma API Personalizada

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

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 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 faz com que as operações que usam 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 API Customizada.

• Adicionar serviço de API: Clique para adicionar um serviço de API para expor uma operação Harmony para consumo. Após clicar, a configuração de serviço de API individual é aberta (descrita abaixo). Vários serviços de API podem ser adicionados a uma API personalizada.

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

• Método de solicitação: Use o menu para selecionar o método de solicitação para o serviço de API, um de GET, POST, PUT, DELETE, ALL ou CUSTOM. Selecionar ALL criará GET, PUT, POST, e DELETE métodos para a Operação selecionada (a 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 Portal Manager devido a uma limitação da especificação OpenAPI.

• Nome do serviço: Insira um nome para o serviço da 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 colchetes { }. Nenhum outro caractere especial é permitido.

  Nota

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

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

• Operação: Na aba Operação, você seleciona um projeto e uma operação para atribuir ao serviço de API (necessário para habilitar 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). Você pode digitar qualquer parte do nome do projeto no menu para filtrar a lista de projetos. Os resultados do menu são filtrados em tempo real com cada pressionamento de tecla.

  • Editar Projeto: Quando um projeto do Cloud Studio é selecionado, este botão é habilitado. 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 entre as operações implantadas no projeto selecionado. Você pode digitar qualquer parte do nome da operação no menu para filtrar a lista de operações implantadas. Os resultados do menu são filtrados em tempo real a cada pressionamento de tecla.

      Importante

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

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

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

      • Variável do sistema: A resposta da API é definida em uma variável Jitterbit na cadeia de operação. Quando esse tipo de resposta é selecionado, a operação selecionada deve ter, como parte da cadeia de operação, um script que define a variável Jitterbit jitterbit.api.response igual à resposta que você quer que a API retorne. Se essa 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 os parâmetros de solicitação são incluídos no Caminho, esta aba é preenchida com estes campos:

  

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

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

• Parâmetros de consulta: Esta aba permite que você adicione quaisquer parâmetros de consultar ao serviço de API:

  

  • Adicionar parâmetro: Clique para adicionar um parâmetro de consultar ao serviço de API. Após clicar, 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 que você adicione quaisquer cabeçalhos de solicitação ao serviço de API:

  

  • Adicionar parâmetro: Clique para adicionar um cabeçalho de solicitação ao serviço de API. Após clicar, 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 de exclusão ao lado de um cabeçalho de solicitação para excluir esse cabeçalho.

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

  Nota

  Depois que o serviço de API for duplicado, você deverá alterar o método de solicitação ou o Caminho, 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 personalizada.

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

  

  Para resolver e habilitar os botões Avançar e Salvar alterações, conclua a configuração ou exclua o serviço de API.

• Cancelar: Clique para cancelar a configuração do serviço de 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

• Atribuir Funções de Usuário: Selecione as funções da organização cujos membros terão acesso à API a partir das páginas do API Manager listadas abaixo. As funções para escolher são aquelas definidas na aba Funções da página Gerenciamento de Usuário.

  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, a papel Administrator não pode ser desmarcada 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.
• Dispensar: Fecha o diálogo.