Esta página foi traduzida pela API Cloud Translation.

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

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Como um desenvolvedor que trabalha com o Apigee, 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 Como criar um proxy de API simples.

Edite a configuração do proxy da API usando um dos seguintes métodos:

Use a IU ou a API da Apigee.
Faça o download do pacote de configuração de proxy da API, edite-o manualmente e faça o upload da nova configuração para a Apigee, conforme descrito em Como fazer o download e upload de um pacote de configuração de proxy da API.

Estrutura de diretórios da configuração de proxy da API

Veja abaixo a estrutura de diretório de configuração de proxy da API:

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.

Uma configuração de proxy de API consiste no seguinte conteúdo:

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

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. Não é necessário definir explicitamente o número de revisão, já que o Apigee 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 inserida, a descrição será exibida na IU do Apigee.	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, você só verá esse elemento quando o proxy de API foi criado usando a IU do Apigee. 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 endpoints de proxy no diretório `/proxies` deste proxy de API. Normalmente, você só verá esse elemento quando o proxy de API foi criado usando a IU do Apigee. 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 IU do Apigee. 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.	N/A	Não
`TargetServers`	Uma lista de servidores de destino referenciados em quaisquer TargetEndpoints deste proxy de API. Normalmente, você só verá esse elemento quando o proxy de API foi criado usando o Apigee. 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 endpoints de destino no diretório `/targets` deste proxy de API. Normalmente, você só verá esse elemento quando o proxy de API foi criado usando a IU do Apigee. 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 endpoint de proxy, 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>
    <Properties/>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

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

Elementos de configuração do ProxyEndpoint

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

ProxyEndpoint

name O nome do endpoint de proxy. Precisa ser exclusivo na configuração do proxy de API quando vários endpoints de proxy 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 de PostFlow de uma solicitação ou resposta.

N/A

Sim

HTTPProxyConnection Define o endereço de rede e o caminho do URI associados ao proxy de API.

BasePath

Uma string obrigatória que identifica exclusivamente o caminho do URI usado pela Apigee para encaminhar mensagens recebidas ao 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 causar erros inesperados devido à maneira como o Apigee identifica caminhos válidos.

Sim

Properties

Um conjunto de configurações de HTTP opcionais pode ser definido como propriedades de <ProxyEndpoint>.

Use a propriedade request.queryparams.ignore.content.type.charset para informar ao proxy para ignorar o parâmetro charset do cabeçalho Content-Type ao processar o URL de solicitação. Por exemplo:

<Property name= \
"request.queryparams.ignore.content.type.charset">true</>

A tabela a seguir mostra um exemplo de saída, dependendo da configuração da propriedade charset e da presença do parâmetro charset do cabeçalho Content-Type.

Configuração da propriedade	Valor do cabeçalho	Exemplo de saída
`charset=false`	Parâmetro `charset` não definido	john.doe+test@gmail.com
`charset=false`	`charset=utf-8`	john.doe test@gmail.com
`charset=true` e nenhum parâmetro `charset` no cabeçalho.	Parâmetro `charset` não definido	john.doe+test@gmail.com
`charset=true`	Parâmetro `charset=utf-8` definido	john.doe+test@gmail.com

N/A

Não

FaultRules

Define como o endpoint de proxy 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, o RouteRule aponta para um endpoint de destino nomeado, um IntegrationEndpoint ou 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 endpoint de destino nomeado é qualquer TargetEndpoint definido no mesmo proxy de API no diretório /targets.

Ao nomear um endpoint de destino, 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 endpoint de proxy 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 endpoint de proxy, ignorando todas as configurações de TargetEndpoint que podem ser armazenadas em /targets N/A Não

Como configurar as RouteRules

