Configuração da Proxy de API¶

Introdução¶

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

Pré-requisitos¶

Ao contrário de uma API Customizada ou Serviço OData, que expõe uma operação Harmony para consumo, uma proxy de API é usada com uma API existente. APIs com proxy não são roteadas por meio de Harmony Agents. A API que está sendo proxy deve estar acessível ao gateway que processa a API:

• Gateway de API em Nuvem: Se estiver usando o Gateway de API em Nuvem (hospedado pela Jitterbit), a API existente deve estar acessível publicamente, mesmo que segura. Ou seja, a API que você está tentando fazer proxy não pode estar atrás de um firewall. Para lista de permissões o acesso dos endereços IP do Gateway de API em Nuvem à API que está sendo proxy, consulte Informações da lista de permissões e navegue até https://services.jitterbit para sua região.
• Gateway de API Privado: Se estiver usando um Gateway de API Privado (hospedado em uma rede privada) a API existente deve ser acessível pelo Gateway de API Privado.

Embora cada proxy de API permita que vários serviços sejam atribuídos a um URL exclusivo, o URL de proxy base está consumindo o direito.

Criando uma Nova Proxy de API¶

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 proxy de API, clique em Novo Proxy:

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

Configurando uma Proxy de API¶

A tela de configuração da proxy de API inclui cinco etapas de configuração, cada uma abordada abaixo:

• Etapa 1: Configurações básicas

• Etapa 2: API existente

• Etapa 3: Definir Serviços e Métodos

• Etapa 4: Atribuir perfis de segurança e cabeçalhos de solicitação

• Etapa 5: Resumo e Confirmação

O URL de serviço de uma API é o URL usado para consumir a API usando o 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:

Etapa 1: Configurações Básicas¶

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

  ( ) - _

• Número da 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 hífen (-) não é recomendado. Exemplos de convenções de nomenclatura incluem versões incrementais, como v1.0, v1.1, v1.2, etc., ou usando uma data em que a API foi publicada, como 2021-08-28.

• 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: O 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 do proxy 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:

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

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

• 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.

• 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 o EnableAPITimeout configuração no arquivo de configuração do Agente Privado está ativado.

• Somente SSL: Selecione para usar criptografia SSL (recomendado). O padrão está selecionado.

• Ativar CORS: Selecione para ativar Compartilhamento de recursos de origem cruzada (CORS) (não recomendado). O padrão é desmarcado.

  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. O padrão é desmarcado.

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

• Salvar alterações: Se ativado, clique para salvar a configuração desta etapa e navegar até Etapa 5: Resumo e confirmação.

etapa 2: API Existente¶

• URL base da API: Insira o URL base da API para proxy.

  Nota

  Se a API fornecer um único serviço, você poderá inserir o URL completo da API, incluindo o caminho do serviço. Caminhos de serviço adicionais são definidos em Etapa 3: Definir serviços e métodos.

• Fornecer documento OpenAPI: Se um documento OpenAPI for fornecido, ele será usado para descobrir automaticamente os serviços da API. Selecione Não para pular ou Sim para expandir uma área adicional para fornecer o documento OpenAPI:

  

  • Carregar URL: Abre uma caixa de diálogo para carregar um documento OpenAPI em formato YAML ou JSON a partir de um URL:

    

  • Carregar arquivo: Abre uma caixa de diálogo para carregar um documento OpenAPI em formato YAML ou JSON após usar Browse para selecionar o arquivo:

    

  • Limpar: Limpa um documento OpenAPI que já foi fornecido e altera a seleção Fornecer documento OpenAPI para Não.

  • Editor de Documento: Permite visualizar e editar um documento OpenAPI fornecido. Você também pode fornecer um documento OpenAPI inserindo-o diretamente aqui. Para visualizar e editar o documento OpenAPI em uma área maior, clique no ícone pop-out (após abrir essa área, clique no ícone retornar para voltar a esta tela).

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

• Salvar alterações: Se ativado, clique para salvar a configuração desta etapa e navegue até Etapa 5: Resumo e confirmação.

• Descartar alterações: Após fazer as alterações, clique para fechar a configuração sem salvar as alterações feitas em nenhuma etapa. Uma mensagem solicita que você confirme que deseja descartar as alterações.

Etapa 3: Definir Serviços e Métodos¶

A forma como os serviços e métodos são definidos depende se a seleção em Etapa 2: API existente para Fornecer documento OpenAPI foi Não ou Sim:

• Não: Se um documento OpenAPI não foi fornecido, os serviços e métodos devem ser definidos manualmente (consulte Definição Manual abaixo).
• Sim: Se um documento OpenAPI foi fornecido, os serviços e métodos são descobertos automaticamente no documento OpenAPI e então selecionados (consulte Descoberta automática de documentos OpenAPI abaixo).

Definição Manual¶

• Definir serviços e métodos: Quando um documento OpenAPI não foi fornecido na Etapa 2: API existente, você deve definir seus serviços e métodos manualmente usando estes campos:

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

  • Caminho: Insira um caminho para o serviço. Se a API não tiver um caminho de serviço, insira uma barra (/).

    Nota

    Usando caracteres como chaves ({ }) em um caminho de serviço não é possível ao definir serviços manualmente. Para usar caracteres não permitidos em um caminho de serviço, forneça um documento OpenAPI definindo o caminho em Etapa 2: API existente.

  • Métodos: Selecione cada método a ser criado para o serviço, selecionando entre GET, PUT, POST, DELETE e Personalizado. Quando Personalizado estiver selecionado, insira um ou mais métodos personalizados separados por vírgula na caixa de texto exibida abaixo:

    

