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

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Esta página se aplica ao Apigee e ao Apigee híbrido .

Veja a documentação do Apigee Edge .

Como desenvolvedor que trabalha com a 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 para você ao criar proxies de API.

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

Edite sua configuração de proxy de API usando um dos seguintes métodos:

• Use a interface do usuário ou a API do Apigee.
• Baixe o pacote de configuração do proxy da API, edite-o manualmente e carregue a nova configuração no Apigee, conforme descrito em Como baixar e carregar um pacote de configuração do proxy da API .

Estrutura de diretório de configuração do proxy da API

A estrutura do diretório de configuração do proxy da API é mostrada abaixo:

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

Configuração base

/apiproxy/weatherapi.xml

A configuração básica para um proxy de API, que define o nome do proxy de API. O nome deve ser exclusivo dentro de uma organização.

Configuração de exemplo:

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

Elementos de configuração básica

Ponto de extremidade do proxy

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

/apiproxy/proxies/default.xml

A configuração ProxyEndpoint define a interface de entrada (voltada para o cliente) para um proxy de API. Ao configurar um endpoint de proxy, você está definindo uma configuração de rede que define como os aplicativos cliente ( apps ) devem invocar a API com proxy.

A seguinte configuração de exemplo do 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 ponto de extremidade proxy básico são:

Elementos de configuração do ProxyEndpoint

Como configurar RouteRules

Um ponto de extremidade de destino nomeado refere-se a um arquivo de configuração em /apiproxy/targets para o qual o RouteRule encaminha uma solicitação após o processamento pelo ponto de extremidade do proxy.

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

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

Invocação direta de URL

Um ponto de extremidade proxy também pode invocar diretamente um serviço de backend. A invocação direta de URL ignora qualquer configuração TargetEndpoint nomeada em /apiproxy/targets . Por esse motivo, TargetEndpoint é uma configuração de proxy de API opcional, embora, na prática, a invocação direta do ponto de extremidade proxy não seja recomendada.

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

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

Rotas condicionais

RouteRules podem ser encadeadas para oferecer suporte ao roteamento dinâmico em tempo de execução. Requisições de entrada podem ser roteadas para configurações de TargetEndpoint nomeadas, diretamente para URLs ou para uma combinação dos dois, com base em cabeçalhos HTTP, conteúdo da mensagem, parâmetros de consulta ou informações contextuais, como hora do dia, localidade, etc.

As RouteRules condicionais funcionam como outras instruções condicionais na Apigee. Consulte a referência de Condições e a referência de Variáveis ​​de fluxo .

Por exemplo, a seguinte combinação de RouteRule 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 denominado 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 ao endpoint de destino. Isso é útil quando o endpoint do proxy realiza todo o processamento necessário, por exemplo, usando JavaScript para chamar um serviço externo ou recuperando dados de uma consulta para o repositório de chaves/valores 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 é 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 Route nula condicional normalmente seria um componente de um conjunto de RouteRules projetadas para oferecer suporte ao roteamento condicional.

Um uso prático de uma Rota nula condicional seria o suporte ao cache. Usando o valor da variável definida pela política de cache, você pode configurar um proxy de API para executar a Rota nula quando uma entrada for fornecida pelo cache.

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

Ponto final de destino

Um endpoint de destino é o equivalente de saída de um endpoint proxy. Um endpoint de destino funciona como cliente para um serviço de backend ou API — ele envia solicitações e recebe respostas.

Um proxy de API não precisa ter endpoints de destino. Os endpoints de proxy podem ser configurados para chamar URLs diretamente. Um proxy de API sem endpoints de destino geralmente contém um endpoint de proxy que chama diretamente um serviço de backend ou que está configurado para chamar um serviço usando Java ou JavaScript.

Configuração do TargetEndpoint

/targets/default.xml

O ponto de extremidade de destino define a conexão de saída do Apigee para outro serviço ou recurso.

Aqui está 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 ponto de extremidade de destino pode chamar um destino de uma das seguintes maneiras:

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

Configure apenas um deles em um ponto de extremidade de destino.

<Properties>
  <Property name="response.payload.parse.limit">15M</Property>
</Properties>

Uso do elemento <Authentication>