Um endpoint de destino nomeado se refere a um arquivo de configuração em /apiproxy/targets para onde a RouteRule encaminha uma solicitação após ser processada pelo endpoint do proxy.

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 endpoint de proxy também pode invocar diretamente um serviço de back-end. A invocação direta de URL ignora qualquer configuração do TargetEndpoint 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 endpoint de proxy 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. Consulte a Referência de condições e Referência de variáveis de fluxo.

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 endpoint de destino 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 endpoint de destino. Isso é útil quando o endpoint de proxy executa todo o processamento necessário, por exemplo, usando JavaScript para chamar um serviço externo ou recuperar dados de uma pesquisa para o armazenamento de chave/valor da Apigee.

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 endpoint de destino é o equivalente de saída de um endpoint de proxy. Um endpoint de destino 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 endpoints de destino. É possível configurar endpoints de destino para chamar URLs diretamente. Um proxy de API sem endpoints de destino geralmente contém um endpoint de destino 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 endpoint de destino define a conexão de saída do Apigee 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/>
    <Authentication/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

Elementos de configuração do TargetEndpoint

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

HTTPTargetConnection para chamadas HTTP ou HTTPS
LocalTargetConnection para encadeamento local de proxy para proxy

Configure apenas um deles em um endpoint de destino.

Nome	Descrição	Padrão	Obrigatório?
`TargetEndpoint`
`name`	O nome do endpoint de destino, que precisa ser exclusivo na configuração do proxy de API. O nome do endpoint de destino é 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 de 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). Observação: o elemento `<LocalTargetConnection>` é compatível com o recurso de substituição de strings dinâmico chamado modelo de mensagem. É possível usar a página`<Authentication>` elemento filho para fazer chamadas autenticadas a serviços do Google ou a serviços personalizados em execução em determinados produtos do Google Cloud, comoCloud Functions eCloud Run. O uso do elemento `<Authentication>` requer etapas de configuração e implantação descritas em Como usar a autenticação do Google. Com a configuração adequada, a política cria um token de autenticação para você e o adiciona à solicitação de serviço. Consulte também Uso de elementos `<Authentication>`.
`URL`	Define o endereço de rede do serviço de back-end para que o endpoint de destino 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 servidores de destino para separar as configurações de proxy da API dos URLs de endpoints do serviço de back-end concreto.	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 endpoint de destino 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. Observação: o elemento `<SSLInfo>` é compatível com o recurso de substituição de strings dinâmico chamado modelo de mensagem.	N/A	Não
`LocalTargetConnection`	Com os elementos filhos, especifica um recurso a ser alcançado localmente, ignorando as 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 endpoint de proxy 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 endpoint de destino 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

Uso do elemento `<Authentication>`

O uso do elemento <Authentication> em <TargetEndpoint> é idêntico ao uso do elemento <Authentication> na política ServiceCallout. Tanto na <TargetEndpoint> quanto na ServiceCall, <Authentication> é um subelemento de <HttpTargetConnection>. Para mais detalhes, veja Elemento de autenticação na Referência de política do ServiceCallout.

Referência de erro do elemento `<Authentication>`

Se você estiver usando o elemento <Authentication>, poderá encontrar possíveis mensagens de erro e dicas de solução de problemas para erros de implantação e tempo de execução na seção Erros da documentação da política de ServiceCallout.

Exemplos de elementos `<Authentication>`

O exemplo a seguir mostra como chamar um serviço implantado no Cloud Run como destino usando o elemento Authentication para gerar um token do OpenID Connect necessário para autenticar a chamada:

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
      <Properties/>
      <URL>https://cloudrun-hostname.a.run.app/test</URL>
      <Authentication>
          <GoogleIDToken>
             <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
          </GoogleIDToken>
     </Authentication>
  </HTTPTargetConnection>
</TargetEndpoint>

O exemplo a seguir mostra como chamar um TargetService que aponta para o Cloud Run usando o elemento Authentication para gerar um token do OpenID Connect necessário para autenticar a chamada: O elemento HeaderName adiciona o token do portador gerado a um cabeçalho chamado X-Serverless-Authorization que é enviado ao sistema de destino. O cabeçalho Authorization, se presente, não é modificado e também é enviado na solicitação.

