Política ServiceCallout

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

Confira a documentação da Apigee Edge.

Ícone da política

O que

A política ServiceCallout permite chamar outro serviço a partir do fluxo de proxy da API. É possível fazer chamadas para um serviço externo, como um endpoint de serviço RESTful externo, ou para serviços internos, como um proxy de API na mesma organização e ambiente.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

  • Em um caso de uso externo, você faz uma chamada para uma API de terceiros externa ao seu proxy. A resposta da API de terceiros é analisada e inserida na mensagem de resposta da sua API, enriquecendo e mascarando os dados dos usuários finais do app. Também é possível fazer uma solicitação usando a política ServiceCallout no fluxo de solicitação e passar as informações na resposta para o TargetEndpoint do proxy de API.
  • Em outro caso de uso, chame um proxy que esteja na mesma organização e ambiente do qual você está chamando. Isso pode ser útil, por exemplo, quando você tem um proxy que oferece alguma funcionalidade discreta de baixo nível que um ou mais proxies consumirão. Por exemplo, um proxy que expõe operações de criação/leitura/atualização/exclusão com um armazenamento de dados de back-end pode ser o proxy de destino para vários outros proxies que expõem os dados aos clientes.

A política aceita solicitações por HTTP e HTTPS.

Amostras

Chamada local para um proxy interno

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

Neste exemplo, é criada uma chamada para um proxy de API local (ou seja, na mesma organização e ambiente) denominada data-manager, especificando o endpoint do proxy com o nome default.

URL como uma variável

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

Este exemplo usa uma variável no URL para preencher dinamicamente o URL do destino. A parte de protocolo do URL, http://, não pode ser especificada por uma variável. Além disso, use variáveis separadas para a parte do domínio do URL e para o restante do URL.

Solicitação de geocodificação/definição do Google

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Em vez de usar uma política, como a política AssignMessage, para criar o objeto da solicitação, você pode defini-la diretamente na política ServiceCalling. Neste exemplo, a política ServiceCallout define os valores de três parâmetros de consulta passados para o serviço externo. É possível criar uma mensagem de solicitação inteira na política ServiceCallout que especifica um payload, um tipo de codificação, como application/xml, cabeçalhos, parâmetros de formulário etc.

Veja outro exemplo em que a solicitação é formada antes de alcançar a política de ServiceCallout.

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

O conteúdo da mensagem de solicitação é extraído de uma variável chamada GeocodingRequest, que pode ser preenchida, por exemplo, por uma política "AssignMessage". A mensagem de resposta é atribuída à variável chamada GeocodingResponse, em que fica disponível para ser analisada por uma política de ExtractVariables ou por código personalizado escrito em JavaScript ou Java. A política aguarda 30 segundos para a resposta da API Google Geocoding antes de expirar.

Chamar servidores de destino

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

Esta política usa o atributo LoadBalancer para chamar os servidores de destino e fazer o balanceamento de carga entre eles. Neste exemplo, a carga é distribuída em dois servidores de destino chamados httpbin e yahoo. Consulte Balanceamento de carga entre servidores de back-end para mais informações sobre como configurar servidores de destino para o proxy e como configurar o balanceamento de carga.

Sobre a política de ServiceCallout

Há muitos cenários em que é possível usar uma política de ServiceCallout no proxy de API. Por exemplo, você pode configurar um proxy de API para fazer chamadas a um serviço externo para fornecer dados de geolocalização, avaliações de clientes, itens do catálogo de varejo de um parceiro e assim por diante.

Geralmente, uma chamada é usada com duas outras políticas: AssignMessage e ExtractVariables.

  • Solicitação: a opção AssignMessage preenche a mensagem de solicitação enviada ao serviço remoto.

  • Resposta: ExtractVariables analisa a resposta e extrai o conteúdo específico.