Referência de erro do elemento <Authentication>

Se estiver usando o elemento <Authentication> , você 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 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 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 OpenID Connect necessário para autenticar a chamada. O elemento HeaderName adiciona o token de portador gerado a um cabeçalho denominado X-Serverless-Authorization , que é enviado ao sistema de destino. O cabeçalho Authorization , se presente, permanece inalterado 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>

O exemplo a seguir mostra como chamar um TargetService que aponta para o serviço Gerenciador de Segredos 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 do GoogleIDToken. Quando useTargetUrl for true e a variável referenciada não for resolvida para uma variável válida, a URL do destino (excluindo parâmetros de consulta) será usada como público. Suponha que o caminho da solicitação seja /foobar e a URL do servidor de destino seja https://xyz.com , o público do GoogleIDToken será automaticamente definido 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 do TargetEndpoint TLS/SSL

Os endpoints de destino geralmente precisam gerenciar conexões HTTPS com infraestrutura de backend heterogênea. Por esse motivo, diversas definições de configuração TLS/SSL são suportadas.

Elementos de configuração do TLS/SSL TargetEndpoint

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

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

Especificando a aplicação de SSL no nível do ambiente

Se SSLInfo.Enforce for definido como true ou false , o valor especificado substituirá quaisquer opções de aplicação granular especificadas nos blocos <SSLInfo> nas configurações TargetEndpoint ou TargetServer.

Se SSLInfo.Enforce não estiver definido, a aplicação do SSL será determinada por quaisquer valores especificados usando o elemento <Enforce> dentro de blocos <SSLInfo> individuais. Para obter mais informações, consulte a configuração do TargetEndpoint TLS/SSL.

No exemplo a seguir, SSLInfo.Enforce está definido como true . Na saída resultante, você pode ver que o SSL é aplicado no ambiente especificado.

VALUE=true
curl -Ss -v -X PUT \
    "https://apigee.googleapis.com/v1/organizations/MYORG/environments/MYENV" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer TOKEN" \
    -d '{
        "name": "MYENV",
        "properties": {
            "property": [{
                "name": "features.SSLInfo.Enforce",
                "value": "'"$VALUE"'"
            }]
        }
    }'
  

Saída:

{
  ...
  "properties": {
    "property": [
      {
        "name": "features.SSLInfo.Enforce",
        "value": "true"
      }
    ]
  },
  ...
}

Exemplo de ponto de extremidade de destino com autenticação de cliente de saída habilitada

<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 obter instruções detalhadas, consulte Opções para configurar TLS .

Usando variáveis ​​de fluxo para definir valores TLS/SSL dinamicamente

Você também pode definir dinamicamente os detalhes de TLS/SSL para atender a requisitos de tempo de execução flexíveis. Por exemplo, se o seu proxy se conectar a dois destinos potencialmente diferentes (um destino de teste e um destino de produção), você poderá fazer com que o proxy de API detecte programaticamente qual ambiente está chamando e defina dinamicamente as referências ao keystore e ao truststore apropriados. O artigo da Comunidade Apigee "Dynamic SSLInfo for TargetEndpoint using variable reference" explica esse cenário com mais detalhes e fornece exemplos de proxy de API implantáveis.

No exemplo a seguir de como a tag <SSLInfo> seria definida em uma configuração TargetEndpoint, os valores podem ser fornecidos em tempo de execução, por exemplo, por uma chamada Java, uma política JavaScript ou uma política AssignMessage . Use as variáveis ​​de mensagem que contêm os valores que você deseja definir.

Variáveis ​​são permitidas somente nos seguintes elementos.

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

Usando referências para definir valores TLS/SSL dinamicamente

Ao configurar um ponto de extremidade de destino que usa HTTPS, você deve considerar o caso em que o certificado TLS/SSL expira ou uma alteração na configuração do sistema exige que você atualize o certificado.

Para obter mais informações, consulte Manipulando certificados expirados .

No entanto, você pode, opcionalmente, configurar o endpoint de destino para usar uma referência ao keystore ou truststore. A vantagem de usar uma referência é que você pode atualizá-la para apontar para um keystore ou truststore diferente e atualizar o certificado TLS/SSL sem precisar reiniciar os Processadores de Mensagens.

