Configuração da API Proxy no Jitterbit API Manager

Introdução

Esta página descreve como criar e configurar uma API proxy a partir da página de APIs do Jitterbit API Manager. Uma API proxy é um dos três tipos de APIs configurados através do API Manager. Para os outros dois tipos — API personalizada e serviço OData — consulte Configuração da API personalizada e Configuração do serviço OData.

Pré-requisitos

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

• Gateway de API em Nuvem: Se estiver usando o gateway de API em nuvem (hospedado pelo Jitterbit), a API existente deve ser acessível publicamente, mesmo que esteja segura. Ou seja, a API que você está tentando proxy não pode estar atrás de um firewall. Para permitir que os endereços IP do gateway de API em nuvem tenham acesso à API que está sendo proxy, consulte as informações de lista de permissão 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 API proxy permita que múltiplos serviços sejam atribuídos a uma URL única, a URL proxy base está consumindo a cota.

Criar uma nova API proxy

Quando você acessa a página APIs do Gerenciador de API, se não houver nenhuma API personalizada, serviço OData ou API proxy na organização selecionada, esta tela estará em branco.

Para criar uma nova API proxy, Novo > API Proxy:

Ao clicar em API Proxy, a tela de configuração da API proxy é aberta. Detalhes sobre como configurar uma nova API proxy estão disponíveis em Configurar uma API proxy abaixo.

Configurar uma API proxy

A tela de configuração da API 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 do serviço de uma API é a URL usada para consumir a API usando o método de autenticação configurado. As partes da URL do serviço de uma API são descritas em URL do serviço da API.

A URL do Serviço é exibida na parte superior de cada etapa:

Etapa 1: Configurações básicas

• Nome da proxy: Insira um nome para a API proxy a ser usado para fins de identificação interna. Os seguintes caracteres especiais são permitidos:

  ( ) - _

• Número da versão: Insira uma versão opcional a ser usada como parte da URL do serviço da API. Este campo permite um máximo de 48 caracteres e não permite espaços ou certos caracteres especiais. O uso de caracteres especiais além de um ponto (.) 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 usar 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 a cada tecla pressionada.

  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. O uso de caracteres especiais além de um sublinhado (_) não é recomendado. Os seguintes 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 depuração e habilitar a entrada de uma data e hora correspondentes em que o modo de depuração será desativado. O tempo máximo de ativação é de duas semanas. O modo de depuração permite rastreamento completo para cada solicitação recebida através da URL do 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

  Navegar pelos dados do evento pode se tornar difícil com grandes volumes (teste de carga, teste de pré-produção, etc.). O aumento nos dados retidos pode resultar em preocupações com espaço de armazenamento e segurança. Não recomendamos o uso do modo de depuração em um ambiente de produção.

• Tempo limite: Insira o número de segundos antes que a API atinja o tempo limite. O padrão é 30 segundos. O máximo é 180 segundos.

  Nota

  Esta configuração é independente da configuração de tempo limite da operação em Integration Studio ou Design Studio. As configurações de tempo limite da operação não são utilizadas a menos que a configuração EnableAPITimeout no arquivo de configuração do agente privado esteja habilitada.

• Somente SSL: Quando selecionado (padrão), os dados são criptografados através de SSL e HTTPS é imposto para todas as solicitações e respostas da API (recomendado).

  Quando não selecionado, os dados transmitidos através das solicitações e respostas da API não são criptografados e podem ser interceptados e visualizados por outros. Isso pode potencialmente expor informações sensíveis.

• Habilitar CORS: Selecione para habilitar Compartilhamento de Recursos de Origem Cruzada (CORS) (não recomendado). O padrão é não selecionado.

  Aviso

  Habilitar CORS faz com que operações usando o método OPTIONS sejam executadas 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 registro da API para ajudar a monitorar dados de entrada e saída e facilitar a depuração. O padrão é não selecionado.