A composição comum da política de ServiceCallout envolve:

  1. Política AssignMessage: cria uma mensagem de solicitação, preenche os cabeçalhos HTTP, os parâmetros de consulta, define o verbo HTTP etc.

  2. Política ServiceCallout: refere-se a uma mensagem criada pela política AssignMessage, define um URL de destino para a chamada externa e define um nome para o objeto de resposta retornado pelo serviço de destino.

    Para melhorar o desempenho, você também pode armazenar em cache as respostas do ServiceCallout, conforme descrito em Como posso armazenar os resultados da política ServiceCalling no cache? e, mais tarde, recuperá-los do cache?

  3. Política de ExtractVariables: normalmente, define uma expressão JSONPath ou XPath que analisa a mensagem gerada pela ServiceCallout. Em seguida, a política define as variáveis que contêm os valores analisados da resposta da ServiceCallout.

Como resolver erros personalizados

Referência de elemento

Veja a seguir elementos e atributos que podem ser configurados com esta política:

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleAccessToken>
            <Scopes>
              <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
            </Scopes>
            <LifetimeInSeconds ref="{variable}">3600</LifetimeInSeconds>
          </GoogleAccessToken>
        </Authentication>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleIDToken>
            <Audience ref="{variable}" useTargetUrl="BOOLEAN">{hostname}</Audience>
            <IncludeEmail ref="{variable}">true</IncludeEmail>
          </GoogleIDToken>
        </Authentication>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

Atributos <ServiceCallout>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo Descrição Padrão Presença
name

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres.

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

 N/A Obrigatório
continueOnError

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

Defina como true para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também:

 falso Opcional
enabled

Defina como true para aplicar a política.

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

 verdadeiro Opcional
async

Esse atributo está obsoleto.

 falso Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

<DisplayName>Policy Display Name</DisplayName>
Padrão

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.
Presença Opcional
Tipo String

Elemento <Request>

Especifica a variável que contém a mensagem de solicitação enviada do proxy de API para o outro serviço. A variável pode ser criada por uma política anterior no fluxo, ou você pode criá-la inline na política de ServiceCallout.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

A sintaxe das tags <Remove>, <Copy>, <Add> e <Set> é a mesma que a da política AssignMessage.

A política retornará um erro se a mensagem de solicitação não puder ser resolvida ou for de um tipo de mensagem de solicitação inválido.

No exemplo mais simples, você transmite uma variável contendo a mensagem de solicitação que foi preenchida anteriormente no fluxo do proxy de API:

<Request clearPayload="true" variable="myRequest"/>

Também é possível preencher a mensagem de solicitação enviada ao serviço externo na própria política de ServiceCallout:

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
Padrão Se você omitir o elemento Request ou qualquer um dos atributos dele, a Apigee atribuirá os seguintes valores padrão:

<Request clearPayload="true" variable="servicecallout.request"/>

Vejamos o que esses valores padrão significam. Primeiro, clearPayload=true significa que um novo objeto de solicitação é criado sempre que a política ServiceCallout é executada. Isso significa que a solicitação e o caminho de URI da solicitação nunca são reutilizados. Segundo, o nome da variável padrão, servicecallout.request, é um nome reservado atribuído à solicitação se você não especificar um nome.

É importante saber sobre esse nome padrão se você estiver usando mascaramento de dados. Se você omitir o nome da variável, será necessário adicionar servicecallout.request à sua configuração de máscara. Por exemplo, se você quiser mascarar o cabeçalho Autorização para que ele não apareça nas sessões de depuração, adicione o código a seguir à configuração de mascaramento para capturar o nome padrão:

servicecallout.request.header.Authorization.
Presence Opcional.
Tipo N/A

Atributos

Atributo Descrição Padrão Presence
variável

Nome da variável que conterá a mensagem de solicitação.

 servicecallout.request Opcional
clearPayload

Se true, a variável que contém a mensagem de solicitação será apagada depois que a solicitação for enviada ao destino HTTP para liberar a memória usada pela mensagem de solicitação.

