Política ExternalCallout

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Qué

La política ExternalCallout te permite enviar solicitudes gRPC a tu servidor gRPC para implementar un comportamiento personalizado que no admiten las políticas de Apigee. En el código de tu servidor, puedes acceder y modificar fácilmente las variables de flujo dentro del flujo de un proxy.

Apigee se comunica con un servidor gRPC a través de una política ExternalCallout mediante una API. Apigee usa la API para enviar variables de flujo al servidor gRPC. En tu servidor gRPC, puedes leer (y, según la variable, modificar) las variables de flujo que se indican en la página de referencia Variables de flujo, así como las variables adicionales que especifiques en el XML de la política.

Si configuras el servidor gRPC con Apigee e incluyes esta política en un proxy, Apigee gestionará las solicitudes de API de la siguiente manera:

1. Apigee envía un mensaje que contiene las variables de flujo a tu servidor gRPC.
2. Se ejecuta el código del servidor gRPC, que accede a las variables y las modifica según se definen en el código. A continuación, el servidor gRPC envía una respuesta que contiene todas las variables de flujo a Apigee.
3. Apigee lee la respuesta de tu servidor gRPC. Si se añade alguna variable o se modifica alguna variable de flujo modificable, se actualiza en Apigee.

Esta política es una política estándar y se puede implementar en cualquier tipo de entorno. Para obtener información sobre los tipos de políticas y la disponibilidad de cada tipo de entorno, consulta Tipos de políticas.

Para obtener más información sobre cómo enviar solicitudes gRPC, consulta los siguientes enlaces:

• gRPC
• Búferes de protocolo

<ExternalCallout>

Define una política ExternalCallout.

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

Este elemento tiene los siguientes atributos, que son comunes a todas las políticas:

En la siguiente tabla se describen los elementos secundarios de <ExternalCallout>.

Ejemplo 1

Puedes consultar ejemplos prácticos de ExternalCallout en External Callout Samples (Ejemplos de ExternalCallout) en GitHub.

En el siguiente ejemplo se muestra una configuración de 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>

En el ejemplo se envía una solicitud a un servidor gRPC externo representado por el TargetServer llamado external-target-server, con las siguientes configuraciones:

• <Property>: incluye el contenido de la solicitud y la respuesta, pero no los encabezados de la solicitud y la respuesta, en la solicitud enviada al servidor gRPC.
• <FlowVariable>: Incluye variables de flujo adicionales example1.flow.variable y example2.flow.variable, especificadas por los elementos FlowVariable, en la solicitud enviada al servidor gRPC.

Ejemplo 2

En el ejemplo siguiente, el atributo useTargetUrl del elemento Audience se ha definido como true. Cuando useTargetUrl es true, el nombre de host del servidor de destino de gRPC se usa como audiencia. Por ejemplo, si el host del servidor es my-grpc-server-java.a.run.app, la audiencia utilizada 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>

Referencia de elemento secundario

En las siguientes secciones se describen los elementos secundarios de ExternalCallout.

<TimeoutMs>

Tiempo de espera de la solicitud en milisegundos para las solicitudes gRPC. <TimeoutMs> debe ser un número positivo.

<GrpcConnection>

El elemento <GrpcConnection> define el servidor gRPC como un TargetServer existente, especificado por el atributo name. Consulta la página de referencia del recurso TargetServer.

Nota: El protocolo de TargetServer debe ser GRPC.

Por ejemplo, el siguiente código

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

especifica que el servidor gRPC es un TargetServer llamado external-target-server.

Usa el elemento <Authentication> (descrito más adelante en esta sección) para generar un token OpenID Connect emitido por Google para hacer llamadas autenticadas a servicios basados en gRPC, como los servicios personalizados alojados en Cloud Run.

En la siguiente tabla se describen los elementos secundarios de <GrpcConnection>.

Elemento <Server>

Especifica el servidor gRPC.

En la siguiente tabla se describen los atributos del elemento <Server>.

Elemento <Authentication>