<TargetEndpoint name="TargetEndpoint-1">
   <HTTPTargetConnection>
     <Authentication>
        <HeaderName>X-Serverless-Authorization</HeaderName>
        <GoogleIDToken>
            <Audience ref="flow.variable.audience">https://cloudrun-hostname.a.run.app</Audience>
        </GoogleIDToken>
     </Authentication>
      <LoadBalancer>
         <Server name="cloud-run-target" />
      </LoadBalancer>
   </HTTPTargetConnection>
</TargetEndpoint>

No exemplo a seguir, veja como chamar um TargetService que aponta para o serviço do Gerenciador de secrets do Google. Neste exemplo, o elemento GoogleAccessToken é configurado para gerar um token de autenticação do Google para autenticar a solicitação de destino:

<HTTPTargetConnection>
   <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
</HTTPTargetConnection>

O exemplo a seguir mostra como definir automaticamente o público-alvo do GoogleIDToken. Quando useTargetUrl for true e a variável referenciada não for resolvida como uma variante válida, o URL de destino (exceto os parâmetros de consulta) será usado como público-alvo. Se o caminho da solicitação for /foobar e o URL do servidor de destino for https://xyz.com, o público-alvo do GoogleIDToken será definido automaticamente como https://xyz.com/foobar.

Usuários da Apigee híbrida: se você usa a Apigee híbrida, o atributo useTargetUrl está disponível nas versões híbridas 1.8 e posteriores da Apigee.

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience ref='myvariable' useTargetUrl="true"/>
      </GoogleIDToken>
    </Authentication>
    <LoadBalancer>
      <Server name="TS" />
    </LoadBalancer>
  </HTTPTargetConnection>
</TargetEndpoint>

Configuração de TargetEndpoint TLS/SSL

Os endpoints de destino geralmente precisam 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`	O bloco `<SSLInfo>` pode ser usado para TLS/SSL unidirecional e bidirecional.
`Enabled`	Quando definido como `true`, especifica que a conexão de destino precisa usar o protocolo SSL de acordo com outros parâmetros especificados neste bloco `<SSLInfo>`. Quando definido como `false`, especifica que a conexão de destino não deve usar SSL. No entanto, se o bloco `<HTTPTargetConnection>` que contém um elemento `<URL>` que avalia para uma string que começa com `https://`, o protocolo SSL será usado mesmo que `<Enabled>` seja falso. Nesse caso, todo o bloco `<SSLInfo>` é ignorado. Por outro lado, se houver um elemento `<URL>` que comece com `http://`, o protocolo SSL não será usado, mesmo que `<Enabled>` seja verdadeiro.	falso	Não
`Enforce`	Aplica SSL rigoroso entre a Apigee e o back-end de destino. Se definidas como `true`, as conexões falharão para destinos com certificados inválidos, certificados expirados, certificados autoassinados, certificados com uma incompatibilidade de nome do host e certificados com uma raiz não confiável. Um código de falha `4xx` ou `5xx` é retornado. Se não for definido ou for definido como `false`, o resultado das conexões para back-ends de destino com certificados problemáticos dependerá da configuração de `<IgnoreValidationErrors>`. Confira abaixo. Uma resposta de sucesso (`2xx`) poderá ocorrer em determinadas condições, se `<IgnoreValidationErrors>` estiver definido como `true`.	`false`	Não
`TrustStore`	Um keystore com certificados de servidor raiz confiáveis. A Apigee vai tratar o peering remoto como confiável se a cadeia de certificados que ele envia terminar em um certificado que está contido neste keystore.	N/A	Não
`ClientAuthEnabled`	Se definida como `true`, ativa o TLS bidirecional (também conhecido como TLS mútuo ou mTLS). entre a Apigee e o peering remoto, seja o cliente da API ou o back-end de destino. A ativação do TLS bidirecional normalmente exige que você configure um truststore e um keystore na Apigee.	`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)
`IgnoreValidationErrors`	Indica se os erros de validação são ignorados. Se o sistema de back-end usar SNI e retornar um certificado com um nome distinto (DN, na sigla em inglês) de assunto que não corresponda ao nome do host, não será possível ignorar o erro, e a conexão falhará. Observação: se `<Enforce>` for definido como `true`, o valor de `<IgnoreValidationErrors>` será ignorado.	`false`	Não
`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, especifique-os explicitamente. Por exemplo, para permitir apenas TLS v1.2 ou TLS v1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols>	N/A	Não
`CommonName`	A Apigee verifica o valor aqui em relação ao CN (nome comum) ou SANs (Nomes alternativos do assunto) no certificado de peering remoto.	N/A	Não