Defina a opção clearPayload como "false" somente se a mensagem de solicitação for necessária depois que a ServiceCallout for executada.

 true Opcional

Elemento <Request>/<IgnoreUnresolvedVariables>

Quando definido como true, a política ignora qualquer erro de variável não resolvido na solicitação.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
Padrão false
Presence Opcional
Tipo Booleano

Elemento <Response>

Inclua esse elemento quando a lógica do proxy de API requer a resposta da chamada remota para processamento adicional.

Quando esse elemento está presente, ele especifica o nome da variável que conterá a mensagem de resposta recebida do serviço externo. A resposta do destino é atribuída à variável somente quando a resposta inteira é lida pela política. Se a chamada remota falhar por qualquer motivo, a política retornará um erro.

Se esse elemento for omitido, o proxy de API não aguardará a resposta. A execução do fluxo do proxy de API continua com todas as etapas subsequentes do fluxo. Além disso, para declarar o óbvio, sem um elemento Response, a resposta do destino não está disponível para processamento nas etapas subsequentes e não há como o fluxo de proxy detectar uma falha na chamada remota. Um uso comum para omitir o elemento Response ao usar ServiceCallout é registrar as mensagens em um sistema externo.

 <Response>calloutResponse</Response>
Padrão NA
Presence Opcional
Tipo String

Elemento <Timeout>

O tempo em milésimos de segundo em que a política de ServiceCallout aguardará uma resposta do destino. Não é possível definir esse valor dinamicamente no ambiente de execução. Se a ServiceCallout atingir um tempo limite, um HTTP 500 será retornado, a política falhará e o proxy de API entrará em um estado de erro, conforme descrito em Como solucionar falhas.

<Timeout>30000</Timeout>
Padrão 55.000 milissegundos (55 segundos), a configuração de tempo limite HTTP padrão da Apigee
Presence Opcional
Tipo Número inteiro

Elemento <HTTPTargetConnection>

Fornece detalhes de transporte, como propriedades URL, TLS/SSL e HTTP. Consulte a referência de configuração do <TargetEndpoint>.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>
Padrão N/A
Presence Obrigatório
Tipo N/A

<HTTPTargetConnection>/<Authentication> element

Gera tokens do Google OAuth 2.0 ou do OpenID Connect emitidos pelo Google para fazer chamadas autenticadas para serviços do Google e serviços personalizados em execução em determinados produtos do Google Cloud. , como Cloud Functions e Cloud Run. O uso desse elemento requer etapas de configuração e implantação descritas em Como usar a autenticação do Google. Com a configuração adequada, a política cria um token de autenticação para você e o adiciona à solicitação de serviço.

Os elementos filhos, GoogleAccessToken e GoogleIDToken, permitem configurar a política para gerar tokens do Google OAuth ou do OpenID Connect. Você precisa escolher um desses elementos filhos, dependendo do tipo de serviço que quer chamar.

A política ServiceCallout é compatível apenas com a chamada de serviços baseados em HTTP.

Padrão N/A
Obrigatório? Opcional.
Tipo Tipo complexo
Elemento pai <HTTPTargetConnection>
Elemento filho <HeaderName>
<GoogleAccessToken>
<GoogleIDToken>

O elemento Authentication usa a seguinte sintaxe:

Sintaxe

<ServiceCallout>
...
  <HTTPTargetConnection>
    <Authentication>
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
        <!-- NOTE: The default value for LifetimeInSeconds is 3600. Change the default only
        if you want to limit the risk of leaked access tokens or improve performance. -->
        <LifetimeInSeconds ref="{variable}">INTEGER</LifetimeInSeconds>
      </GoogleAccessToken>

    --OR--
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </HTTPTargetConnection>
</ServiceCallout>

Como usar o GoogleAccessToken

O exemplo a seguir mostra o elemento GoogleAccessToken:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Como usar o GoogleIDToken

O exemplo a seguir mostra o elemento GoogleIDToken:

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>false</IncludeEmail>
  </GoogleIDToken>
