Política de ExternalCallout

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 ExternalCallout permite-lhe enviar pedidos gRPC ao seu servidor gRPC para implementar um comportamento personalizado que não é suportado pelas políticas do Apigee. No código do servidor, pode aceder e modificar facilmente as variáveis de fluxo no fluxo de um proxy.

O Apigee comunica com um servidor gRPC através de uma política ExternalCallout através de uma API. O Apigee usa a API para enviar variáveis de fluxo para o servidor gRPC. No seu servidor gRPC, pode ler e, consoante a variável, modificar as variáveis de fluxo indicadas na página de referência Variáveis de fluxo, bem como variáveis adicionais que especifica no XML da política.

Se configurar o servidor gRPC com o Apigee e incluir esta política num proxy, o Apigee processa os pedidos de API da seguinte forma:

  1. O Apigee envia uma mensagem que contém as variáveis de fluxo para o seu servidor gRPC.
  2. O código do servidor gRPC é executado, acedendo e modificando as variáveis conforme definido no código. Em seguida, o servidor gRPC envia uma resposta que contém todas as variáveis de fluxo de volta para o Apigee.
  3. O Apigee lê a resposta do seu servidor gRPC. Se forem adicionadas variáveis ou as variáveis de fluxo modificáveis forem modificadas, estas são atualizadas no Apigee.

Esta política é uma política padrão e pode ser implementada em qualquer tipo de ambiente. Para obter informações sobre os tipos de políticas e a disponibilidade com cada tipo de ambiente, consulte Tipos de políticas.

Para saber mais sobre o envio de pedidos gRPC, consulte os seguintes links:

<ExternalCallout>

Define uma política ExternalCallout.

<ExternalCallout async="true" continueOnError="true" enabled="true" name="EC">

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo Predefinição Obrigatório? Descrição
name N/A Obrigatório

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.
continueOnError falso Opcional 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:
enabled verdadeiro Opcional 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 anexada a um fluxo.
async   falso Descontinuado Este atributo foi descontinuado.

A tabela seguinte descreve os elementos secundários de <ExternalCallout>.

Elemento secundário Obrigatória Descrição
<TimeoutMs> Obrigatória O limite de tempo do pedido em milissegundos para pedidos gRPC.
<GrpcConnection> Obrigatória Especifica o nome de um TargetServer existente para ser o servidor gRPC para o qual enviar pedidos.
<Configurations> Opcional Permite-lhe configurar vários aspetos da política ExternalCallout, incluindo os elementos <Property> e <FlowVariable>.

Exemplo 1

Estão disponíveis exemplos funcionais de ExternalCallout em Amostras de chamadas externas no GitHub.

O exemplo seguinte ilustra uma configuração da política ExternalCallout.

<ExternalCallout enabled="true" continueOnError="false" name="ExternalCallout-1">
  <DisplayName>External Callout 1</DisplayName>
  <TimeoutMs>5000</TimeoutMs>
  <GrpcConnection>
    <Server name="external-target-server"/>
  </GrpcConnection>
  <Configurations>
    <Property name="with.request.content">true</Property>
    <Property name="with.request.headers">false</Property>
    <Property name="with.response.content">true</Property>
    <Property name="with.response.headers">false</Property>
    <FlowVariable>example1.flow.variable</FlowVariable>
    <FlowVariable>example2.flow.variable</FlowVariable>
  </Configurations>
<ExternalCallout>

O exemplo envia um pedido a um servidor gRPC externo representado pelo TargetServer denominado external-target-server, com as seguintes configurações:

  • <Property>: Inclua o conteúdo do pedido e da resposta, mas não os cabeçalhos do pedido e da resposta, no pedido enviado para o servidor gRPC.
  • <FlowVariable>: Inclua variáveis de fluxo adicionais example1.flow.variable e example2.flow.variable, especificadas pelos elementos FlowVariable, no pedido enviado para o servidor gRPC.

Exemplo 2