Exemplo do endpoint de destino com a autenticação de cliente de saída ativada

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

Para instruções detalhadas, consulte Opções de configuração de TLS.

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 Dynamic SSLInfo for TargetEndpoint using variable reference (em inglês) da comunidade Apigee explica esse cenário em mais detalhes e fornece exemplos de proxy da API implantáveis.

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 AssignMessage. 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 endpoint de destino que usa HTTPS, é preciso considerar o caso quando o certificado TLS/SSL expira ou uma alteração na configuração do sistema exige a atualização do certificado.

Para mais informações, consulte Como lidar com certificados expirados.

No entanto, você tem a opção de configurar o endpoint de destino 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 endpoint de destino 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 "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>'

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como configurar variáveis de ambiente para solicitações da API Apigee.

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

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

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

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 "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

TargetEndpoint com balanceamento de carga de destino

Os endpoints de destino são compatíveis com balanceamento de carga em vários servidores de destino nomeados usando três algoritmos de balanceamento de carga.

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

IntegrationEndpoint

Um IntegrationEndpoint é um endpoint de destino que executa especificamente integrações da Apigee. Se você configurou um IntegrationEndpoint, a Apigee envia o objeto request à plataforma de integração da Apigee para execução. Para executar a integração, além de configurar a IntegrationEndpoint, você também precisa adicionar a política SetIntegrationRequest no fluxo de proxy.

É possível configurar a integração para ser executada de maneira síncrona ou assíncrona. Basta definir o elemento <AsyncExecution> na integração IntegrationEndpoint. Para mais informações, consulte Execução síncrona versus assíncrona. Depois de executar a integração, a Apigee salva a resposta na mensagem de resposta.

Observação: você precisa de um token de autenticação para executar o IntegrationEndpoint. No entanto, não há nenhum elemento <Authentication> explícito na definição de EndpointsEndpoint. A Apigee adiciona um token de autenticação à solicitação internamente. Para que o IntegrationEndpoint faça a autenticação com êxito, é necessário implantar o proxy de API com uma conta de serviço que tenha os papéis do IAM necessários para executar uma integração. Para informações sobre os papéis necessários, consulte Papéis do IAM para integrações. Para mais detalhes sobre como implantar um proxy de API, consulte Implantar na Apigee.

Como configurar IntegrationEndpoint

Para configurar um endpoint de integração como o endpoint de destino, adicione o elemento IntegrationEndpoint à configuração do ProxyEndpoint. Veja a seguir uma amostra de configuração de ProxyEndpoint:

<ProxyEndpoint name="default">
    <Description/>
    <FaultRules/>
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>my-set-integration-request-policy</Name>
            </Step>
        </Request>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow"/>
    <HTTPProxyConnection>
        <BasePath>/integration-endpoint-test</BasePath>
        <Properties/>
    </HTTPProxyConnection>
    <RouteRule name="default">
        <IntegrationEndpoint>my-int-endpoint</IntegrationEndpoint>
    </RouteRule>
</ProxyEndpoint>

Na configuração ProxyEndpoint de amostra, a Apigee executa as seguintes tarefas:

No PreFlow, executa a política chamada my-set-integration-request-policy, que define o objeto da solicitação de integração e as variáveis de fluxo de integração.
Usa my-int-endpoint como o endpoint de destino, conforme especificado em RouteRule.
Lê o objeto de solicitação de integração criado pelo my-set-integration-request-policy.
Envia a solicitação para a plataforma de integração da Apigee usando o objeto da solicitação e as variáveis de fluxo definidas pela política SetIntegrationRequest.
Salva a resposta da integração na mensagem de resposta.

O arquivo XML que contém a declaração <IntegrationEndpoint> estará disponível no diretório APIGEE_BUNDLE_DIRECTORY/apiproxy/integration-endpoints/. Se você criar seu proxy de API usando a opção Develop > API Proxies > CREATE NEW > Integration target, a Apigee armazena a declaração no arquivo /apiproxy/integration-endpoints/default.xml. Se você criar o XML do endpoint de integração a partir da IU, poderá fornecer um nome personalizado para o arquivo XML.

O exemplo a seguir mostra a declaração do elemento <IntegrationEndpoint> no arquivo XML:

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>false</AsyncExecution>
</IntegrationEndpoint>

Elementos de configuração de IntegrationEndpoint

Nome	Descrição	Padrão	Obrigatório?
`IntegrationEndpoint`
`name`	O nome do IntegrationEndpoint. Os caracteres que você pode usar no nome são restritos a: `A-Za-z0-9._\-$ %`	N/A	Sim
`AsyncExecution`	Um valor booleano que especifica se a integração precisa ser executada no modo síncrono ou assíncrono. Para mais informações, consulte Execução síncrona versus assíncrona.	falso	Não

Execução síncrona versus assíncrona

Você pode configurar a integração para ser executada em modo síncrono ou assíncrono. Para entender a diferença entre os modos de execução síncrono e assíncrono, consulte <AsyncExecution>.

Use o elemento <AsyncExecution> em </IntegrationEndpoint> para especificar a execução síncrona ou assíncrona. Se <AsyncExecution> for definido como true, a integração será executada de maneira assíncrona. Se você a definir como false, a integração será executada de maneira síncrona.

O exemplo a seguir define a AsyncExecution como true:

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>true</AsyncExecution>
</IntegrationEndpoint>

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 IU da Apigee impõe outras restrições, como a remoção automática de caracteres que não são alfanuméricos. Opcionalmente, use o elemento `<DisplayName>` para rotular a política no editor de proxy da IU do Apigee com um nome de linguagem natural diferente.	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.	`true`	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 padrão `false`. 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
endpont de proxy e o endpoint de destino, que contêm etapas que acionam políticas. Depois que o
serviço HTTP retorna a resposta, ela é processada pelo endpoint de destino 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. Por 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 endpoint de proxy, que é executado depois que a resposta é retornada ao app cliente solicitante. Somente a política MessageLogging pode ser anexada 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.

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:

PreFlow da solicitação de proxy
Fluxos condicionais de solicitação de proxy (opcional)
PostFlow de solicitação de proxy
PreFlow da solicitação de destino
Fluxos condicionais de solicitação de destino (opcional)
PostFlow da solicitação de destino

Pipeline de resposta:

PreFlow de resposta de destino
Fluxos condicionais de resposta desejada (opcional)
PostFlow de resposta de destino
PreFlow de resposta do proxy
Fluxos condicionais de resposta de proxy (opcional)
PostFlow de resposta de proxy
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

Os endpoints de proxy e de destino 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 de 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 endpoint de proxy ou endpoint de destino
`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. No entanto, se você incluir um único fluxo sem uma condição no final de uma sequência de fluxos, ele vai funcionar como a instrução 'Else' no final da sequência de fluxos.	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 dos fluxos condicionais é aplicada pela Apigee. 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. Elas aparecem na seção Scripts do editor de proxy de API na IU da Apigee.

Consulte Como gerenciar recursos para saber os tipos de recurso 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. A Apigee resolve 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.