</Authentication>

Usando HeaderName

O exemplo a seguir mostra o elemento HeaderName:

  <Authentication>
    <HeaderName>X-Serverless-Authorization</HeaderName>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
    </GoogleAccessToken>
  </Authentication>

Como usar LifeInSeconds

O exemplo a seguir mostra o elemento HeaderName:

  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
      <LifetimeInSeconds ref="variable">3600</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>

Atributos

Nenhuma.

Elemento filho HeaderName

Por padrão, quando uma configuração de autenticação está presente, a Apigee gera um token do portador e o injeta no cabeçalho Authorization na mensagem enviada ao sistema de destino. O elemento HeaderName permite especificar o nome de um cabeçalho diferente para armazenar o token do portador. Esse recurso é particularmente útil quando o destino é um serviço do Cloud Run que usa o cabeçalho X-Serverless-Authorization. O cabeçalho Authorization, se presente, não é modificado e também é enviado na solicitação.

Padrão N/A
Obrigatório? Não
Tipo String
Elemento pai <Authentication>
Elemento filho Nenhum

O elemento HeaderName usa a seguinte sintaxe:

Sintaxe

<ServiceCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

Com string estática

Neste exemplo, o token do portador gerado é adicionado, por padrão, 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.

<Authentication>
  <HeaderName>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Com referência de variável

Neste exemplo, o token do portador gerado é adicionado, por padrão, a um cabeçalho chamado X-Serverless-Authorization, que é enviado ao sistema de destino. Se my-variable tiver um valor, esse valor será usado no lugar da string padrão. O cabeçalho Authorization, se presente, não é modificado e também é enviado na solicitação.

<Authentication>
  <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Elemento filho GoogleAccessToken

gera tokens Google OAuth 2.0 (em inglês) para fazer chamadas autenticadas aos serviços do Google. Os tokens OAuth do Google podem ser usados para chamar muitos tipos de serviços do Google, como Cloud Logging e Gerenciador de secrets.

Padrão N/A
Obrigatório? O elemento filho GoogleAccessToken ou GoogleIDToken precisa estar presente.
Tipo String
Elemento pai <Authentication>
Elemento filho <Scopes>
<LifetimeInSeconds>

O elemento GoogleAccessToken usa a seguinte sintaxe:

Sintaxe

<ServiceCallout>
...
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>SCOPE_1</Scope>
        ...
      </Scopes>
      <!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing
      the default unless you want to limit the risk of leaked access tokens or improve performance. -->
      <LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

Exemplo 1

O exemplo a seguir mostra o elemento GoogleAccessToken:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Exemplo 2

O exemplo a seguir mostra como se conectar ao gerenciador de secrets para recuperar um secret usando a política ServiceCallout. 

<ServiceCallout name="ServiceCallout-sm">
  <Response>SecretManagerResponse</Response>
  <Timeout>30000</Timeout>
  <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>
</ServiceCallout>

Exemplo 3

O exemplo a seguir mostra como fazer uma chamada para o Cloud pela política ServiceCallout. 

<ServiceCallout name="ServiceCallout-CloudRun">
  <Response>CloudRunResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
      </GoogleIDToken>
    </Authentication>
    <URL>https://cloudrun-hostname.a.run.app/test</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Elemento filho Scopes

Identifica os escopos a serem incluídos no token de acesso do OAuth 2.0. Para mais informações, consulte Escopos do OAuth 2.0 para APIs do Google. É possível adicionar um ou mais elementos filhos <Scope> nesse elemento.

Padrão N/A
Obrigatório? Obrigatório
Tipo String
Elemento pai <GoogleAccessToken>
Elemento filho <Scope>

Elemento filho Scope

Especifica um escopo válido de API do Google. Para mais informações, consulte Escopos do OAuth 2.0 para APIs do Google.

Padrão N/A
Obrigatório? Ao menos um valor é obrigatório.
Tipo String
Elemento pai <Scopes>
Elemento filho Nenhuma.