No exemplo seguinte, o atributo useTargetUrl do elemento Audience está definido como true. Quando useTargetUrl é true, o nome do anfitrião do servidor de destino gRPC é usado como público-alvo. Por exemplo, se o anfitrião do servidor for my-grpc-server-java.a.run.app, o público-alvo usado será https://my-grpc-server-java.a.run.app.

<ExternalCallout continueOnError="false" enabled="true" name="External-Callout-1">
  <DisplayName>External-Callout-1</DisplayName>
  <GrpcConnection>
    <Server name="cloud_run_server_name"/>
    <Authentication>
      <GoogleIDToken>
        <Audience useTargetUrl="true"/>
      </GoogleIDToken>
    </Authentication>
  </GrpcConnection>
  <TimeoutMs>5000</TimeoutMs>
  <Configurations>
    <Property name="with.request.content">true</Property>
    <Property name="with.request.headers">true</Property>
    <Property name="with.response.content">true</Property>
    <Property name="with.response.headers">true</Property>
    <FlowVariable>example.flow.variable</FlowVariable>
    <FlowVariable>another.flow.variable</FlowVariable>
  </Configurations>
</ExternalCallout>

Referência de elemento secundário

As secções seguintes descrevem os elementos secundários de ExternalCallout.

<TimeoutMs>

O limite de tempo do pedido em milissegundos para pedidos gRPC. <TimeoutMs> tem de ser um número positivo.

<GrpcConnection>

O elemento <GrpcConnection> define o servidor gRPC como um TargetServer existente, especificado pelo atributo name. Consulte a página de referência de recursos TargetServer.

Nota: o protocolo para o TargetServer tem de ser GRPC.

Por exemplo, o seguinte código

<GrpcConnection>
  <Server name="external-target-server"/>
</GrpcConnection>

especifica que o servidor gRPC é um TargetServer existente denominado external-target-server.

Use o elemento <Authentication> (descrito mais adiante nesta secção) para gerar um token OpenID Connect emitido pela Google para fazer chamadas autenticadas a serviços baseados em gRPC, como serviços personalizados alojados no Cloud Run.

A tabela seguinte descreve os elementos secundários de <GrpcConnection>.

Elemento secundário Obrigatório? Descrição
<Server> elemento Obrigatório Especifica o servidor gRPC.
<Authentication> elemento Opcional Gera um token OpenID Connect emitido pela Google para fazer chamadas autenticadas a serviços baseados em gRPC, como o Cloud Run.

<Server> elemento

Especifica o servidor gRPC.

A tabela seguinte descreve os atributos do elemento <Server>.

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

O nome de um TargetServer existente que vai ser o servidor gRPC para o qual enviar pedidos.

 N/A Obrigatória String

<Authentication> elemento

Gera um token OpenID Connect emitido pela Google para fazer chamadas autenticadas a serviços baseados em gRPC, como serviços personalizados alojados no 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.

Este elemento tem um elemento secundário obrigatório: GoogleIDToken.

Predefinição N/A
Obrigatório? Opcional.
Tipo Tipo complexo
Elemento principal <GrpcConnection>
Elementos subordinados <GoogleIDToken>

O elemento Authentication usa a seguinte sintaxe:

Sintaxe

<ExternalCallout>
...
  <GrpcConnection>
    <Server name="cloud_run_server_name"/>
    <Authentication>
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleIDToken>
         <Audience ref="variable-1">STRING</Audience>
         <IncludeEmail ref="variable-2">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </GrpcConnection>
</ExternalCallout>

Exemplo

O exemplo seguinte mostra o elemento GoogleIDToken:

<ExternalCallout continueOnError="false" enabled="true" name="External-Callout-1">
  <DisplayName>External-Callout-1</DisplayName>
  <GrpcConnection>
     <Server name="cloud_run_server_name"/>
     <Authentication>
        <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
        <GoogleIDToken>
           <Audience>https://cloudrun-hostname.a.run.app</Audience>
        </GoogleIDToken>
     </Authentication>
  </GrpcConnection>
  <TimeoutMs>5000</TimeoutMs>
  <Configurations>
    <Property name="with.request.content">true</Property>
    <Property name="with.request.headers">true</Property>
    <Property name="with.response.content">true</Property>
    <Property name="with.response.headers">true</Property>
    <FlowVariable>example.flow.variable</FlowVariable>
    <FlowVariable>another.flow.variable</FlowVariable>
  </Configurations>
</ExternalCallout>
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

<ExternalCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleIDToken>
    ... 
    </GoogleIDToken>
  </Authentication>
  ...
</ExternalCallout>

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>
  <GoogleIDToken>
    <Audience>https://cloudrun-hostname.a.run.app</Audience>
  </GoogleIDToken>
</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>
  <GoogleIDToken>
    <Audience>https://cloudrun-hostname.a.run.app</Audience>
  </GoogleIDToken>
</Authentication>
Elemento secundário <GoogleIDToken>

Gera tokens OpenID Connect emitidos pela Google para fazer chamadas autenticadas aos serviços Google, como serviços personalizados alojados no Cloud Run.

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

O elemento GoogleIDToken usa a seguinte sintaxe:

Sintaxe

<ExternalCallout>
...
  <GrpcConnection>
    <Server name="cloud_run_server_name"/>
    <Authentication>
      <GoogleIDToken>
        <Audience ref="context-variable" useTargetUrl='BOOLEAN'>STRING</Audience>
        <IncludeEmail ref="context-variable">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </GrpcConnection>
</ExternalCallout>

Exemplo

O exemplo seguinte mostra o elemento GoogleIDToken:

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>true</IncludeEmail>
  </GoogleIDToken>
</Authentication>
Elemento secundário <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, o valor de ref estiver vazio ou for resolvido para um valor vazio e useTargetUrl for true, é usado "https://" + (nome do anfitrião do servidor de destino gRPC) como público-alvo. Por exemplo, se o anfitrião do servidor for my-grpc-server-java.a.run.app, o público-alvo usado é https://my-grpc-server-java.a.run.app.

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.

<Configurations>

O elemento <Configurations> permite-lhe configurar vários aspetos da política ExternalCallout, incluindo <Property> e <FlowVariable>.

A tabela seguinte descreve os elementos secundários de <Configurations>.

Elemento secundário Obrigatório? Descrição
<Property> Obrigatório

Especifica se os cabeçalhos e/ou o conteúdo de pedido/resposta vão ser enviados para o servidor. Os valores possíveis são true ou false. A predefinição é false.

<FlowVariable> Obrigatório

Especifica que variáveis de fluxo adicionais devem ser enviadas para o servidor.

<Property>

O elemento <Property> especifica se os cabeçalhos e/ou o conteúdo de pedido/resposta serão enviados para o servidor. Os valores possíveis são true (o item é enviado) ou false (o item não é enviado). O valor predefinido é false.

A tabela seguinte descreve os atributos do elemento <Property>.

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

Especifica o conteúdo que vai ser enviado para o servidor. Os valores possíveis para name são:

  • with.request.content
  • with.request.headers
  • with.response.content
  • with.response.headers
 N/A Obrigatória String

<FlowVariable>

O elemento <FlowVariable> especifica que variáveis de fluxo adicionais serão enviadas para o servidor. O valor de <FlowVariable> é um prefixo de uma variável, em vez do nome completo da variável. Por exemplo , se o elemento for a.b.c, o valor de uma variável denominada a.b.c é enviado para o servidor. Da mesma forma, o valor de uma variável denominada a.b.c.my-variable é enviado para o servidor. Mas o valor de uma variável denominada a.x.another-variable não é enviado porque não tem o prefixo a.b.c. Seguem-se alguns exemplos

<Configurations>
  <FlowVariable>a.b.c</FlowVariable>
  <FlowVariable>d.e.f</FlowVariable>
