Política ServiceCallout

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Ícone de política

O quê

A política ServiceCallout permite-lhe chamar outro serviço a partir do fluxo do proxy de API. Pode fazer chamadas para um serviço externo (como um ponto final de serviço RESTful externo) ou para serviços internos (como um proxy de API na mesma organização e ambiente).

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

  • Num exemplo de utilização externo, faz uma chamada para uma API de terceiros que é externa ao seu proxy. A resposta da API de terceiros é analisada e inserida na mensagem de resposta da sua API, enriquecendo e combinando os dados para os utilizadores finais da app. Também pode fazer um pedido através da política ServiceCallout no fluxo de pedidos e, em seguida, transmitir as informações na resposta para o TargetEndpoint do proxy de API.
  • Noutro exemplo de utilização, chama um proxy que está na mesma organização e ambiente que aquele a partir do qual está a ligar. Por exemplo, pode achar isto útil quando tem um proxy que oferece alguma funcionalidade discreta de baixo nível que um ou mais outros proxies vão consumir. Por exemplo, um proxy que exponha operações de criação/leitura/atualização/eliminação com um arquivo 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 suporta pedidos através de HTTP e HTTPS.

Exemplos

Chamada local para um proxy interno

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

Este exemplo cria um apelo a um proxy de API local (ou seja, um na mesma organização e ambiente) denominado data-manager, especificando o respetivo ponto final do proxy cujo nome é default.

URL como 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 alvo. A parte do protocolo do URL, http://, não pode ser especificada por uma variável. Além disso, tem de usar variáveis separadas para a parte do domínio do URL e para o resto do URL.

Geocodificação / definição de pedidos da 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 de pedido, pode defini-lo diretamente na política ServiceCallout. Neste exemplo, a política ServiceCallout define os valores de três parâmetros de consulta transmitidos ao serviço externo. Pode criar uma mensagem de pedido completa na política ServiceCallout que especifica uma carga útil, um tipo de codificação como application/xml, cabeçalhos, parâmetros de formulário, etc.

Segue-se outro exemplo em que o pedido é formado antes de atingir a política 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 pedido é extraído de uma variável denominada GeocodingRequest (que pode ser preenchida, por exemplo, por uma política AssignMessage). A mensagem de resposta é atribuída à variável denominada GeocodingResponse, onde está disponível para ser analisada por uma política ExtractVariables ou por código personalizado escrito em JavaScript ou Java. A política aguarda 30 segundos pela resposta da API Google Geocoding antes de atingir o tempo limite.

Servidores de destino de chamadas

<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 servidores de destino e fazer o equilíbrio de carga entre eles. Neste exemplo, a carga é distribuída por dois servidores de destino denominados httpbin e yahoo. Para ver informações sobre a configuração de servidores de destino para o seu proxy e a configuração do equilíbrio de carga, consulte o artigo Equilíbrio de carga entre servidores de back-end.

Acerca da política ServiceCallout

Existem muitos cenários em que pode usar uma política ServiceCallout no seu proxy de API. Por exemplo, pode configurar um proxy de API para fazer chamadas a um serviço externo para fornecer dados de geolocalização, críticas de clientes, artigos do catálogo de retalho de um parceiro, etc.

Normalmente, um callout é usado com outras duas políticas: AssignMessage e ExtractVariables.

  • Request: AssignMessage preenche a mensagem de pedido enviada para o serviço remoto.

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

A composição típica da política ServiceCallout envolve:

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

  2. Política ServiceCallout: faz referência 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 que o serviço de destino devolve.

    Para melhorar o desempenho, também pode colocar em cache as respostas ServiceCallout, conforme descrito em Como posso armazenar os resultados da política ServiceCallout na cache e, posteriormente, recuperá-los da cache?

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

Processamento de erros personalizado

Referência do elemento

Seguem-se os elementos e os atributos que pode configurar nesta 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 Presence
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:

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

 true Opcional
async

Esse atributo está obsoleto.

 false 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.
Presence Opcional
Tipo String

Elemento <Request>