Elemento filho LifetimeInSeconds

Especifica a duração do token de acesso em segundos.

Padrão 3600
Obrigatório? Opcional
Tipo Número inteiro
Elemento pai <GoogleAccessToken>
Elemento filho Nenhuma.

Elemento filho GoogleIDToken

gera tokens OpenID Connect emitidos pelo Google para fazer chamadas autenticadas aos serviços do Google;

Padrão N/A
Obrigatório? O elemento filho GoogleAccessToken ou GoogleIDToken precisa estar presente.
Tipo String
Elemento pai <Authentication>
Elemento filho <Audience>
<IncludeEmail>

O elemento GoogleIDToken usa a seguinte sintaxe:

Sintaxe

<ServiceCallout>
...
  <Authentication>
    <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
    </GoogleIDToken>
  </Authentication>
</ServiceCallout>

Exemplo 1

O exemplo a seguir mostra o elemento GoogleIDToken:

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>true</IncludeEmail>
  </GoogleIDToken>
</Authentication>

Elemento filho Audience

O público-alvo do token de autenticação gerado, como a API ou a conta à qual o token concede acesso.

Se o valor de Audience estiver vazio ou a variável ref não for resolvida como um valor válido e useTargetUrl for true, o URL de destino (excluindo qualquer parâmetro de consulta) é usado como público-alvo. Por padrão, useTargetUrl é false. 

<Audience>explicit-audience-value-here</Audience>

or:

<Audience ref='variable-name-here'/>

or:

<Audience ref='variable-name-here' useTargetUrl='true'/>

or:

<Audience useTargetUrl='true'/>
Padrão N/A
Obrigatório? Obrigatório
Tipo String
Elemento pai <GoogleIDToken>
Elemento filho Nenhuma.

Elemento filho IncludeEmail

Se definido como true, o token de autenticação gerado conterá as declarações email e email_verified da conta de serviço.

Padrão false
Obrigatório? Opcional
Tipo Booleano
Elemento pai <GoogleIDToken>
Elemento filho Nenhuma.

Elemento <HTTPTargetConnection>/<URL>

O URL do serviço que está sendo chamado:

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

Você pode fornecer parte do URL dinamicamente com uma variável. No entanto, a parte de protocolo do URL, http:// abaixo, não pode ser especificada por uma variável. No próximo exemplo, você usa uma variável para especificar o valor de um parâmetro de consulta:

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

Se preferir, defina uma parte do caminho do URL com uma variável:

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

Se você quiser usar uma variável para especificar o domínio e a porta do URL, use uma variável somente para o domínio e a porta e uma segunda variável para qualquer outra parte do URL:

<URL>http://{request.dom_port}/{request.resourcePath}</URL>
Padrão N/A
Presence Obrigatório
Tipo String

Elemento <HTTPTargetConnection>/<SSLInfo>

A configuração de TLS/SSL para o serviço de back-end. Para ter ajuda sobre a configuração de TLS/SSL, consulte Opções para configurar TLS e "Configuração de endpoint de destino TLS/SSL" na referência de configuração do proxy da API.

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>
Padrão N/A
Presence Opcional
Tipo N/A

Elemento <HTTPTargetConnection>/<Properties>

Propriedades de transporte HTTP para o serviço de back-end. Para mais informações, consulte a Referência das propriedades de endpoint.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>
Padrão N/A
Presence Opcional
Tipo N/A

Elemento <HTTPTargetConnection>/<LoadBalancer>

Chame um ou mais servidores de destino e faça o balanceamento de carga neles. Veja o exemplo de Servidores de destino de chamada na seção "Amostras". Consulte também Balanceamento de carga entre servidores de back-end. Consulte também endpoint de destino/frase de destaque do servidor que discute maneiras de chamar servidores de destino a partir da política ServiceCalling e usando regras de rota

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
Padrão N/A
Presence Opcional
Tipo N/A