• Adicionar serviço: Depois que todos os campos forem preenchidos, clique em Adicionar serviço para adicionar o serviço à tabela abaixo. Pelo menos um serviço deve ser adicionado para ativar o botão Próximo.

• Serviços Adicionados: Uma tabela exibe todos os serviços que foram adicionados. Para remover um serviço adicionado, clique no ícone de remoção .

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

• Salvar alterações: Se ativado, clique para salvar a configuração desta etapa e navegue até Etapa 5: Resumo e confirmação.

Descoberta Automática de Documentos OpenAPI¶

• Definir serviços e métodos: Quando um documento OpenAPI foi fornecido na Etapa 2: API existente, seus serviços são descobertos automaticamente no documento OpenAPI e listados em uma tabela com estas colunas:
  • Selecionar: Selecione os serviços a serem adicionados à proxy de API. A caixa de seleção na coluna do cabeçalho pode ser usada para adicionar todos os serviços disponíveis de uma só vez.
  • Nome do serviço: O nome usado para identificar o serviço.
  • Método(s): Os métodos que se aplicam ao serviço.
  • Caminho: O caminho do serviço.
• Próximo: Clique para armazenar temporariamente a configuração desta etapa e continuar para a próxima etapa.
• Salvar alterações: Se ativado, clique para salvar a configuração desta etapa e navegar até Etapa 5: Resumo e confirmação.
• Descartar alterações: Após fazer as alterações, clique para fechar a configuração sem salvar as alterações feitas em nenhuma etapa. Uma mensagem solicita que você confirme que deseja descartar as alterações.

Etapa 4: Atribuir Perfis de Segurança e Cabeçalhos de Solicitação¶

• Perfil(s) de segurança: Perfis de segurança são usados 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.
  • Perfis disponíveis: Use o menu suspenso para selecionar um perfil de segurança existente.
  • Atribuir perfil: Clique para atribuir um perfil de segurança selecionado à API.
  • Criar novo perfil: Clique para criar um novo perfil de segurança. Para obter instruções, consulte Configuração do perfil de segurança.
• Perfis atribuídos: Uma tabela lista os perfis de segurança atribuídos. Para remover um perfil atribuído, clique no ícone de remoção .
• Cabeçalhos de solicitação: Novos cabeçalhos de solicitação podem ser adicionados ou os cabeçalhos de solicitação existentes podem ser substituídos usando estas configurações:
  • Chave: Insira uma chave para o cabeçalho da solicitação.
  • Valor: Insira um valor para o cabeçalho da solicitação.
  • Substituir entrada: Selecione para substituir um cabeçalho de solicitação existente que usa a mesma Chave. O padrão é desmarcado.
  • Atribuir campo de cabeçalho: Depois que uma Chave e um Valor forem inseridos, clique para atribuir o cabeçalho da solicitação à API.
• Campos de cabeçalho: Os campos de cabeçalho atribuídos acima na seção Cabeçalhos de solicitação são exibidos em uma tabela. Para remover um campo de cabeçalho atribuído, clique no ícone de remoção .
• 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 e navegue até Etapa 5: Resumo e confirmação. Se a API não receber um perfil de segurança obrigatório, esta opção será desativada.

Etapa 5: Resumo e Confirmação¶

• Nome do proxy e Ambiente: O nome da API e o ambiente, conforme configurado na Etapa 1: Configurações básicas.

• 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 Editar para retornar ao Etapa 1: Configurações básicas.

  • Ativar modo de depuração até: Esta opção é a mesma descrita em Etapa 1: Configurações básicas. Você pode alterar essa configuração diretamente nesta etapa, em vez de precisar retornar à primeira etapa.

• API existente: O URL da API base fornecido na Etapa 2: API existente. Para fazer alterações, clique no ícone Editar para retornar à Etapa 2: API existente.

• Serviços e Métodos: Os serviços definidos na Etapa 3: Definir Serviços e Métodos. Para fazer alterações, clique no ícone Editar para retornar à Etapa 3: Definir serviços e métodos.

• Perfis de segurança e Cabeçalhos de solicitação: Os perfis de segurança e cabeçalhos de solicitação atribuídos na Etapa 4: Atribuir perfis de segurança e cabeçalhos de solicitação. Para fazer alterações, clique no ícone Editar para retornar à Etapa 4: Atribuir perfis de segurança e cabeçalhos de solicitação.

• 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 do proxy é prefixado com Copy of, a Service Root é anexada com Copyof e a Version é anexada com -2. A cópia da API é imediatamente aberta Etapa 5: 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 proxy usados em seu limite de assinatura. Se o status da API era Rascunho no momento da exclusão, o número de URLs de proxy 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 URL proxy.
  • Publicado com rascunho: Uma API cujo status era Publicado no momento em que Salvar como rascunho é usada. Uma API publicada com um rascunho conta em seu limite de assinatura de URL de proxy, 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 URL de proxy, pois a API está acessível. Uma caixa de diálogo indica que a API está ativa. Clique em Copiar URL para copiar o URL do serviço da API (consulte URL do serviço da API):