Especifica a variável que contém a mensagem de pedido enviada do proxy de API para o outro serviço. A variável pode ser criada por uma política anterior no fluxo ou pode criá-la inline na política 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 etiquetas <Remove>, <Copy>, <Add> e <Set> é igual à da política AssignMessage.

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

No exemplo mais simples, passa uma variável que contém a mensagem de pedido preenchida anteriormente no fluxo do proxy de API:

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

Em alternativa, pode preencher a mensagem de pedido enviada para o serviço externo na própria política 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>
Predefinição Se omitir o elemento Request ou qualquer um dos respetivos atributos, o Apigee atribui os valores predefinidos seguintes:

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

Vejamos o que significam estes valores predefinidos. Primeiro, clearPayload=true significa que é criado um novo objeto de pedido cada vez que a política ServiceCallout é executada. Isto significa que o pedido e o caminho do URI do pedido nunca são reutilizados. Em segundo lugar, o nome da variável predefinido, servicecallout.request, é um nome reservado que é atribuído ao pedido se não fornecer um nome.

É importante conhecer este nome predefinido se estiver a usar a ocultação de dados. Se omitir o nome da variável, tem de adicionar servicecallout.request à configuração da máscara. Por exemplo, se quiser mascarar o cabeçalho de autorização para que não apareça nas sessões de depuração, adicionaria o seguinte à configuração de mascaramento para capturar o nome predefinido:

servicecallout.request.header.Authorization.
Presença Opcional.
Tipo N/A

Atributos

Atributo Descrição Predefinição Presença
variável

Nome da variável que vai conter a mensagem de pedido.

 servicecallout.request Opcional
clearPayload

Se true, a variável que contém a mensagem de pedido é limpa depois de a mensagem ser enviada para o destino HTTP para libertar a memória usada pela mensagem de pedido.

Defina a opção clearPayload como falsa apenas se a mensagem de pedido for necessária após a execução de ServiceCallout.

 verdadeiro Opcional

Elemento <Request>/<IgnoreUnresolvedVariables>

Quando definida como verdadeira, a política ignora qualquer erro de variável não resolvido no pedido.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
Predefinição falso
Presença Opcional
Tipo Booleano

Elemento <Response>

Inclua este elemento quando a lógica do proxy da API exigir a resposta da chamada remota para processamento adicional.

Quando este elemento está presente, especifica o nome da variável que vai conter a mensagem de resposta recebida do serviço externo. A resposta do destino é atribuída à variável apenas quando a política lê com êxito a resposta completa. Se a chamada remota falhar por qualquer motivo, a política devolve um erro.

Se este elemento for omitido, o proxy de API não aguarda uma resposta; a execução do fluxo do proxy de API continua com os passos do fluxo subsequentes. Além disso, para afirmar o óbvio, sem o elemento Response, a resposta do destino não está disponível para processamento por passos subsequentes, e não existe forma de o fluxo de proxy detetar uma falha na chamada remota. Uma utilização comum para omitir o elemento Response quando usa ServiceCallout: registar mensagens num sistema externo.

 <Response>calloutResponse</Response>
Predefinição NA
Presença Opcional
Tipo String

Elemento <Timeout>

O tempo, em milissegundos, que a política ServiceCallout aguarda por uma resposta do destino. Não pode definir este valor dinamicamente no tempo de execução. Se o ServiceCallout atingir um limite de tempo, é devolvido um HTTP 500, a política falha e o proxy de API entra num estado de erro, conforme descrito em Processamento de falhas.

<Timeout>30000</Timeout>
Predefinição 55 000 milissegundos (55 segundos), a predefinição do limite de tempo HTTP para o Apigee
Presença Opcional
Tipo Número inteiro

Elemento <HTTPTargetConnection>

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

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>
Predefinição N/A
Presença Obrigatória
Tipo N/A

Elemento <HTTPTargetConnection>/<Authentication>