Elemento <LocalTargetConnection>

Especifica um proxy local, ou seja, um proxy na mesma organização e ambiente, como o destino das chamadas de serviço.

Para especificar o destino em mais detalhes, use os elementos <APIProxy> e <ProxyEndpoint> ou o elemento <Path>.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>
Padrão N/A
Presence Obrigatório
Tipo N/A

Elemento <LocalTargetConnection>/<APIProxy>

O nome de um proxy de API que é o destino de uma chamada local. O proxy precisa estar na mesma organização e ambiente que o proxy que está fazendo a chamada.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

Junto com o elemento <APIProxy>, inclua o elemento <ProxyEndpoint> para especificar o nome do endpoint de proxy que precisa ser direcionado para a chamada.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>
Padrão N/A
Presence Obrigatório
Tipo String

Elemento <LocalTargetConnection>/<ProxyEndpoint>

O nome do endpoint do proxy que precisa ser o destino das chamadas. Esse é um endpoint de proxy no proxy de API especificado com o elemento <APIProxy>.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
Padrão N/A
Presence Opcional
Tipo N/A

Elemento <LocalTargetConnection>/<Path>

Um caminho para o endpoint que está sendo direcionado. O endpoint precisa se referir a um proxy na mesma organização e ambiente que o proxy que está fazendo a chamada.

Use-o em vez de um par <APIProxy>/<ProxyEndpoint> quando você não souber o nome do proxy, ou não puder confiar nele. O caminho pode ser um destino confiável.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>
Padrão N/A
Presence Opcional
Tipo N/A

Esquemas

Variáveis de fluxo

As variáveis de fluxo permitem o comportamento dinâmico de políticas e fluxos no ambiente de execução, com base em cabeçalhos HTTP, conteúdo de mensagens ou contexto de fluxo. As variáveis de fluxo predefinidas a seguir estarão disponíveis depois que uma política de ServiceCallout for executada. Para mais informações sobre variáveis de fluxo, consulte a esta referência.

As ServiceCallouts têm uma solicitação e uma resposta próprias, e é possível acessar esses dados por meio de variáveis. Como a mensagem principal está usando os prefixos de variável request.* e response.*, use os prefixos myrequest.* e calloutResponse.* (os padrões na configuração da ServiceCallout) para acessar os dados da mensagem específicos da ServiceCallout. O primeiro exemplo na tabela a seguir mostra como você recebe os cabeçalhos HTTP na ServiceCallout.

Variável Descrição

Veja abaixo um exemplo de como conseguir os cabeçalhos de solicitação e de ServiceCallout da mesma forma como você faz com os cabeçalhos da solicitação principal e da resposta.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

em que calloutResponse é o nome da variável da resposta na chamada de serviço, e myRequest é o nome da variável da solicitação. Exemplo:

calloutResponse.header.Content-Length

retorna o cabeçalho Content-Length da resposta da ServiceCallout.

Escopo: com base no encaminhamento da ServiceCallout
Tipo: String
Permissão: Leitura/gravação

Um cabeçalho de mensagem na solicitação ou resposta de ServiceCallout. Por exemplo, se o destino do proxy de API for http://example.com e o destino da ServiceCallout for http://mocktarget.apigee.net, essas variáveis serão os cabeçalhos da chamada para http://mocktarget.apigee.net.
servicecallout.requesturi

Escopo: com base no encaminhamento da solicitação de ServiceCallout
Tipo: String
Permissão: Leitura/gravação

O URI TargetEndpoint de uma política ServiceCallout. O URI é o URL TargetEndpoint sem a especificação do protocolo e do domínio.
servicecallout.{policy-name}.target.url

Escopo: com base no encaminhamento da solicitação de ServiceCallout
Tipo: String
Permissão: Leitura/gravação

O URL de destino de uma ServiceCallout.

calloutResponse.content

em que calloutResponse é o <Response>nome da variável na configuração da ServiceCallout.