Genera un token OpenID Connect emitido por Google para hacer llamadas autenticadas a servicios basados en gRPC, como servicios personalizados alojados en Cloud Run. Para usar este elemento, debes seguir los pasos de configuración e implementación que se describen en el artículo Usar la autenticación de Google. Si la configuración es correcta, la política crea un token de autenticación y lo añade a la solicitud de servicio.

Este elemento tiene un elemento secundario obligatorio: GoogleIDToken.

El elemento Authentication utiliza la siguiente sintaxis:

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

<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

Ninguno

Elemento secundario <HeaderName>

De forma predeterminada, cuando hay una configuración de autenticación, Apigee genera un token de portador y lo inserta en el encabezado Authorization del mensaje enviado al sistema de destino. El elemento HeaderName le permite especificar el nombre de otro encabezado para contener ese token de portador. Esta función es especialmente útil cuando el destino es un servicio de Cloud Run que usa la cabecera X-Serverless-Authorization. El encabezado Authorization, si está presente, no se modifica y también se envía en la solicitud.

El elemento HeaderName utiliza la siguiente sintaxis:

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

<Authentication>
  <HeaderName>X-Serverless-Authorization</HeaderName>
  <GoogleIDToken>
    <Audience>https://cloudrun-hostname.a.run.app</Audience>
  </GoogleIDToken>
</Authentication>

<Authentication>
  <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
  <GoogleIDToken>
    <Audience>https://cloudrun-hostname.a.run.app</Audience>
  </GoogleIDToken>
</Authentication>

Elemento secundario <GoogleIDToken>

Genera tokens de OpenID Connect emitidos por Google para hacer llamadas autenticadas a servicios de Google, como servicios personalizados alojados en Cloud Run.

El elemento GoogleIDToken utiliza la siguiente sintaxis:

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

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

Elemento secundario <Audience>

La audiencia del token de autenticación generado, como la API o la cuenta a la que el token concede acceso.

Si el valor de Audience está vacío, ref está vacío o se resuelve en un valor vacío y useTargetUrl es true, se usa "https://" + (nombre de host del servidor de destino de gRPC) como audiencia. Por ejemplo, si el host del servidor es my-grpc-server-java.a.run.app, la audiencia utilizada será https://my-grpc-server-java.a.run.app.

De forma predeterminada, useTargetUrl es 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'/>

Elemento secundario <IncludeEmail>

Si se define como true, el token de autenticación generado contendrá las reclamaciones email y email_verified de la cuenta de servicio.

<Configurations>

El elemento <Configurations> le permite configurar varios aspectos de la política ExternalCallout, como <Property> y <FlowVariable>.

En la siguiente tabla se describen los elementos secundarios de <Configurations>.

<Property>

El elemento <Property> especifica si se enviarán al servidor los encabezados y/o el contenido de la solicitud o la respuesta. Los valores posibles son true (el artículo se enviará) o false (el artículo no se enviará). El valor predeterminado es false.

En la siguiente tabla se describen los atributos del elemento <Property>.

<FlowVariable>

El elemento <FlowVariable> especifica qué variables de flujo adicionales se enviarán al servidor. El valor de <FlowVariable> es un prefijo de una variable, no el nombre completo de la variable. Por ejemplo , si el elemento es a.b.c, se enviará al servidor el valor de una variable llamada a.b.c. Del mismo modo, el valor de una variable llamada a.b.c.my-variable se enviará al servidor. Sin embargo, no se enviará el valor de una variable llamada a.x.another-variable porque no tiene el prefijo a.b.c. Aquí tienes algunos ejemplos:

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

Referencia de errores

Errores de implementación

Deployment of \"organizations/foo/apis/apiproxy/revisions/1\"
requires a service account identity, but one was not provided
with the request.

Errores de tiempo de ejecución

En la siguiente tabla se describen los errores de tiempo de ejecución, que pueden producirse cuando se ejecuta la política.

{
  "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"
    }
  }
}

Errores varios

En la siguiente tabla se describen errores varios. Consulta la causa para obtener más información.

Fallas

Las variables de error de la siguiente tabla se definen de forma predeterminada en todas las políticas. Consulta las variables específicas de los errores de las políticas.

Temas relacionados

• Política JavaCallout