Gera tokens Google OAuth 2.0 ou OpenID Connect emitidos pela Google para fazer chamadas autenticadas para serviços Google e serviços personalizados em execução em determinados produtos do Google Cloud, como as Cloud Functions e o Cloud Run. A utilização deste elemento requer passos de configuração e implementação descritos no artigo Usar a autenticação Google. Com a configuração adequada, a política cria um token de autenticação para si e adiciona-o ao pedido de serviço.

Os elementos secundários, GoogleAccessToken e GoogleIDToken, permitem-lhe configurar a política para gerar tokens do Google OAuth ou do OpenID Connect. Tem de escolher um destes elementos filho consoante o tipo de serviço que quer chamar.

A política ServiceCallout só suporta a chamada de serviços baseados em HTTP.

Predefinição N/A
Obrigatório? Opcional.
Tipo Tipo complexo
Elemento principal <HTTPTargetConnection>
Elementos subordinados <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>

Usar o GoogleAccessToken

O exemplo seguinte mostra o elemento GoogleAccessToken:

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

Usar GoogleIDToken

O exemplo seguinte mostra o elemento GoogleIDToken:

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

Usar HeaderName

O exemplo seguinte mostra o elemento HeaderName:

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

Usar LifetimeInSeconds

O exemplo seguinte 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

Nenhum.

Elemento secundário HeaderName

Por predefinição, quando existe uma configuração de autenticação, o Apigee gera um token de autorização e injeta-o no cabeçalho Authorization na mensagem enviada para o sistema de destino. O elemento HeaderName permite especificar o nome de um cabeçalho diferente para conter esse token de portador. Esta funcionalidade é particularmente útil quando o destino é um serviço do Cloud Run que usa o cabeçalho X-Serverless-Authorization. O cabeçalho Authorization, se estiver presente, é deixado inalterado e também enviado no pedido.

Predefinição N/A
Obrigatório? Não
Tipo String
Elemento principal <Authentication>
Elementos subordinados 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 de autorização gerado é adicionado, por predefinição, a um cabeçalho denominado X-Serverless-Authorization que é enviado para o sistema de destino. O cabeçalho Authorization, se estiver presente, é deixado inalterado e também enviado no pedido.

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

Com referência a variáveis

Neste exemplo, o token de autorização gerado é adicionado, por predefinição, a um cabeçalho denominado X-Serverless-Authorization que é enviado para o sistema de destino. Se my-variable tiver um valor, esse valor é usado em vez da string predefinida. O cabeçalho Authorization, se estiver presente, é deixado inalterado e também enviado no pedido.

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

Elemento secundário GoogleAccessToken

Gera tokens Google OAuth 2.0 para fazer chamadas autenticadas para serviços Google. Os tokens OAuth da Google podem ser usados para chamar muitos tipos de serviços Google, como o Cloud Logging e o Secret Manager.

Predefinição N/A
Obrigatório? Tem de estar presente o elemento subordinado GoogleAccessToken ou GoogleIDToken.
Tipo String
Elemento principal <Authentication>
Elementos subordinados <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 seguinte mostra o elemento GoogleAccessToken:

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

Exemplo 2

O exemplo seguinte mostra como estabelecer ligação ao Secret Manager para obter um segredo através da 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 seguinte mostra como fazer um apelo ao Cloud Run a partir da 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>

Define o âmbito do elemento secundário

Identifica os âmbitos a incluir na chave de acesso OAuth 2.0. Para mais informações, consulte o artigo Âmbitos do OAuth 2.0 para APIs Google. Pode adicionar um ou mais <Scope>elementos secundários a este elemento.

Predefinição N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <GoogleAccessToken>
Elementos subordinados <Scope>

Elemento secundário de âmbito

Especifica um âmbito da API Google válido. Para mais informações, consulte o artigo Âmbitos do OAuth 2.0 para APIs Google.

Predefinição N/A
Obrigatório? É necessário, pelo menos, um valor.
Tipo String
Elemento principal <Scopes>
Elementos subordinados Nenhum.

Elemento secundário LifetimeInSeconds

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

Predefinição 3600
Obrigatório? Opcional
Tipo Número inteiro
Elemento principal <GoogleAccessToken>
Elementos subordinados Nenhum.