Escopo: com base no encaminhamento da resposta da ServiceCallout
Tipo: String
Permissão: Leitura/gravação

O corpo da resposta da ServiceCallout.
servicecallout.{policy-name}.expectedcn

Escopo: com base no encaminhamento da solicitação de ServiceCallout
Tipo: String
Permissão: Leitura/gravação

O nome comum esperado do TargetEndpoint, conforme mencionado em uma política ServiceCallout. Isso é significativo somente quando o TargetEndpoint se refere a um endpoint TLS/SSL.
servicecallout.{policy-name}.failed

Escopo: com base no encaminhamento da resposta da ServiceCallout
Tipo: Booleano
Permissão: Leitura/gravação

Booleano que indica se a política foi concluída, é falsa ou falhou.

Erros

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Código de falha Status HTTP Causa Corrigir
steps.servicecallout.ExecutionFailed 500

Esse erro pode ocorrer quando:

  • a política precisa lidar com entradas malformadas ou inválidas.
  • O serviço de destino de back-end retorna um status de erro (por padrão, 4xx ou 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 A variável Request especificada na política não é do tipo Message. Por exemplo, no caso de uma string ou outro tipo de mensagem que não é uma mensagem, você vê esse erro.
steps.servicecallout.RequestVariableNotRequestMessageType 500 A variável Request especificada na política não é do tipo RequestMessage. Por exemplo, se for um tipo de resposta, você verá esse erro.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> está ativado, mas useTargetUrl está definido como falso, e nenhum valor é fornecido para <Audience> diretamente ou por referência no momento do erro.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 Esse erro pode acontecer se o proxy de API estiver configurado com o elemento <Authentication>. Estas são as possíveis causas:
  • A conta de serviço implantada com o proxy:
    • não existe em seu projeto
    • foi desativado
    • (Somente híbridos da Apigee) não concedeu o papel roles/iam.serviceAccountTokenCreator à conta de serviço apigee-runtime.
  • A API IAMCredentials está desativada no projeto de origem da conta de serviço apigee-runtime.
  • O elemento <GoogleAccessToken> é usado e um ou mais escopos inválidos são fornecidos. Por exemplo, procure erros de digitação ou escopos vazios.

    • Somente para a Apigee híbrida, verifique o registro do contêiner de ambiente de execução e procure GoogleTokenGenerationFailure para encontrar mensagens de erro mais detalhadas que podem ajudar na depuração do problema.

    Erros na implantação

    Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

    Nome do erro Causa Corrigir
    URLMissing O elemento <URL> dentro de <HTTPTargetConnection> está ausente ou vazio.
    ConnectionInfoMissing Esse erro ocorrerá se a política não tiver um elemento <HTTPTargetConnection> ou <LocalTargetConnection>.
    InvalidTimeoutValue Este erro ocorrerá se o valor <Timeout> for negativo ou zero.
    FAILED_PRECONDITION Esse erro ocorrerá se a conta de serviço estiver ausente quando o proxy estiver configurado com a tag <Authentication>.

    Exemplo: 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED Esse erro ocorrerá se houver um problema de permissão com a conta de serviço se o proxy estiver configurado com a tag <Authentication>. Causas possíveis:
    • A conta de serviço não existe.
    • A conta de serviço não foi criada no mesmo projeto do Google Cloud que a organização da Apigee.
    • O implantador tem a permissão iam.serviceAccounts.actAs na conta de serviço. Para ver detalhes, consulte Sobre as permissões da conta de serviço.

    Variáveis de falha

    Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

    Variáveis Onde Exemplo
    fault.name="fault_name" fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name é o nome especificado pelo usuário da política que causou a falha. servicecallout.SC-GetUserData.failed = true

    Exemplo de resposta de erro

    {
   "fault":{
      "detail":{
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]:
            request variable data_str value is not of type Message"
   }
}

    Exemplo de regra de falha

    <FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

    Temas relacionados