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:
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:
/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, 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 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: |
/ | Sim | |||||||||||||||
Properties |
Um conjunto de configurações de HTTP opcionais pode ser definido como propriedades de
<ProxyEndpoint> .
Use a propriedade <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
|
N/A | Não | |||||||||||||||
FaultRules |
Define como o endpoint de proxy reage a um erro. Uma regra de falha especifica dois
itens:
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 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).
É possível usar a página |
||
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. | 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:
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>
. ServiceCall.
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
.
<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 |
||
Enabled |
Se definido como O valor padrão de |
verdadeiro se <URL> especificar HTTPS. |
Não |
Enforce |
Aplica SSL rigoroso entre a Apigee e o back-end de destino. Se definidas como Se não for definido ou for definido como |
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 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 |
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"
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.
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.
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 emRouteRule
. - 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:
Opcionalmente, use o elemento |
N/A | Sim |
enabled |
Defina como Defina como |
true |
Não |
continueOnError |
Defina como Defina como |
false |
Não |
async |
Quando definida como 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:
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 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 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 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. | 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.