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

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Como desenvolvedor que trabalha com o Apigee Edge, suas principais atividades de desenvolvimento envolvem a configuração de 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 formas mais comuns de editar configurações de proxy são:

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 terminar, 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.

Nesta seção, descrevemos como usar a IU para fazer o download de uma confusão de proxy, editá-la e fazer upload dela de volta para o 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. Na visualização "API Proxies", selecione Project > Download Revision.
  2. Na máquina local, crie um novo diretório e expanda o arquivo ZIP salvo nele.

    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. Altere para o novo diretório que você criou quando 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. Você pode usar um utilitário como o 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 incrementa o número de revisão da nova configuração de proxy quando você faz upload dela.

  7. Faça upload da nova configuração de proxy usando a interface do Edge. Na visualização API Proxies, selecione Project > Upload a New Revision.

    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 upload da nova configuração de proxy, o Edge incrementa o número de revisão e o exibe 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 interface e a API de gerenciamento na Comunidade Apigee.

Estrutura do proxy de API

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

Configuração básica Principais definições da configuração de um proxy de API. Consulte Configuração básica.
Configuração de ProxyEndpoint Configurações para a conexão HTTP de entrada (da solicitação de apps ao Apigee Edge), fluxos de solicitação e resposta e anexos de políticas. Consulte ProxyEndpoint.
Configuração do TargetEndpoint Configurações para a conexão HTTP de saída (do Apigee Edge para o serviço de back-end), fluxos de solicitação e resposta e anexos de políticas. Consulte TargetEndpoint.
Fluxos Pipelines de solicitação e resposta de ProxyEndpoint e TargetEndpoint em que as políticas podem ser anexadas. Consulte Fluxos.
Políticas Arquivos de configuração formatados em XML que estão em conformidade com os esquemas de políticas da Apigee Edge. Consulte Políticas.
Recursos Scripts, arquivos JAR e arquivos XSLT referenciados por políticas para executar a lógica personalizada. Consulte Recursos.

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:

Mostra a estrutura de diretórios em que apiproxy é a raiz. Diretamente no diretório
    apiproxy estão as políticas, proxies, recursos e diretórios de destino, bem como
    o arquivo weatherapi.xml.

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

/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

Nome Descrição Padrão Obrigatório?
APIProxy
name O nome do proxy de API, que precisa ser exclusivo na organização. Os caracteres permitidos no nome são restritos ao seguinte: A-Za-z0-9_- N/A Sim
revision O número da revisão da configuração do proxy de API. Você não precisa definir explicitamente o número de revisão, já que o Apigee Edge rastreia automaticamente a revisão atual do proxy de API. N/A Não
ConfigurationVersion A versão do esquema de configuração do proxy de API a que o proxy de API está em conformidade. Atualmente, o único valor compatível é majorVersion 4 e minorVersion 0. Essa configuração pode ser usada no futuro para permitir a evolução do formato do proxy de API. 4,0 Não
Description Uma descrição textual do proxy de API. Se fornecido, a descrição será exibida na IU de gerenciamento do Edge. N/A Não
DisplayName Um nome fácil de usar que pode ser diferente do atributo name da configuração de proxy da API. N/A Não
Policies Uma lista de políticas no diretório /policies deste proxy de API. Normalmente, esse elemento só é mostrado quando o proxy de API foi criado usando a interface de gerenciamento de borda. Essa é apenas uma configuração de "manifesto" projetada para fornecer visibilidade ao conteúdo do proxy de API. N/A Não
ProxyEndpoints Uma lista de ProxyEndpoints no diretório /proxies deste proxy de API. Normalmente, esse elemento só aparece quando o proxy de API foi criado usando a interface de gerenciamento de borda. Essa é apenas uma configuração de "manifesto" projetada para fornecer visibilidade ao conteúdo do proxy de API. N/A Não
Resources Uma lista de recursos (JavaScript, Python, Java, XLST) no diretório /resources deste proxy de API. Normalmente, você só verá esse elemento quando o proxy de API foi criado usando a interface de gerenciamento de borda. Essa é apenas uma configuração de "manifesto" projetada para fornecer visibilidade ao conteúdo do proxy de API. N/A Não
Spec Identifica a especificação OpenAPI associada ao proxy de API. O valor é definido como um URL ou um caminho no armazenamento de especificações.