Elemento secundário GoogleIDToken

Gera tokens OpenID Connect emitidos pela Google para fazer chamadas autenticadas aos serviços Google.

Predefinição N/A
Obrigatório? Tem de estar presente o elemento subordinado GoogleAccessToken ou GoogleIDToken.
Tipo String
Elemento principal <Authentication>
Elementos subordinados <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 seguinte mostra o elemento GoogleIDToken:

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

Elemento secundário de público-alvo

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 para um valor válido e useTargetUrl for true, o URL do destino (excluindo quaisquer parâmetros de consulta) é usado como público-alvo. Por predefiniçã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'/>
Predefinição N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <GoogleIDToken>
Elementos subordinados Nenhum.

Elemento secundário IncludeEmail

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

Predefinição falso
Obrigatório? Opcional
Tipo Booleano
Elemento principal <GoogleIDToken>
Elementos subordinados Nenhum.

Elemento <HTTPTargetConnection>/<URL>

O URL do serviço que está a ser chamado:

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

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

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

Em alternativa, defina uma parte do caminho do URL com uma variável:

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

Se quiser usar uma variável para especificar o domínio e a porta do URL, use uma variável apenas 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>
Predefinição N/A
Presença Obrigatória
Tipo String

Elemento <HTTPTargetConnection>/<SSLInfo>

A configuração de TLS/SSL para o serviço de back-end. Para obter ajuda sobre a configuração de TLS/SSL, consulte as Opções de configuração de TLS e "Configuração de TargetEndpoint de TLS/SSL" na referência de configuração do proxy de 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>
Predefinição N/A
Presença Opcional
Tipo N/A

Elemento <HTTPTargetConnection>/<Properties>

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

<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>
Predefinição N/A
Presença Opcional
Tipo N/A

Elemento <HTTPTargetConnection>/<LoadBalancer>

Chamar um ou mais servidores de destino e fazer o balanceamento de carga nos mesmos. Veja o exemplo de servidores de destino de chamadas na secção Exemplos. Veja também o artigo Balanceamento de carga entre servidores de back-end. Consulte também o artigo Target Endpoint/Server callout, que aborda formas de chamar servidores de destino a partir da política ServiceCallout e através de regras de encaminhamento.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
Predefinição N/A
Presença 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 ainda mais o destino, use os elementos <APIProxy> e <ProxyEndpoint> ou o elemento <Path>.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>
Predefinição N/A
Presença Obrigatória
Tipo N/A

Elemento <LocalTargetConnection>/<APIProxy>

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

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

Juntamente com o elemento <APIProxy>, inclua o elemento <ProxyEndpoint> para especificar o nome do ponto final do proxy que deve ser segmentado para a chamada.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>
Predefinição N/A
Presença Obrigatória
Tipo String

Elemento <LocalTargetConnection>/<ProxyEndpoint>

O nome do ponto final do proxy que deve ser o destino das chamadas. Este é um ponto final de proxy no proxy de API especificado com o elemento <APIProxy>.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
Predefinição N/A
Presença Opcional
Tipo N/A

Elemento <LocalTargetConnection>/<Path>

Um caminho para o ponto final que está a ser segmentado. O ponto final tem de referir-se a um proxy na mesma organização e ambiente que o proxy que está a fazer a chamada.

Use isto em vez de um par <APIProxy>/<ProxyEndpoint> quando não conhece ou não pode confiar no nome do proxy. O caminho pode ser um alvo fiável.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>
Predefinição N/A
Presença Opcional
Tipo N/A

Esquemas

Variáveis de fluxo

As variáveis de fluxo permitem o comportamento dinâmico das políticas e dos fluxos no tempo de execução, com base nos cabeçalhos HTTP, no conteúdo das mensagens ou no contexto do fluxo. As seguintes variáveis de fluxo predefinidas estão disponíveis após a execução de uma política ServiceCallout. Para mais informações sobre as variáveis de fluxo, consulte a Referência de variáveis de fluxo.