Por exemplo, abaixo é mostrado um ponto de extremidade 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 de API POST 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>'

Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

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

Use a seguinte chamada de API GET para visualizar a referência:

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

Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

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

Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

Para alterar posteriormente a referência para apontar para um keystore diferente, garantindo que o alias tenha o mesmo nome, 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>'

Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

TargetEndpoint com balanceamento de carga de destino

Os endpoints de destino oferecem suporte ao balanceamento de carga entre vários servidores de destino nomeados usando três algoritmos de balanceamento de carga.

Para obter instruções detalhadas, consulte Balanceamento de carga entre servidores de backend .

Ponto de extremidade de integração

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

Você pode configurar sua integração para ser executada de forma síncrona ou assíncrona definindo o elemento <AsyncExecution> na configuração IntegrationEndpoint. Para obter mais informações, consulte Execução síncrona vs. assíncrona . Após executar a integração, a Apigee salva a resposta na mensagem de resposta .

Configurando o IntegrationEndpoint

Para configurar um endpoint de integração como seu endpoint de destino, adicione o elemento IntegrationEndpoint à sua configuração ProxyEndpoint. A seguir, um exemplo de configuração 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 de exemplo do ProxyEndpoint, a Apigee executa as seguintes tarefas:

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

O arquivo XML contendo 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 armazenará a declaração no arquivo /apiproxy/integration-endpoints/default.xml . Se você criar o XML do endpoint de integração a partir da interface do usuário, 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 do IntegrationEndpoint

Execução síncrona vs. assíncrona

Você pode configurar a integração para ser executada no 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> dentro de </IntegrationEndpoint> para especificar a execução síncrona ou assíncrona. Se você definir <AsyncExecution> como true , a integração será executada de forma assíncrona. E se você definir como false , a integração será executada de forma síncrona.

O exemplo a seguir define 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 de política

Anexo de políticas

A imagem a seguir mostra a sequência de execução dos fluxos de proxy da API:

Conforme mostrado acima:

As políticas são anexadas como etapas de processamento para os fluxos . O nome da política é usado para fazer referência à política a ser aplicada como uma etapa de processamento. O formato de um anexo político é o seguinte:

<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 de anexo de políticas

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 fluxo de resposta são subdivididos em um pré -fluxo, um ou mais fluxos condicionais ou nomeados opcionais e um pós -fluxo.

• Preflow: sempre é executado. Executa antes de qualquer fluxo condicional.
• Pós -fluxo: sempre é executado. Executa após qualquer fluxo condicional.

Além disso, você pode adicionar um fluxo pós -client ao endpoint proxy, que é executado após o retorno da resposta ao aplicativo do cliente solicitante. Somente a política do Messagelogging pode ser anexada a esse fluxo. O Post -ClientFlow reduz a latência do proxy da API e disponibiliza informações para registro que não são calculadas até que a resposta seja devolvida ao cliente, como o client.sent.start.timestamp e client.sent.end.timestamp . O fluxo é usado principalmente para medir o intervalo de tempo entre os timestamps iniciais e finais para a mensagem de resposta.

Aqui está um exemplo de um fluxo pós -client com uma 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 de proxy da API executa os fluxos na seguinte sequência:

Solicitar pipeline:

1. Solicitação de proxy pré -fluxo
2. Solicitação de proxy Fluxos condicionais (opcional)
3. Solicitação de proxy PostFlow
4. Solicitação de destino Pré -fluxo
5. Solicitação de destino Fluxos condicionais (opcional)
6. Solicitação de destino pós -fluxo

Oleoduto de resposta:

1. Atenda de resposta do alvo
2. Resposta do alvo Fluxos condicionais (opcional)
3. RESPOSTA DE TARGENS Pós -fluxo
4. Resposta de proxy pré -fluxo
5. Resposta de proxy Fluxos condicionais (opcional)
6. Resposta de proxy Pós -fluxo
7. Resposta pós -clientflow (opcional)

Somente os fluxos com anexos de políticas precisam ser configurados nas configurações do ProxyendPoint ou TargetEndPoint. O pré -fluxo e o pós -fluxo precisam ser especificados apenas em uma configuração de proxyendpoint ou TargetEndPoint quando uma política precisa ser aplicada durante o processamento de pré -fluxo ou pós -fluxo.