Observação: o armazenamento de especificações está disponível apenas na nova experiência do Edge. Para mais informações sobre o armazenamento de especificações, consulte Como gerenciar e compartilhar especificações.
N/A Não
TargetServers Uma lista de TargetServers referenciados em quaisquer TargetEndpoints deste proxy de API. Normalmente, esse elemento só é mostrado quando o proxy de API foi criado usando a interface de gerenciamento de borda. Essa é apenas uma configuração de "manifesto" projetada para fornecer visibilidade ao conteúdo do proxy de API. N/A Não
TargetEndpoints Uma lista de TargetEndpoints no diretório /targets deste proxy de API. Normalmente, esse elemento só aparece quando o proxy de API foi criado usando a interface de gerenciamento de borda. Essa é apenas uma configuração de "manifesto" projetada para fornecer visibilidade ao conteúdo do proxy de API. N/A Não

ProxyEndpoint

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

Mostra um cliente chamando um
  serviço HTTP. A solicitação passa pelo endpoint do proxy e, em seguida, pelo endpoint de destino antes de ser
  processado pelo serviço HTTP. A resposta passa pelo endpoint desejado e, em seguida, pelo endpoint
  do proxy antes de ser retornada ao cliente.

/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

Nome Descrição Padrão Obrigatório?
ProxyEndpoint
name O nome do ProxyEndpoint. Precisa ser exclusivo na configuração do proxy de API quando vários ProxyEndpoints são definidos (o que é raro). Os caracteres permitidos no nome são restritos ao seguinte: A-Za-z0-9._\-$ %. N/A Sim
PreFlow Define as políticas no fluxo de PreFlow de uma solicitação ou resposta. N/A Sim
Flows
Define as políticas nos fluxos condicionais de uma solicitação ou resposta.
N/A Sim
PostFlow
Define as políticas no fluxo PostFlow de uma solicitação ou resposta.
N/A Sim
HTTPProxyConnection Define o endereço da rede e o caminho do URI associados ao proxy de API
BasePath

Uma string obrigatória que identifica exclusivamente o caminho do URI usado pelo Apigee Edge para rotear mensagens recebidas para o proxy de API adequado.