</Configurations>

Referência de erros

Erros de implementação

Nome do erro Causa
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.

Erros de tempo de execução

A tabela abaixo descreve os erros de tempo de execução, que podem ocorrer quando a política é executada.

Código de falha Estado de HTTP Causa
GrpcTlsInitFailed 500

Este erro ocorre se existirem problemas com a inicialização do TLS com o servidor gRPC (como problemas de keystore ou truststore).
steps.externalcallout.[error_code] 500

[error_code] é determinado pelo campo errorCode da mensagem de erro. A string de falha do erro vai ser o campo faultstring da mensagem de falha.
steps.externalcallout.ExecutionError 500

Este erro ocorre se ocorrer alguma outra exceção durante a execução desta política. A exceção subjacente é exposta no faultstring. Se tiver ocorrido um problema com as credenciais do servidor gRPC, o erro terá um aspeto semelhante ao seguinte:

{
  "fault": {
    "faultstring": "Encountered the following exception while sending the gRPC request or
     processing the response: [io.grpc.StatusRuntimeException: UNAVAILABLE: Credentials failed
     to obtain metadata].",
    "detail": {
      "errorcode": "steps.externalcallout.ExecutionError"
    }
  }
}

Pode consultar os registos do MP para obter mais indicações de depuração.
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.
steps.externalcallout.ExecutionError

com a string de falha:

Encountered the following exception while sending the gRPC request or processing the response: [io.grpc.StatusRuntimeException: UNAVAILABLE: Credentials failed to obtain metadata]

 500

Este erro ocorre se o proxy de API estiver configurado com o elemento <Authentication>. Causas possíveis:

  • A conta de serviço implementada com o proxy:
    • Não existe no seu projeto (existia quando foi implementado, mas foi eliminado após a implementação)
    • foi desativada
    • (Apenas para o Apigee hybrid) não concedeu a função roles/iam.serviceAccountTokenCreator à conta de serviço apigee-runtime.
  • (Apenas para o Apigee hybrid) A API IAMCredentials está desativada no projeto de origem da conta de serviço apigee-runtime.

    Nota: apenas para o Apigee híbrido, verifique o registo do contentor de tempo de execução e procure externalcallout.ExecutionError para encontrar mensagens de erro mais detalhadas que podem ajudar a depurar o problema.

steps.externalcallout.ExecutionError com faultstring contendo PERMISSION DENIED.

Por exemplo, a faultstring terá o seguinte aspeto para o Cloud Run:

Encountered the following exception while sending the gRPC request or processing the response: [io.grpc.StatusRuntimeException: PERMISSION_DENIED: HTTP status code 403 …]

 500

Este erro ocorre se o proxy da API estiver configurado com o elemento <Authentication>. Causas possíveis:

  • A conta de serviço do proxy existe e está ativada, mas não tem as autorizações adequadas para aceder ao serviço.
  • O serviço requer autenticação, mas o pedido não tinha um cabeçalho de autenticação (por exemplo, o XML de autenticação não foi incluído no XML da política).

Erros diversos

A tabela abaixo descreve erros diversos. Consulte a causa para ver mais detalhes.

Código de falha Causa
ReferencesExistToGrpcServer

Este erro ocorre se um utilizador tentar eliminar um servidor de destino gRPC, mas o servidor ainda estiver a ser usado por outras políticas.

Falhas

As variáveis de falha na tabela seguinte são definidas para todas as políticas por predefinição. Consulte as variáveis específicas dos erros de políticas.

Variáveis Onde Exemplos
fault.name="fault_name" fault_name é o nome da falha, conforme indicado na tabela de erros de tempo de execução acima. O nome da falha é a última parte do código de falha. fault.name corresponde a "ExecutionError".
externalcallout.[policy_name].failed policy_name é o nome especificado pelo utilizador da política que gerou a falha. externalcallout.ExternalCallout-1.failed = true

Tópicos relacionados