Em contraste com os fluxos condicionais, a ordem dos elementos de pré-fluxo e pós-fluxo não é importante-o proxy da API sempre será executado cada um no ponto apropriado da tubulação, independentemente de onde eles aparecem na configuração do endpoint.

Fluxos condicionais

Os pontos de extremidade de proxy e pontos de extremidade de destino suportam um número ilimitado de fluxos condicionais (também conhecidos como fluxos nomeados ).

Os testes de proxy da API para a condição especificada no fluxo condicional e, se a condição for atendida, as etapas de processamento no fluxo condicional serão executadas pelo proxy da 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 da API e a primeira cuja condição é atendida é executada.

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

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

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

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

Elementos de configuração de fluxo

Processamento de etapas

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

Por exemplo, na seguinte configuração de fluxo, qualquer solicitação de entrada que não inclua o sufixo do 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, codificados e transformações XSL que podem ser anexadas aos fluxos usando políticas. Eles aparecem na seção Scripts do editor de proxy da API na interface do usuário da Apigee.

Consulte o gerenciamento de recursos para os tipos de recursos suportados.

Os recursos podem ser armazenados em um proxy da API, um ambiente ou uma organização. Em cada caso, um recurso é referenciado pelo nome em uma política. O APIGEE resolve o nome, passando do proxy da API, para o meio ambiente, para 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 de proxy da API pode ser referenciado apenas por políticas nesse proxy da API.

Esta página se aplica ao Apigee e ao Apigee híbrido .

Veja a documentação do Apigee Edge .

Como 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 ao criar proxies da API.

Se você está aprendendo a criar proxies de API, é recomendável que você comece com a criação de um proxy de API simples .

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

• Use a interface do usuário ou API 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 o Apigee, conforme descrito ao baixar e fazer upload de um pacote de configuração de proxy da API .

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

A estrutura do diretório de configuração de proxy da API é mostrada abaixo:

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

Configuração base

/apiproxy/weatherapi.xml

A configuração base para um proxy da API, que define o nome do proxy da API. O nome deve ser único em uma organização.

Configuração de amostra:

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

Elementos de configuração base

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 (voltada para o cliente) para um proxy da API. Quando você configura um ponto de extremidade de proxy, está configurando uma configuração de rede que define como os aplicativos do cliente ( APPS ) devem invocar a API proxiada.

A seguinte configuração de proxyendpoint de amostra 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 básico de proxy são:

Elementos de configuração do proxyendpoint

Como configurar roteadores

Um terminal de destino nomeado refere -se a um arquivo de configuração em /apiproxy/targets aos quais o roteterule encaminha uma solicitação após o processamento pelo endpoint de procuração.

Por exemplo, o seguinte routerule refere -se à configuração /apiproxy/targets/myTarget.xml :

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

Invocação direta de URL

Um terminal de proxy também pode chamar diretamente um serviço de back -end. A Invocation Direct URL ignora qualquer configuração de TargetEndPoint nomeada em /apiproxy/targets ). Por esse motivo, o TargetEndPoint é uma configuração opcional de proxy da API, embora, na prática, a invocação direta do endpoint proxy não seja recomendada.

Por exemplo, o roteterule 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

Os roteadores podem ser acorrentados para apoiar o roteamento dinâmico em tempo de execução. As solicitações de entrada podem ser roteadas para configurações de TargetEndPoint nomeadas, diretamente para URLs ou para uma combinação dos dois, com base em cabeçalhos HTTP, conteúdo de mensagens, parâmetros de consulta ou informações contextuais, tal hora do dia, localidade, etc.

Os routerules condicionais funcionam como outras declarações condicionais no Apigee. Consulte Referência de Referência e Variáveis ​​de Fluxo .

Por exemplo, a combinação de roteterule 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 Value TargetEndpoint1 , a solicitação será encaminhada para o terminal de destino denominado TargetEndpoint1 . Caso contrário, a solicitação de entrada é 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