O BasePath é um fragmento de URI (por exemplo, /weather) anexado ao URL de base de um proxy de API (por exemplo, http://apifactory-test.apigee.net). O BasePath precisa ser exclusivo dentro do ambiente. A exclusividade é validada quando um proxy de API é gerado ou importado.

Como usar um caractere curinga em caminhos base

É possível usar um ou mais caracteres curinga "*" nos caminhos base do proxy de API. Por exemplo, um caminho base de /team/*/members permite que os clientes chamem https://[host]/team/blue/members e https://[host]/team/green/members sem que você precise criar novos proxies de API para dar suporte a novas equipes. Observe que /**/ não é compatível.

Importante: o Apigee NÃO é compatível com o uso de um caractere curinga "*" como o primeiro elemento de um caminho base. Por exemplo, isto NÃO é compatível: /*/search. Iniciar o caminho base com um "*" pode levar a erros inesperados devido à maneira como o Edge identifica caminhos válidos.

/ Sim
VirtualHost

Associa um proxy de API a URLs de base específicos para um ambiente. Um VirtualHost é uma configuração nomeada que define um ou mais URLs para um ambiente.

Os VirtualHosts definidos para um ProxyEndpoint determinam os domínios e portas em que um proxy de API é exposto e, por extensão, o URL que os aplicativos usam para invocar um proxy de API.

Por padrão, dois VirtualHosts são definidos para um ambiente: default e secure. Uma organização também pode definir domínios personalizados. Para garantir que um proxy de API esteja disponível somente por HTTPS, por exemplo, configure o VirtualHost no HTTPProxyConnection como secure.

padrão Não
Properties Um conjunto de configurações de HTTP opcionais pode ser definido como propriedades de <ProxyEndpoint>. N/A Não
FaultRules
Define como o ProxyEndpoint reage a um erro. Uma regra de falha especifica dois itens:
  • Uma condição que especifica a falha a ser processada com base na categoria, na subcategoria ou no nome da falha pré-definidos
  • Uma ou mais políticas que definem o comportamento da regra de falha da condição correspondente

Consulte Como lidar com falhas.

N/A Não
DefaultFaultRule

Processa todos os erros (sistema, transporte, mensagens ou política) que não são explicitamente processados por outra regra de falha.

Consulte Como lidar com falhas.

N/A Não
RouteRule Define o destino das mensagens de solicitação recebidas após o processamento pelo pipeline da solicitação ProxyEndpoint. Normalmente, a RouteRule aponta para uma configuração TargetEndpoint especificada, mas também pode apontar diretamente para um URL.
Name Atributo obrigatório, que fornece um nome para a RouteRule. Os caracteres permitidos no nome são restritos ao seguinte: A-Za-z0-9._\-$ %. Por exemplo, Cat2 %_ é um nome legal. N/A Sim
Condition Uma instrução condicional opcional usada para roteamento dinâmico no ambiente de execução. As RouteRules condicionais são úteis, por exemplo, para ativar o roteamento baseado em conteúdo e oferecer suporte ao controle de versão de back-end. N/A Não
TargetEndpoint

Uma string opcional que identifica uma configuração de TargetEndpoint. Um TargetEndpoint é qualquer TargetEndpoint definido no mesmo proxy de API no diretório /targets.

Ao nomear um TargetEndpoint, você indica onde as mensagens de solicitação devem ser encaminhadas após o processamento pelo pipeline de solicitação ProxyEndpoint. Essa é uma configuração opcional.

Um ProxyEndpoint pode chamar um URL diretamente. Por exemplo, um recurso JavaScript ou Java, trabalhando no papel de um cliente HTTP, pode executar a função básica de um TargetEndpoint, que é encaminhar solicitações para um serviço de back-end.

N/A Não
URL Uma string opcional que define um endereço de rede de saída chamado pelo ProxyEndpoint, ignorando todas as configurações de TargetEndpoint que podem ser armazenadas em /targets N/A Não

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 a Referência de condições e a 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

Mostra um cliente chamando um
  serviço HTTP. A solicitação passa pelo endpoint do proxy e, em seguida, pelo endpoint de destino antes de ser
  processado pelo serviço HTTP. A resposta passa pelo endpoint desejado e, em seguida, pelo endpoint
  do proxy antes de ser retornada ao cliente.

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 para 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 para um script Node.js hospedado na borda

Configure apenas um deles em um TargetEndpoint.

Nome Descrição Padrão Obrigatório?
TargetEndpoint
name O nome do TargetEndpoint, que precisa ser exclusivo na configuração do proxy de API. O nome do TargetEndPoint é usado na RouteRule ProxyEndpoint para direcionar solicitações de processamento de saída. Os caracteres permitidos no nome são restritos ao seguinte: A-Za-z0-9._\-$ %. N/A Sim
PreFlow Define as políticas no fluxo de PreFlow de uma solicitação ou resposta. N/A Sim
Flows
Define as políticas nos fluxos condicionais de uma solicitação ou resposta.
N/A Sim
PostFlow
Define as políticas no fluxo PostFlow de uma solicitação ou resposta.
N/A Sim
HTTPTargetConnection

Com seus elementos filhos, especifica um alcance de recurso de back-end por HTTP.

Se você usa HTTPTargetConnection, não configure outros tipos de conexões de destino (ScriptTarget ou LocalTargetConnection).

URL Define o endereço de rede do serviço de back-end para que o TargetEndpoint encaminha mensagens de solicitação. N/A Não
LoadBalancer

Define uma ou mais configurações de TargetServer nomeado. As configurações do TargetServer nomeado podem ser usadas para balanceamento de carga definindo duas ou mais conexões de configuração de endpoints.

Também é possível usar TargetServers para separar as configurações de proxy da API dos URLs de endpoints do serviço de back-end concreto.

Consulte Balanceamento de carga entre servidores de back-end.

N/A Não
Properties Um conjunto de configurações de HTTP opcionais pode ser definido como propriedades de <TargetEndpoint>. N/A Não
SSLInfo Opcionalmente, defina configurações TLS/SSL em um TargetEndpoint para controlar a conexão TLS/SSL entre o proxy de API e o serviço de destino. Consulte Configuração do TLS/SSL TargetEndpoint. N/A Não
LocalTargetConnection Com seus elementos filhos, especifica um recurso a ser alcançado localmente, ignorando características da rede, como balanceamento de carga e processadores de mensagens.

Para especificar o recurso de destino, inclua o elemento filho APIProxy (com o elemento ProxyEndpoint) ou o elemento filho Path.

Para mais informações, consulte Como clonar proxies de API juntos.

Se você usa LocalTargetConnection, não configure outros tipos de conexões de destino (HTTPTargetConnection ou ScriptTarget).

APIProxy Especifica o nome de um proxy de API a ser usado como destino para solicitações. O proxy de destino precisa estar na mesma organização e no mesmo ambiente que a solicitação de envio de proxy. Essa é uma alternativa ao uso do elemento Path. N/A Não
ProxyEndpoint Usado com APIProxy para especificar o nome do ProxyEndpoint do proxy de destino. N/A Não
Path Especifica o caminho do endpoint de um proxy de API a ser usado como destino para solicitações. O proxy de destino precisa estar na mesma organização e no mesmo ambiente que as solicitações de envio de proxy. Essa é uma alternativa ao uso da APIProxy. N/A Não
FaultRules
Define como o TargetEndpoint reage a um erro. Uma regra de falha especifica dois itens:
  • Uma condição que especifica a falha a ser processada com base na categoria, na subcategoria ou no nome da falha pré-definidos
  • Uma ou mais políticas que definem o comportamento da regra de falha da condição correspondente

Consulte Como lidar com falhas.

N/A Não
DefaultFaultRule

Processa todos os erros (sistema, transporte, mensagens ou política) que não são explicitamente processados por outra FaultRule.

Consulte Como lidar com falhas.

N/A Não
ScriptTarget
ResourceURL

Define o tipo de recurso (nó) e o nome do script principal em Node.js que implementa a funcionalidade TargetEndpoint.

<ResourceURL>node://server.js</ResourceURL>

O script precisa ser incluído nos arquivos de recursos do proxy de API. Consulte Como adicionar o Node.js a um proxy de API atual.

Se você usar ScriptTarget, não configure outros tipos de conexões de destino (HTTPTargetConnection ou LocalTargetConnection).

N/A Sim
EnvironmentVariable

Como opção, transmita as variáveis de ambiente para o script Node.js principal.

Consulte Noções básicas sobre o suporte do Edge para módulos Node.js.

N/A Não
Arguments

Como opção, transmita os argumentos para o script Node.js principal.

Consulte Noções básicas sobre o suporte do Edge para módulos Node.js.

N/A Não

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

Nome Descrição Padrão Obrigatório?
SSLInfo
Enabled Indica se o TLS/SSL está ativado para o endpoint. O valor padrão é true se <URL> especificar o protocolo HTTPS e false se <URL> especificar HTTP. verdadeiro se <URL> especificar HTTPS. Não
TrustStore Um keystore com certificados de servidor confiáveis. N/A Não
ClientAuthEnabled Uma configuração que ativa a autenticação do cliente de saída (TLS/SSL bidirecional) false Não
KeyStore Um keystore com chaves privadas usadas para autenticação do cliente de saída N/A Sim (se ClientAuthEnabled for verdadeiro)
KeyAlias O alias da chave privada usada para autenticação do cliente de saída N/A Sim (se ClientAuthEnabled for verdadeiro)
Ciphers

Criptografias compatíveis para TLS/SSL de saída. Se nenhuma criptografia for especificada, todas as criptografias disponíveis para o JVM serão permitidas.

Para restringir as criptografias, adicione os elementos a seguir listando as criptografias compatíveis:

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>    
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>
N/A Não
Protocols

Protocolos compatíveis com TLS/SSL de saída. Se nenhum protocolo for especificado, todos os protocolos disponíveis para JVM serão permitidos.

Para restringir protocolos, adicione os elementos a seguir listando os protocolos compatíveis:

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>
N/A Não
CommonName

Se especificado, um valor em relação ao qual o nome comum do certificado de destino é validado. Este valor só é válido para as configurações TargetEndpoint e TargetServer. Não é válido para configurações do VirtualHost.

Por padrão, o valor especificado é correspondido exatamente ao nome comum do certificado de destino. Por exemplo, usar *.myhost.com como o valor de <CommonName> só vai corresponder e validar o nome do host de destino se o valor exato *.myhost.com for especificado como o nome comum no certificado de destino.

Opcionalmente, a Apigee pode fazer a correspondência com caracteres curinga usando o atributo wildcardMatch.

Por exemplo, um nome comum especificado como abc.myhost.com em um certificado de destino será correspondido e validado se o elemento <CommonName> for especificado da seguinte maneira:

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

N/A Não

TargetEndpoint de amostra com 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, considere o caso de expiração do certificado TLS/SSL ou uma alteração na configuração do sistema exigirá que o certificado seja atualizado. Em uma instalação do Edge para nuvem privada, ao configurar o TLS/SSL usando valores estáticos ou variáveis de fluxo, há uma chance de 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

Nome Descrição Padrão Obrigatório?
Policy
name

O nome interno da política. Os caracteres que podem ser usados no nome são restritos a: A-Za-z0-9._\-$ %. No entanto, a interface de gerenciamento de borda aplica outras restrições, como a remoção automática de caracteres que não são alfanuméricos.

Se quiser, use o elemento <DisplayName> para rotular a política no editor de proxy da interface de gerenciamento com um nome diferente em linguagem natural.

N/A Sim
enabled

Defina como true para aplicar a política.

Defina como false para "desativar" a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.

verdadeiro Não
continueOnError

Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas.

Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.

false Não
async

Observação: esse atributo não faz a política ser executada de forma assíncrona. Na maioria dos casos, deixe isso com o false padrão.

Quando definida como true, a execução da política é descarregada para uma linha de execução diferente, deixando a linha de execução principal livre para processar solicitações extras. Após a conclusão do processamento off-line, a linha de execução principal volta e termina o processamento do fluxo de mensagens. Em alguns casos, a configuração assíncrona de true melhora o desempenho do proxy de API. No entanto, usar o recurso assíncrono pode prejudicar o desempenho devido à alta alternância de linhas de execução.

Para usar o comportamento assíncrono nos proxies de API, consulte o modelo de objeto JavaScript.

false Não

Anexo da política

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

mostra um cliente chamando um serviço HTTP. A solicitação encontra o
  ProxyEndpoint e o TargetEndpoint, que contêm etapas que acionam políticas. Depois que o
  serviço HTTP retorna a resposta, ela é processada pelo TargetEndpoint e, em seguida, pelo
  ProxyEndpoing antes de ser retornada ao cliente. Assim como na solicitação, a resposta é processada
  pelas políticas nas etapas.

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

Nome Descrição Padrão Obrigatório?
Step
Name O nome da política a ser executada por esta definição de etapa. N/A Sim
Condition Uma declaração condicional que determina se a política é aplicada ou não. Se uma política tiver uma condição associada, ela será executada somente se a instrução condicional for avaliada como verdadeira. N/A Não

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 um vídeo rápido com instruções

Vídeo: veja este vídeo curto sobre como usar o registro de mensagens no PostClientFlow.

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

Nome Descrição Padrão Obrigatório?
Flow Um pipeline de processamento de solicitação ou resposta definido por um ProxyEndpoint ou TargetEndpoint
Name O nome exclusivo do fluxo. N/A Sim
Condition Uma declaração condicional que avalia uma ou mais variáveis para avaliar como verdadeiro ou falso. Todos os fluxos diferentes dos tipos de PreFlow e PostFlow pré-definidos precisam definir uma condição para a execução. N/A Sim
Request O pipeline associado ao processamento da mensagem de solicitação N/A Não
Response O pipeline associado ao processamento da mensagem de resposta N/A Não

Processamento de etapas

A ordem sequencial de 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 seção "Scripts" do editor de proxy de API na interface 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.