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 seguinte descreve os atributos comuns a todos os elementos principais de políticas:

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

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres.

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

 N/A Obrigatória
continueOnError

Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas.

Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja 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 é aplicada, mesmo que permaneça associada a um fluxo.

 verdadeiro Opcional
async

Este atributo foi descontinuado.

 falso Descontinuado

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
Predefinição

N/A

Se omitir este elemento, é 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 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

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Erros de tempo de execução

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

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

Este erro pode ocorrer quando:

  • A política é solicitada para processar entradas com um formato incorreto ou que são inválidas.
  • O serviço de destino de back-end devolve um estado de erro (por predefinição, 4xx ou 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 A variável Request especificada na política não é do tipo Message. Por exemplo, se for uma string ou outro tipo que não seja de mensagem, é apresentado este 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, é apresentado este erro.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> está ativado, mas useTargetUrl está definido como falso e não é fornecido nenhum valor a <Audience> diretamente ou através de referência no momento do erro.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 Este erro pode ocorrer se o proxy da API estiver configurado com o elemento <Authentication>. As causas possíveis incluem:
  • A conta de serviço implementada com o proxy:
    • não existe no seu projeto
    • foi desativada
    • (Apenas para o Apigee híbrido) Não concedeu a função roles/iam.serviceAccountTokenCreator na 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 são fornecidos um ou mais âmbitos inválidos. Por exemplo, procure gralhas ou âmbitos vazios.

    • Apenas para o Apigee hybrid, verifique o registo do contentor de tempo de execução e procure GoogleTokenGenerationFailure para encontrar mensagens de erro mais detalhadas que podem ajudar a depurar o problema.

    Erros de implementação

    Estes erros podem ocorrer quando implementa um proxy que contém esta política.

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

    Por exemplo: 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED Este erro ocorre se houver um problema de autorização com a conta de serviço se o proxy estiver configurado com a etiqueta <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 implementador tem a autorização iam.serviceAccounts.actAs na conta de serviço. Para ver detalhes, consulte o artigo Acerca das autorizações da conta de serviço.

    Variáveis de falha

    Estas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

    Variáveis Onde Exemplo
    fault.name="fault_name" fault_name é o nome da falha, conforme indicado na tabela Erros de tempo 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 utilizador da política que gerou 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>

    Tópicos relacionados