Os ServiceCallouts têm o seu próprio pedido e resposta, e pode aceder a esses dados através de variáveis. Uma vez que a mensagem principal está a usar os prefixos das variáveis request.* e response.*, use os prefixos myrequest.* e calloutResponse.* (as predefinições na configuração ServiceCallout) para obter dados de mensagens específicos do ServiceCallout. O primeiro exemplo na tabela seguinte mostra como obter cabeçalhos HTTP no ServiceCallout.

Variável Descrição

Segue-se um exemplo de como obter cabeçalhos de pedidos e respostas de ServiceCallout, de forma semelhante à obtenção de cabeçalhos do pedido e da resposta principais.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

onde calloutResponse é o nome da variável para a resposta no serviço Callout e myRequest é o nome da variável para o pedido. Por exemplo:

calloutResponse.header.Content-Length

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

Âmbito: do ServiceCallout em diante
Tipo: string
Autorização: leitura/escrita

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

Âmbito: a partir do pedido ServiceCallout
Tipo: string
Autorização: leitura/escrita

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

Âmbito: a partir do pedido ServiceCallout
Tipo: string
Autorização: leitura/escrita

O URL de destino de um ServiceCallout.

calloutResponse.content

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

Âmbito: a partir da resposta ServiceCallout
Tipo: string
Autorização: leitura/escrita

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

Âmbito: a partir do pedido ServiceCallout
Tipo: string
Autorização: leitura/escrita

O nome comum esperado do TargetEndpoint, conforme referido numa política ServiceCallout. Isto só é significativo quando o TargetEndpoint se refere a um ponto final TLS/SSL.
servicecallout.{policy-name}.failed

Âmbito: da resposta ServiceCallout em diante
Tipo: booleano
Autorização: leitura/escrita

Valor booleano que indica se a política foi bem-sucedida (falso) ou falhou (verdadeiro).

Erros

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.servicecallout.ExecutionFailed 500

This error can occur when:

  • The policy is asked to handle input that is malformed or otherwise invalid.
  • The backend target service returns an error status (by default, 4xx or 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 The Request variable specified in the policy is not of type Message. For example, if it's a string or other non-message type, you'll see this error.
steps.servicecallout.RequestVariableNotRequestMessageType 500 The Request variable specified in the policy is not of type RequestMessage. For example, if it's a Response type, you'll see this error.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> is enabled but useTargetUrl is set to false and no value is provided to <Audience> either directly or through reference at the time of error.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 This error can happen if the API proxy is configured with the <Authentication> element. Possible causes include:
  • The service account deployed with the proxy:
    • does not exist in your project
    • has been disabled
    • (Apigee hybrid only) has not granted the roles/iam.serviceAccountTokenCreator role on the apigee-runtime service account.
  • The IAMCredentials API is disabled in the source project of the apigee-runtime service account.
  • The <GoogleAccessToken> element is used and one or more invalid scopes are provided. For example, look for typos or empty scopes.

    • For Apigee hybrid only, check the runtime container's log and search for GoogleTokenGenerationFailure to find more detailed error messages that may help with debugging the problem.

    Deployment errors

    These errors can occur when you deploy a proxy containing this policy.

    Error name Cause Fix
    URLMissing The <URL> element inside <HTTPTargetConnection> is missing or empty.
    ConnectionInfoMissing This error happens if the policy does not have an <HTTPTargetConnection> or <LocalTargetConnection> element.
    InvalidTimeoutValue This error happens if the <Timeout> value is negative or zero.
    FAILED_PRECONDITION This error happens if the service account is missing when the proxy is configured with the <Authentication> tag.

    For example: 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED This error happens if there is a permission problem with the service account if the proxy is configured with the <Authentication> tag. Possible causes:
    • The service account does not exist.
    • The service account was not created in the same Google Cloud project as the Apigee organization.
    • The deployer does have iam.serviceAccounts.actAs permission on the service account. For details, see About service account permissions.

    Fault variables

    These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

    Variables Where Example
    fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. servicecallout.SC-GetUserData.failed = true

    Example error response

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

    Example fault rule

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

    Tópicos relacionados