Um roteterule nulo pode ser definido para apoiar cenários nos quais a mensagem de solicitação não precisa ser encaminhada para o terminal de destino. Isso é útil quando o endpoint proxy executa todo o processamento necessário, por exemplo, usando o JavaScript para chamar um serviço externo ou recuperar dados de uma pesquisa para o armazenamento de chave/valor do 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 é configurada para executar quando uma 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 os roteadores podem ser encadeados; portanto, uma rota nula condicional normalmente seria um componente de um conjunto de roteterules projetadas para suportar o roteamento condicional.

O uso prático de uma rota nula condicional seria apoiar o cache. Usando o valor da variável definida pela política de cache, você pode configurar um proxy da API para executar a rota nula quando uma entrada é servida no cache.

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

TargetEndPoint

Um ponto de extremidade de destino é o equivalente de saída de um terminal de procuração. Um terminal de destino funciona como cliente para um serviço de back -end ou API - envia solicitações e recebe respostas.

Um proxy da API não precisa ter nenhum ponto de extremidade de destino. Os terminais de proxy podem ser configurados para ligar diretamente para URLs. Um proxy da API sem pontos de extremidade de destino geralmente contém um terminal de proxy 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 terminal de destino define a conexão de saída do Apigee para outro serviço ou recurso.

Aqui está uma amostra 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 alvo pode chamar um alvo de uma das seguintes maneiras:

• HttptargetConnection para chamadas http ou https
• LocalTargetConnection para encadeamento local de proxy-proxy

Configure apenas um desses em um terminal de destino.

<Properties>
  <Property name="response.payload.parse.limit">15M</Property>
</Properties>

<Authentication> Uso do elemento

Referência de erro do elemento <Authentication>

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

Exemplos de elementos <Authentication>

O exemplo a seguir mostra como chamar um serviço implantado no Cloud Run como o destino usando o elemento Authentication para gerar um token de conexão OpenID 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 serviço de destino que aponta para a nuvem Run usando o elemento Authentication para gerar um token de conexão OpenID 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, é deixado 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>

O exemplo a seguir mostra como chamar um serviço de destino que aponta para o Serviço do Google Secret Manager . Neste exemplo, o elemento GoogleaccessToken está 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 do GoogleidToken. Quando useTargetUrl é true e a variável referenciada não resolve para uma variável válida, o URL do destino (excluindo parâmetros de consulta) é usado como público. Suponha que o caminho da solicitação seja /foobar e o URL do servidor de destino seja https://xyz.com , o público do GoogleidToken será automaticamente definido 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 do TargetEndPoint TLS/SSL

Os pontos de extremidade de destino geralmente precisam gerenciar conexões HTTPS com infraestrutura de back -end heterogênea. Por esse motivo, várias definições de configuração TLS/SSL são suportadas.

TLS/SSL TargetEndPoint Configuração Elementos

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

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

Especificando a aplicação do SSL no nível do meio ambiente

Se SSLInfo.Enforce for definido como true ou false , o valor especificado substitui quaisquer opções de aplicação granular especificadas nos blocos <SSLInfo> nas configurações do TargetEndPoint ou TargetServer.

Se SSLInfo.Enforce não for definido, a aplicação do SSL será determinada por quaisquer valores especificados usando o elemento <Enforce> dentro de blocos individuais <SSLInfo> . Para obter mais informações, consulte Configuração TLS/SSL TargetEndPoint.

No exemplo a seguir, SSLInfo.Enforce está definido como true . Na saída resultante, você pode ver que o SSL é aplicado no ambiente especificado.

VALUE=true
curl -Ss -v -X PUT \
    "https://apigee.googleapis.com/v1/organizations/MYORG/environments/MYENV" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer TOKEN" \
    -d '{
        "name": "MYENV",
        "properties": {
            "property": [{
                "name": "features.SSLInfo.Enforce",
                "value": "'"$VALUE"'"
            }]
        }
    }'
  

Saída:

{
  ...
  "properties": {
    "property": [
      {
        "name": "features.SSLInfo.Enforce",
        "value": "true"
      }
    ]
  },
  ...
}

Exemplo de terminal de destino com 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 as opções para configurar o TLS .

Usando variáveis ​​de fluxo para definir valores de TLS/SSL dinamicamente