• 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 a ser proxy.

  Nota

  Se a API fornecer um único serviço, você pode inserir a URL completa da API, incluindo o caminho do serviço. Caminhos de serviços 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 uma URL:

    

  • Enviar Arquivo: Abre uma caixa de diálogo para enviar um documento OpenAPI em formato YAML ou JSON após usar Procurar 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 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 de expansão (após 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 navegar para 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 qualquer etapa. Uma mensagem pede 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 de 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 (veja Definição manual abaixo).
• Sim: Se um documento OpenAPI foi fornecido, os serviços e métodos são descobertos automaticamente a partir do documento OpenAPI e, em seguida, são selecionados (veja Descoberta automática do 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

    Usar 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 que defina o caminho em Etapa 2: API existente.

  • Métodos: Selecione cada método a ser criado para o serviço, escolhendo entre GET, PUT, POST, DELETE e Personalizado. Quando Personalizado é selecionado, insira um ou mais métodos personalizados separados por 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 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 remover.

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

Descoberta automática de documentos OpenAPI

• Definir Serviços e Métodos: Quando um documento OpenAPI é fornecido na Etapa 2: API Existente, seus serviços são descobertos automaticamente a partir do 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 do cabeçalho pode ser usada para adicionar todos os serviços disponíveis de uma 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 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.
• Descartar Alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em qualquer etapa. Uma mensagem pede para você confirmar que deseja descartar as alterações.

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

• Perfil(is) de Segurança: Perfis de segurança são usados para restringir o acesso ao 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 tecla pressionada. Um perfil de segurança pode ser necessário para ser atribuído a fim de 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 instruções, veja Perfis 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 cabeçalhos de solicitação existentes podem ser substituídos usando as seguintes configurações.

  Nota

  Por padrão, o cabeçalho de solicitação disable-hyphen-replacement é definido como true para todas as novas APIs proxy. Uma vez que a API proxy é publicada, o cabeçalho de solicitação pode ser definido como false para substituir hífens (-) por sublinhados (_) nos 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 de solicitação.

  • Valor: Insira um valor para o cabeçalho de solicitação.

  • Substituir Entrada: Selecione para substituir um cabeçalho de solicitação existente que usa a mesma Chave. O padrão é não selecionado.

  • Atribuir Campo de Cabeçalho: Uma vez que uma Chave e um Valor tenham sido inseridos, clique para atribuir o cabeçalho de 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 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 estará desabilitada.

• Salvar Alterações: Se habilitado, clique para salvar a configuração para esta etapa e navegar para Etapa 5: Resumo e confirmação. Se a API não tiver um perfil de segurança necessário atribuído, esta opção estará desabilitada.

Etapa 5: Resumo e confirmação

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

• Descrição, Tempo limite, Apenas SSL, CORS habilitado e Registro detalhado habilitado: A descrição da API e outras configurações que estão habilitadas () ou desabilitadas (). Para fazer alterações nessas configurações, clique no ícone de edição para retornar a Passo 1: Configurações básicas.

  • Habilitar Modo de Depuração Até: Esta opção é a mesma que a descrita em Passo 1: Configurações básicas. Você pode alterar essa configuração diretamente a partir deste passo, em vez de ser necessário retornar ao primeiro passo.

• API Existente: A URL Base da API fornecida em Passo 2: API Existente. Para fazer alterações, clique no ícone de edição para retornar ao Passo 2: API Existente.

• Serviços e Métodos: Os serviços definidos em Passo 3: Definir serviços e métodos. Para fazer alterações, clique no ícone de edição para retornar ao Passo 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 Passo 4: Atribuir perfis de segurança e cabeçalhos de solicitação. Para fazer alterações, clique no ícone de edição para retornar ao Passo 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 (veja Exportando e importando APIs).

• Clonar: Cria uma cópia de uma API existente. Na cópia da API, o Nome do Proxy é precedido por Cópia de, a Raiz do Serviço é precedida por Cópia de, e a Versão é acrescida de -2. A cópia da API é imediatamente aberta em seu próprio Passo 5: Resumo e confirmação.

• Excluir: Exclui permanentemente a API e fecha a configuração. Uma caixa de diálogo solicita 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, ela também é removida do número de URLs de Proxy usadas contra o seu limite de assinatura. Se o status da API era Rascunho no momento da exclusão, o número de URLs de Proxy usadas contra o 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 utilizado. Rascunhos não contam contra o seu limite de assinatura de URLs de Proxy.
  • Publicado com Rascunho: Uma API cujo status era Publicado no momento em que Salvar como Rascunho foi utilizado. Uma API que é publicada com um rascunho conta contra o seu limite de assinatura de URLs de Proxy, pois a API é acessível, embora seu rascunho não seja.

• Salvar e Publicar: Salva a API no status Publicado. A API está ao vivo e acessível em cinco minutos. Uma API publicada conta contra o seu limite de assinatura de URLs de Proxy, pois a API é acessível. Uma caixa de diálogo indica que a API está ao vivo. Clique em Copiar URL para copiar a URL de serviço da API (veja URL de serviço da API):

  

Editar a API

Após salvar a API, você pode editá-la a partir destes locais:

• Usando visualização em bloco na página de APIs, clique em Visualizar/Editar.
• Usando visualização em lista na página de APIs, clique em Editar na coluna Ações.