Configuração da Proxy de API

Introdução

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

Pré-requisitos

Diferentemente de uma API personalizada ou serviço OData, que expõe uma operação Harmony para consumo, uma API proxy é usada com uma API existente. APIs proxy não são roteadas por meio de agentes Harmony. A API que está sendo proxyada deve ser acessível ao gateway que processa a API:

• Gateway da API da nuvem: Se estiver usando o gateway da API da nuvem (hospedado pelo Jitterbit) a API existente deve ser acessível publicamente, mesmo se protegida. Ou seja, a API que você está tentando usar como proxy não pode estar atrás de um firewall. Para lista de permissões que os endereços IP do gateway da API da nuvem sejam listados para permitir que o gateway acesse a API que está sendo usada como 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 (hospedada em uma rede privada), a API existente deve ser acessível pelo gateway de API privado.

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

Crie uma Nova API de Proxy

Ao acessar o API Manager Minhas APIs, se nenhuma API personalizada, serviço OData ou API proxy existir na organização selecionada, esta tela ficará em branco.

Para criar uma nova API de proxy, clique em Novo proxy:

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

Configurar uma API Proxy

A tela de configuração da API de proxy 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

A URL de serviço de uma API é a URL usada para consumir a API usando o 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 Básicas

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

  ( ) - _

• Número da 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 hífen (-) não é recomendado. Convenções de nomenclatura de exemplo 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: 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 do proxy 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:

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

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

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

• Time out: 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 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 a 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.

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

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

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

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

etapa 2: API Existente

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

  Nota

  Se a API fornecer um único serviço, você poderá inserir a URL completa 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 autodescobrir 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 no formato YAML ou JSON de uma URL:

    

  • Carregar arquivo: Abre uma caixa de diálogo para carregar um documento OpenAPI no formato YAML ou JSON após usar Navegar 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 documentos: Permite a visualização e edição de um documento OpenAPI fornecido. Você também pode fornecer um documento OpenAPI inserindo-o aqui diretamente. Para visualizar e editar o documento OpenAPI em uma área maior, clique no ícone pop-out (depois de abrir essa área, clique no ícone de retorno para voltar a esta tela).

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

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

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

Etapa 3: Definir Serviços e Métodos

A maneira 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, serviços e métodos são descobertos automaticamente a partir do documento OpenAPI e então são selecionados (veja Descoberta automática de documento OpenAPI abaixo).

Definição Manual

• Definir serviços e métodos: Quando um documento OpenAPI não foi fornecido em 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, em vez disso, 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 Custom. Quando Custom for selecionado, insira um ou mais métodos personalizados separados por uma vírgula na caixa de texto que aparece 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 habilitar o botão Avançar.

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

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

• Salvar alterações: Se habilitado, clique para salvar a configuração para esta 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 em 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 à API proxy. A caixa de seleção na coluna de 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 habilitado, clique para salvar a configuração desta etapa e navegar até Etapa 5: Resumo e confirmação.
• Descartar alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em nenhuma etapa. Uma mensagem pede para você confirmar que deseja descartar as alterações.

Etapa 4: Atribuir Perfis de Segurança e Solicitar Cabeçalhos

• Perfil(s) de Segurança: Perfis de segurança são usados 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.

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

• Cabeçalhos de solicitação: Novos cabeçalhos de solicitação podem ser adicionados ou cabeçalhos de solicitação existentes podem ser substituídos usando as seguintes configurações.

  Nota

  Por padrão, o cabeçalho da solicitação disable-hyphen-replacement está definido para true para todas as novas APIs de proxy. Depois que a API de proxy for publicada, o cabeçalho da solicitação pode ser definido como false para substituir hifens (-) com sublinhados (_) em cabeçalhos de solicitação (exceto para os cabeçalhos de solicitação Content-Type, Content-Length, Accept-Encoding, e Transfer-Encoding).

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

• 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 desta etapa e navegue até Etapa 5: Resumo e confirmação. Se a API não tiver um perfil de segurança necessário atribuído, esta opção será desabilitada.

Etapa 5: Resumo e Confirmação

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

• 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 básicas.

  • Habilitar 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: A URL da API base fornecida em Etapa 2: API existente. Para fazer alterações, clique no ícone de edição para retornar para Etapa 2: API existente.

• Serviços e métodos: Os serviços definidos em Etapa 3: Definir serviços e métodos. Para fazer alterações, clique no ícone de edição para retornar para 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 em Etapa 4: Atribuir perfis de segurança e cabeçalhos de solicitação. Para fazer alterações, clique no ícone de edição para retornar para 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 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 5: 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 proxy 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 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 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 o seu limite de assinatura de URL do proxy.
  • 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 URL do proxy, 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 URL do proxy, pois a API está acessível. Uma caixa de diálogo indica que a API está ativa. Clique em Copiar URL para copiar a URL do serviço da API (consulte URL do serviço da API):