Você também pode definir dinamicamente os detalhes TLS/SSL para suportar requisitos flexíveis de tempo de execução. Por exemplo, se o seu proxy se conectar a dois alvos potencialmente diferentes (um alvo de teste e um alvo de produção), você poderá detectar programaticamente o seu ambiente que está chamando e definir referências dinamicamente para a Keystore e TrustStore apropriados. O dinâmico artigo da Comunidade Apigee de referência da variável Apigee explica esse cenário com mais detalhes e fornece exemplos implantáveis ​​de proxy da API.

No exemplo a seguir de como a tag <SSLInfo> seria definida em uma configuração do TargetEndPoint, os valores podem ser fornecidos em tempo de execução, por exemplo, por uma chamada de Java, uma política de JavaScript ou uma política de atribuições . Use as variáveis ​​de mensagem que contêm os valores que você deseja definir.

Variáveis ​​são permitidas apenas nos seguintes elementos.

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

Usando referências para definir valores TLS/SSL dinamicamente

Ao configurar um terminal de destino que usa HTTPS, você deve considerar o caso quando o certificado TLS/SSL expirar ou uma alteração na configuração do sistema exige que você atualize o cert.

Para mais informações, consulte o manuseio de certificados expirados .

However, you can optionally configure the target endpoint to use a reference to the keystore or truststore instead. The advantage to using a reference is that you can update the reference to point to a different keystore or truststore to update the TLS/SSL cert without having to restart Message Processors.

For example, shown below is a target endpoint that uses a reference to the keystore:

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

Use the following POST API call to create the reference named 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>'

Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

The reference specifies the name of the keystore and its type.

Use the following GET API call to view the reference:

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

Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

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

Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

To later change the reference to point to a different keystore, ensuring that the alias has the same name, use the following PUT call:

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>'

Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

TargetEndpoint with target load balancing

Target endpoints support load balancing across multiple named target servers using three load balancing algorithms.

For detailed instructions, refer to Load balancing across backend servers .

IntegrationEndpoint

An IntegrationEndpoint is a target endpoint that specifically runs Apigee integrations . If you have configured an IntegrationEndpoint, Apigee sends the request object to Apigee's Integration Platform for execution. To run your integration, in addition to configuring the IntegrationEndpoint, you must also add the SetIntegrationRequest policy in your proxy flow.

You can configure your integration to execute either synchronously or asynchronously by setting the <AsyncExecution> element in the IntegrationEndpoint configuration. For more information, see Synchronous vs Asynchronous execution . After running the integration, Apigee saves the response in the response message .

Configuring IntegrationEndpoint

To configure an integration endpoint as your target endpoint, add the IntegrationEndpoint element to your ProxyEndpoint configuration. The following is a sample ProxyEndpoint configuration:

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

In the sample ProxyEndpoint configuration, Apigee performs the following tasks:

1. In the PreFlow, executes the policy named my-set-integration-request-policy , which sets the integration request object and integration flow variables.
2. Uses my-int-endpoint as the target endpoint, as specified in the RouteRule .
3. Reads the integration request object created by the my-set-integration-request-policy .
4. Sends the request to Apigee's Integration Platform using the request object and flow variables set by the SetIntegrationRequest policy.
5. Saves the response of the integration in the response message.

The XML file containing the <IntegrationEndpoint> declaration will be available in the APIGEE_BUNDLE_DIRECTORY /apiproxy/integration-endpoints/ directory. If you create your API proxy using the Develop > API Proxies > CREATE NEW > Integration target option, Apigee stores the declaration in the /apiproxy/integration-endpoints/default.xml file. If you create the integration endpoint XML from the UI, you can provide a custom name for the XML file.

The following example shows the declaration of the <IntegrationEndpoint> element in the XML file:

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

IntegrationEndpoint configuration elements

Synchronous vs Asynchronous execution

You can configure the integration to run in either synchronous or asynchronous mode. To understand the difference between synchronous and asynchronous execution modes, see <AsyncExecution> .

Use the <AsyncExecution> element within the </IntegrationEndpoint> to specify synchronous or asynchronous execution. If you set <AsyncExecution> to true , the integration runs asynchronously. And if you set it to false , the integration runs synchronously.

The following example sets the AsyncExecution to true :

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

Políticas

