Referência de configuração de proxy da API

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

Como desenvolvedor que trabalha com o Apigee Edge, suas principais atividades de desenvolvimento envolvem configurar proxies de API que funcionam como proxies para APIs ou serviços de back-end; Este documento é uma referência de todos os elementos de configuração disponíveis quando você cria proxies de API.

Se você estiver aprendendo a criar proxies de API, é recomendável começar com o tópico Criar um proxy de API simples.

As maneiras mais comuns de editar configurações de proxy são:

• Uso do editor XML na interface do Edge
• Faça o download da configuração e edite-a localmente, conforme descrito em Desenvolvimento local de configurações de proxy.

Desenvolvimento local de configurações de proxy

É possível fazer o download das configurações de proxy para poder editá-las em uma máquina local. Quando e pronto, faça upload dos resultados para o Edge. Essa abordagem permite integrar as configurações de proxy ao controle de origem, ao controle de versão e a outros fluxos de trabalho compartilhados. Além disso, ao trabalhar em uma configuração de proxy localmente, é possível usar seu próprio editor de XML e ferramentas de validação.

Esta seção descreve como usar a interface para fazer download de uma confuração de proxy existente, editá-la, e depois fazer upload dele no Edge para implantação. Também é possível usar o apigeetool para fazer o download e implantar uma nova configuração de proxy (usando os comandos fetchproxy e deployproxy, respectivamente).

Para editar uma configuração de proxy localmente usando a IU:

1. Faça o download da configuração de proxy atual na interface do Edge. (Nos proxies das APIs selecione Projeto > Fazer o download da revisão.
2. Na máquina local, crie um novo diretório e expanda o arquivo ZIP baixado.

   Para expandir o arquivo ZIP, é possível usar um utilitário como unzip, como mostra o exemplo a seguir:

   mkdir myappdir
   unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir

   O conteúdo expandido do arquivo ZIP precisa ser semelhante à estrutura descrita na estrutura de proxy de API.

3. Edite os arquivos de origem, conforme necessário. Para uma descrição dos arquivos de origem em uma configuração de proxy, consulte Arquivos de configuração e estrutura de diretório de um proxy de API.

   Por exemplo, para ativar o monitoramento de integridade no proxy da API, edite o arquivo de configuração TargetEndpoint no diretório /apiproxy/targets/. O arquivo padrão nesse diretório é default.xml, embora possa haver arquivos com nomes diferentes se você usar destinos condicionais.

   Nesse caso, se o arquivo de configuração TargetEndpoint e o diretório dele não existirem, crie-os.

4. Após editar os arquivos de configuração de proxy, salve as alterações.
5. Mude para o novo diretório criado quando você expandiu os arquivos ZIP (a raiz dos arquivos de configuração expandidos).

   Por exemplo, se você expandiu os arquivos para o diretório /myappdir, mude para esse diretório, conforme mostrado no exemplo a seguir:

   cd myappdir

   Altere para esse diretório antes de arquivar novamente os arquivos de configuração de proxy, porque não quer que o diretório /myappdir seja incluído no arquivo ZIP. O diretório de nível superior no arquivo ZIP precisa ser /apiproxy.

6. Arquive novamente os arquivos de configuração de proxy, incluindo os novos ou alterados. É possível usar um utilitário como zip, como mostra o exemplo a seguir:

   zip my-new-proxy.zip -r .

   O diretório de nível superior no arquivo ZIP precisa ser /apiproxy.

   Não há requisitos especiais para o nome do arquivo ZIP. Por exemplo, você não precisa incrementar o número de revisão nem especificar a data no nome do arquivo, mas fazer isso pode ser útil para depuração ou controle de origem.

   O Edge aumenta o número de revisão da nova configuração de proxy no momento do upload. reimplantá-lo.

7. Faça upload da nova configuração de proxy usando a interface do Edge. Na coluna Proxies da API, selecione Projeto > Fazer upload de uma nova revisão.

   Se você receber um erro como Bundle is invalid. Empty bundle., verifique se o diretório de nível superior do seu arquivo ZIP é /apiproxy. Se não for, arquive novamente os arquivos de configuração de proxy na raiz do diretório expandido.

   Depois de fazer o upload da nova configuração de proxy, o Edge incrementa o número de revisão e o exibirá na visualização Resumo da revisão.

   O Edge não implanta a nova revisão depois que você faz upload dela com a interface.

8. Implante sua nova revisão.

Para mais informações, consulte Tutorial: como fazer o download de um proxy usando a IU e a API de gerenciamento no Comunidade da Apigee.

Estrutura do proxy de API

Um proxy de API consiste na configuração a seguir:

Estrutura e conteúdo do diretório de proxy de API

Os componentes na tabela acima são definidos por arquivos de configuração na estrutura do diretório a seguir:

Arquivos de configuração e estruturas de diretório de um proxy de API

Nesta seção, explicamos os arquivos de configuração e a estrutura de diretórios de um proxy de API.

• Configuração básica
• ProxyEndpoint
• TargetEndpoint
  • Configuração de TargetEndpoint TLS/SSL
• Políticas
• Fluxos
• Recursos

Configuração básica

/apiproxy/weatherapi.xml

A configuração básica de um proxy de API, que define o nome do proxy de API. O nome precisa ser exclusivo na organização.

Exemplo de configuração:

<APIProxy name="weatherapi">
</APIProxy>

Elementos de configuração básica

ProxyEndpoint

A imagem a seguir mostra o fluxo de solicitação/resposta:

/apiproxy/proxies/default.xml

A configuração do ProxyEndpoint define a interface de entrada (do cliente) para um proxy de API. Ao configurar um ProxyEndpoint, você define uma configuração de rede que define como os aplicativos clientes ("apps") precisam invocar a API com proxy.

A seguinte amostra de ProxyEndpoint seria armazenada em /apiproxy/proxies:

<ProxyEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPProxyConnection>
    <BasePath>/weather</BasePath>
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Os elementos de configuração necessários em um ProxyEndpoint básico são:

Elementos de configuração do ProxyEndpoint

Como configurar as RouteRules

Um TargetEndpoint é chamado de um arquivo de configuração em /apiproxy/targets para onde a RouteRule encaminha uma solicitação após ser processada pelo ProxyEndpoint.

Por exemplo, a RouteRule a seguir se refere à configuração /apiproxy/targets/myTarget.xml:

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

Invocação direta de URL

Um ProxyEndpoint também pode invocar diretamente um serviço de back-end. A invocação direta de URL ignora qualquer configuração do TargetEndpoints nomeada em /apiproxy/targets. Por isso, o TargetEndpoint é uma configuração opcional de proxy de API, embora, na prática, a invocação direta do ProxyEndpoint não seja recomendada.

Por exemplo, a RouteRule a seguir faz uma chamada HTTP para http://api.mycompany.com/v2.

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL> 
</RouteRule>

Rotas condicionais

É possível encadear rotas para oferecer compatibilidade com o roteamento dinâmico no ambiente de execução. As solicitações de entrada podem ser encaminhadas para configurações nomeadas do TargetEndpoint, diretamente para URLs ou uma combinação dos dois, com base em cabeçalhos HTTP, conteúdo de mensagens, parâmetros de consulta ou informações contextuais, como hora do dia, local etc.

As RouteRules condicionais funcionam como outras instruções condicionais no Apigee Edge. Consulte Referência de condições e Referência de variáveis.

Por exemplo, a combinação da RouteRule a seguir avalia primeiro a solicitação de entrada para verificar o valor de um cabeçalho HTTP. Se o cabeçalho HTTP routeTo tiver o valor TargetEndpoint1, a solicitação será encaminhada para o TargetEndpoint chamado TargetEndpoint1. Caso contrário, a solicitação de entrada será encaminhada para http://api.mycompany.com/v2.

<RouteRule name="MyRoute">
  <Condition>request.header.routeTo = "TargetEndpoint1"</Condition>
  <TargetEndpoint>TargetEndpoint1</TargetEndpoint>
</RouteRule>
<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

Rotas nulas

Uma RouteRule nula pode ser definida para oferecer suporte a cenários em que a mensagem de solicitação não precisa ser encaminhada para o TargetEndpoint. Isso é útil quando o ProxyEndpoint executa todo o processamento necessário, por exemplo, usando o JavaScript para chamar um serviço externo ou recuperando dados de uma pesquisa para o armazenamento de chave/valor dos serviços de API.

Por exemplo, o seguinte define uma rota nula:

<RouteRule name="GoNowhere"/>

Rotas nulas condicionais podem ser úteis. No exemplo a seguir, uma rota nula está configurada para ser executada quando um cabeçalho HTTP request.header.X-DoNothing tem um valor diferente de null.

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

Lembre-se de que RouteRules podem ser encadeadas. Portanto, uma rota nula condicional normalmente seria um componente de um conjunto de RouteRules projetadas para oferecer suporte ao encaminhamento condicional.

O uso prático de uma rota nula condicional seria como suporte ao armazenamento em cache. Usando o valor da variável definido pela política de cache, é possível configurar um proxy de API para executar a rota nula quando uma entrada é veiculada do cache.

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

Um TargetEndpoint é o equivalente de saída de um ProxyEndpoint. Um TargetEndpoint funciona como o cliente de um serviço de back-end ou API: envia solicitações e recebe respostas.

Um proxy de API não precisa ter TargetEndpoints. É possível configurar ProxyEndpoints para chamar URLs diretamente. Um proxy de API sem TargetEndpoints geralmente contém um ProxyEndpoint que chama diretamente um serviço de back-end ou que está configurado para chamar um serviço usando Java ou JavaScript.

Configuração do TargetEndpoint

/targets/default.xml

O TargetEndpoint define a conexão de saída do Apigee Edge com outro serviço ou recurso.

Veja um exemplo de configuração do TargetEndpoint:

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

Elementos de configuração do TargetEndpoint

Um TargetEndpoint pode chamar um destino de uma das seguintes maneiras:

• HTTPTargetConnection para chamadas HTTP(S)
• LocalTargetConnection para encadeamento local de proxy para proxy
• ScriptTarget para chamadas a uma rede hospedada no Edge Script em Node.js

Configure apenas um deles em um TargetEndpoint.

Configuração de TargetEndpoint TLS/SSL

O TargetEndpoints geralmente precisa gerenciar conexões HTTPS com a infraestrutura de back-end heterogênea. Por isso, várias configurações de configuração TLS/SSL são compatíveis.

Elementos de configuração do TargetEndpoint TLS/SSL

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>    
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

Exemplo de TargetEndpoint com a autenticação de cliente de saída ativada

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

Para instruções detalhadas, consulte Como configurar o TLS da borda para o back-end (nuvem e nuvem privada).

Como usar variáveis de fluxo para definir valores de TLS/SSL dinamicamente

Também é possível definir detalhes de TLS/SSL dinamicamente para oferecer suporte aos requisitos de ambiente de execução flexível. Por exemplo, se o proxy se conectar a dois destinos potencialmente diferentes (um destino de teste e um destino de produção), será possível fazer com que o proxy de API detecte de forma programática qual ambiente está chamando e defina referências ao keystore e ao truststore apropriados dinamicamente. O artigo da comunidade do Apigee a seguir explica esse cenário com mais detalhes e fornece exemplos de proxy de API implantáveis: https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html.

No exemplo a seguir de como a tag <SSLInfo> seria definida em uma configuração de TargetEndpoint, os valores podem ser fornecidos no ambiente de execução, por exemplo, por uma chamada de Java, uma política JavaScript ou uma política "Atribuir mensagem". Use as variáveis de mensagem que contenham os valores que você quer definir.

As variáveis são permitidas somente nos elementos a seguir.

<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

Como usar referências para definir valores de TLS/SSL dinamicamente

Ao configurar um TargetEndpoint que usa HTTPS, é preciso considerar o caso em que o O certificado TLS/SSL expira ou uma alteração na configuração do sistema exige que você o atualize. Em um Edge para instalação de nuvem privada, ao configurar TLS/SSL usando valores estáticos ou usando variáveis de fluxo, é possível que você precise reiniciar os processadores de mensagens.

Para saber mais, consulte Atualizar um certificado TLS.

No entanto, você tem a opção de configurar o TargetEndpoint para usar uma referência ao keystore ou truststore. A vantagem de usar uma referência é poder atualizá-la para apontar para um keystore ou truststore diferente para atualizar o certificado TLS/SSL sem precisar reiniciar o processador de mensagens.

Por exemplo, abaixo é mostrado um TargetEndpoint que usa uma referência ao keystore:

<SSLInfo> 
    <Enabled>true</Enabled> 
    <ClientAuthEnabled>false</ClientAuthEnabled> 
    <KeyStore>ref://keystoreref</KeyStore> 
    <KeyAlias>myKeyAlias</KeyAlias> 
</SSLInfo>

Use a seguinte chamada POST API para criar a referência chamada keystoreref:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

A referência especifica o nome e o tipo do keystore.

Use a chamada GET API a seguir para visualizar a referência:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

Posteriormente, para alterar a referência e apontar para um keystore diferente, verifique se o alias tem o mesmo nome e use a seguinte chamada PUT:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

TargetEndpoint com balanceamento de carga de destino

O TargetEndpoints é compatível com balanceamento de carga em vários TargetServers nomeados usando três algoritmos de balanceamento de carga.

Para instruções detalhadas, consulte Balanceamento de carga entre servidores de back-end.

Políticas

O diretório /policies em um proxy de API contém todas as políticas disponíveis para serem anexadas aos fluxos no proxy de API.

Elementos de configuração da política

Anexo da política

A imagem a seguir mostra a sequência de execução do fluxo da API:

Como mostrado acima:

As políticas são anexadas como etapas de processamento para Fluxos. O nome da política é usado para referenciar a política a ser aplicada como uma etapa de processamento. Este é o formato de um anexo de política:

<Step><Name>MyPolicy</Name></Step>

As políticas são aplicadas na ordem em que são anexadas a um fluxo. Exemplo:

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

Elementos de configuração do anexo de política

Fluxos

ProxyEndpoint e TargetEndpoint definem um pipeline para processamento de mensagens de solicitação e resposta. Um pipeline de processamento consiste em um fluxo de solicitação e um fluxo de resposta. Cada fluxo de solicitação e de resposta é subdividido em um PreFlow, um ou mais fluxos "condicionais" ou "nomeados" opcionais e um PostFlow.

• PreFlow: sempre executado. Executado antes de qualquer fluxo condicional.
• PostFlow: sempre é executado. Executado após qualquer fluxo condicional.

Além disso, é possível adicionar um PostClientFlow ao ProxyEndpoint, que é executado depois que a resposta é retornada ao aplicativo de cliente solicitante. Somente a política MessageLogging e a Extensão do Google Stackdriver Logging podem ser anexadas a esse fluxo. O PostClientFlow reduz a latência do proxy de API e disponibiliza informações para a geração de registros que não são calculadas até que a resposta seja retornada ao cliente, como client.sent.start.timestamp e client.sent.end.timestamp O fluxo de trabalho é usado principalmente para medir o intervalo de tempo entre os carimbos de data/hora de início e término da mensagem de resposta.

Assista a um vídeo de instruções rápido

Veja um exemplo de PostClientFlow com política de registro de mensagens anexada.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

O pipeline de processamento do proxy de API executa fluxos na seguinte sequência:

Solicitar pipeline:

1. PreFlow da solicitação de proxy
2. Fluxos condicionais de solicitação de proxy (opcional)
3. PostFlow de solicitação de proxy
4. PreFlow da solicitação de destino
5. Fluxos condicionais de solicitação de destino (opcional)
6. PostFlow da solicitação de destino

Pipeline de resposta:

1. PreFlow de resposta de destino
2. Fluxos condicionais de resposta desejada (opcional)
3. PostFlow de resposta de destino
4. PreFlow de resposta do proxy
5. Fluxos condicionais de resposta de proxy (opcional)
6. PostFlow de resposta de proxy
7. Resposta de PostClientFlow (opcional)

Somente fluxos com anexos de política precisam ser configurados nas configurações de ProxyEndpoint ou TargetEndpoint. O PreFlow e o PostFlow só precisam ser especificados em uma configuração de ProxyEndpoint ou TargetEndpoint quando uma política precisa ser aplicada durante o processamento do PreFlow ou PostFlow.

Ao contrário dos fluxos condicionais, a ordem dos elementos de PreFlow e PostFlow não é importante. O proxy de API sempre será executado no ponto adequado do pipeline, independentemente de onde eles aparecem na configuração do endpoint.

Fluxos condicionais

ProxyEndpoints e TargetEndpoints são compatíveis com um número ilimitado de fluxos condicionais (também conhecidos como "fluxos nomeados").

O proxy de API testa a condição especificada no fluxo condicional e, se a condição for atendida, as etapas de processamento no fluxo condicional são executadas pelo proxy de API. Se a condição não for atendida, as etapas de processamento no fluxo condicional serão ignoradas. Os fluxos condicionais são avaliados na ordem definida no proxy de API e no primeiro local em que a condição é atendida.

Ao definir fluxos condicionais, você ganha a capacidade de aplicar etapas de processamento em um proxy de API com base em:

• URI da solicitação
• Verbo HTTP (GET/PUT/POST/DELETE)
• Valor de um parâmetro de consulta, cabeçalho e parâmetro de formulário
• Muitos outros tipos de condições

Por exemplo, o fluxo condicional a seguir especifica que ele é executado somente quando o caminho do recurso da solicitação é /accesstoken. Qualquer solicitação de entrada com o caminho /accesstoken faz com que esse fluxo seja executado com todas as políticas anexadas ao fluxo. Se o caminho da solicitação não incluir o sufixo /accesstoken, o fluxo não será executado (embora outro fluxo condicional possa ser).

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request> 
  </Flow>
</Flows>   

Elementos da configuração de fluxo

Processamento de etapas

A ordem sequencial dos fluxos condicionais é aplicada pelo Apigee Edge. Os fluxos condicionais são executados de cima para baixo. O primeiro fluxo condicional com condição avaliada como true é executado e apenas um fluxo condicional é executado.

Por exemplo, na configuração de fluxo a seguir, qualquer solicitação de entrada que não inclua o sufixo de caminho /first ou /second fará com que o ThirdFlow seja executado, aplicando a política chamada Return404.

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

Recursos

"Recursos" (arquivos de recursos para uso em proxies de API) são scripts, código e transformações XSL que podem ser anexadas a fluxos usando políticas. Eles aparecem na lista "Scripts" da API de proxy na IU de gerenciamento.

Consulte Arquivos de recursos para conhecer os tipos de recursos compatíveis.

Os recursos podem ser armazenados em um proxy de API, um ambiente ou uma organização. Em cada caso, um recurso é referenciado pelo nome em uma política. Os serviços da API resolvem o nome mudando do proxy de API para o ambiente, até o nível da organização.

Um recurso armazenado no nível da organização pode ser referenciado por políticas em qualquer ambiente. Um recurso armazenado no nível do ambiente pode ser referenciado por políticas nesse ambiente. Um recurso armazenado no nível do proxy de API só pode ser referenciado por políticas nesse proxy de API.