The /policies directory in an API proxy contains all policies available to be attached to Flows in the API proxy.

Policy configuration elements

Policy attachment

The following image shows the API proxy flows execution sequence:

Conforme mostrado acima:

Policies are attached as processing steps to Flows . The policy's name is used to reference the policy to be enforced as a processing Step. The format of a policy attachment is the following:

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

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

Policy attachment configuration elements

Fluxos

ProxyEndpoint and TargetEndpoint define a pipeline for request and response message processing. A processing pipeline consists of a request flow and a response flow. Each request flow and response flow is subdivided into a PreFlow, one or more optional conditional or named flows, and a PostFlow.

• PreFlow: Always executes. Executes before any conditional Flows.
• PostFlow: Always executes. Executes after any conditional Flows.

Additionally, you can add a PostClientFlow to the proxy endpoint, which executes after the response is returned to the requesting client app. Only the MessageLogging policy can be attached to this flow. PostClientFlow reduces API proxy latency and makes information available for logging that is not calculated until after the response is returned to the client, such as the client.sent.start.timestamp and client.sent.end.timestamp .The flow is used primarily for measuring the time interval between the start and end timestamps for the response message.

Here's an example of a PostClientFlow with a message logging policy attached.

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

The API proxy processing pipeline executes Flows in the following sequence:

Request Pipeline:

1. Proxy Request PreFlow
2. Proxy Request Conditional Flows (Optional)
3. Proxy Request PostFlow
4. Target Request PreFlow
5. Target Request Conditional Flows (Optional)
6. Target Request PostFlow

Response Pipeline:

1. Target Response PreFlow
2. Target Response Conditional Flows (Optional)
3. Target Response PostFlow
4. Proxy Response PreFlow
5. Proxy Response Conditional Flows (Optional)
6. Proxy Response PostFlow
7. PostClientFlow Response (Optional)

Only those Flows with policy attachments need to be configured in ProxyEndpoint or TargetEndpoint configurations. PreFlow and PostFlow need only be specified in a ProxyEndpoint or TargetEndpoint configuration when a policy needs to be enforced during PreFlow or PostFlow processing.

In contrast to conditional flows, the ordering of PreFlow and PostFlow elements is not important--the API proxy will always execute each at the appropriate point in the pipeline, regardless of where they appear in the Endpoint configuration.

Fluxos condicionais

Proxy endpoints and target endpoints support an unlimited number of conditional flows (also known as named flows ).

The API proxy tests for the condition specified in the conditional flow and, if the condition is met, the processing steps in the conditional flow are executed by the API proxy. If the condition is not met, then the processing steps in the conditional flow are bypassed. Conditional flows are evaluated in the order defined in the API proxy and the first one whose condition is met is executed.

By defining conditional flows, you gain the ability to apply processing steps in an API proxy based on:

• URI de solicitação
• HTTP verb ( GET / PUT / POST / DELETE )
• Value of a query param, header, and form param
• Many other types of conditions

For example, the following conditional flow specifies that it is executed only when the request resource path is /accesstoken . Any inbound request with the path /accesstoken causes this flow to be executed, along with any policies that are attached to the flow. If the request path does not include the suffix /accesstoken , then the flow does not execute (although another conditional flow might).

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

Flow configuration elements

Step processing

The sequential ordering of conditional Flows is enforced by Apigee. Conditional Flows execute from top to bottom. The first conditional Flow whose condition evaluates to true is executed, and only one conditional Flow is executed.

For example, in the following Flow configuration, any inbound request that does not include the path suffix /first or /second will cause the ThirdFlow to execute, enforcing the policy called 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

"Resources" (resource files for use in API proxies) are scripts, code, and XSL transformations that can be attached to Flows using policies. These appear in the Scripts section of the API proxy editor in the Apigee UI.

See Managing resources for the supported resource types.

Resources can be stored in an API proxy, an environment, or an organization. In each case, a resource is referenced by name in a Policy. Apigee resolves the name by moving from the API proxy, to environment, to organization level.

A resource stored at the organization level can be referenced by Policies in any environment. A resource stored at the environment level can be referenced by Policies in that environment. A resource stored at the API proxy level can be referenced only by Policies in that API proxy.