Política ServiceCallout

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

Consulta la documentación de Apigee Edge.

Icono de política

Qué

La política ServiceCallout te permite llamar a otro servicio desde el flujo de tu proxy de API. Puedes hacer llamadas a un servicio externo (como un endpoint de servicio RESTful externo) o a servicios internos (como un proxy de API en la misma organización y entorno).

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

  • En un caso práctico externo, haces una llamada a una API de terceros que es externa a tu proxy. La respuesta de la API de terceros se analiza y se inserta en el mensaje de respuesta de tu API, lo que enriquece y combina los datos para los usuarios finales de la aplicación. También puedes hacer una solicitud mediante la política ServiceCallout en el flujo de solicitudes y, a continuación, pasar la información de la respuesta al elemento TargetEndpoint del proxy de API.
  • En otro caso práctico, llamas a un proxy que está en la misma organización y entorno que el proxy desde el que llamas. Por ejemplo, puede resultarte útil cuando tengas un proxy que ofrezca alguna función discreta de bajo nivel que consumirán uno o varios proxies. Por ejemplo, un proxy que exponga operaciones de creación, lectura, actualización y eliminación con un almacén de datos backend podría ser el proxy de destino de otros proxies que expongan los datos a los clientes.

La política admite solicitudes a través de HTTP y HTTPS.

Ejemplos

Llamada local a un proxy interno

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

En este ejemplo se crea una llamada a un proxy de API local (es decir, uno que se encuentra en la misma organización y entorno) llamado data-manager, especificando su endpoint de proxy, cuyo nombre es default.

URL como variable

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

En este ejemplo se usa una variable en la URL para rellenar dinámicamente la URL del objetivo. La parte del protocolo de la URL, http://, no se puede especificar mediante una variable. Además, debe usar variables independientes para la parte del dominio de la URL y para el resto de la URL.

Solicitud de geocodificación o definición de 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>

En lugar de usar una política como AssignMessage para crear el objeto de solicitud, puedes definirlo directamente en la política ServiceCallout. En este ejemplo, la política ServiceCallout define los valores de tres parámetros de consulta que se transfieren al servicio externo. Puedes crear un mensaje de solicitud completo en la política ServiceCallout que especifique una carga útil, un tipo de codificación (como application/xml), encabezados, parámetros de formulario, etc.

Aquí tienes otro ejemplo en el que la solicitud se forma antes de llegar a la 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>

El contenido del mensaje de la solicitud se extrae de una variable llamada GeocodingRequest (que se puede rellenar, por ejemplo, con una política AssignMessage). El mensaje de respuesta se asigna a la variable GeocodingResponse, donde está disponible para que la analice una política ExtractVariables o un código personalizado escrito en JavaScript o Java. La política espera 30 segundos para recibir la respuesta de la API Google Geocoding antes de agotar el tiempo de espera.

Llamar a servidores de destino

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

Esta política usa el atributo LoadBalancer para llamar a los servidores de destino y hacer el balanceo de carga entre ellos. En este ejemplo, la carga se distribuye entre dos servidores de destino llamados httpbin y yahoo. Para obtener información sobre cómo configurar servidores de destino para tu proxy y el balanceo de carga, consulta el artículo Balanceo de carga en servidores de backend.

Acerca de la política ServiceCallout

Hay muchos casos en los que puedes usar una política ServiceCallout en tu proxy de API. Por ejemplo, puedes configurar un proxy de API para que haga llamadas a un servicio externo con el fin de proporcionar datos de geolocalización, reseñas de clientes, artículos del catálogo de un partner, etc.

Normalmente, se usa una llamada con otras dos políticas: AssignMessage y ExtractVariables.

  • Solicitud: AssignMessage rellena el mensaje de solicitud enviado al servicio remoto.

  • Respuesta: ExtractVariables analiza la respuesta y extrae contenido específico.

La composición típica de la política ServiceCallout implica lo siguiente:

  1. Política AssignMessage: crea un mensaje de solicitud, rellena los encabezados HTTP y los parámetros de consulta, define el verbo HTTP, etc.

  2. Política ServiceCallout: hace referencia a un mensaje creado por la política AssignMessage, define una URL de destino para la llamada externa y define un nombre para el objeto de respuesta que devuelve el servicio de destino.

    Para mejorar el rendimiento, también puedes almacenar en caché las respuestas de ServiceCallout, tal como se describe en ¿Cómo puedo almacenar los resultados de la política ServiceCallout en la caché y, más adelante, recuperarlos de la caché?

  3. Política ExtractVariables: normalmente define una expresión JSONPath o XPath que analiza el mensaje generado por ServiceCallout. A continuación, la política define variables que contienen los valores analizados a partir de la respuesta de ServiceCallout.

Gestión de errores personalizada

Referencia de elemento

A continuación, se indican los elementos y atributos que puede configurar en esta política:

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

Atributos de <ServiceCallout>

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

En la siguiente tabla se describen los atributos que son comunes a todos los elementos superiores de la política:

Atributo Descripción Predeterminado Presencia
name

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

 N/A Obligatorio
continueOnError

Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas.

Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también:

 falso Opcional
enabled

Asigna el valor true para aplicar la política.

Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.

 true Opcional
async

Este atributo está obsoleto.

 falso Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>
Predeterminado

N/A

Si omite este elemento, se usará el valor del atributo name de la política.
Presencia Opcional
Tipo Cadena

Elemento <Request>

Especifica la variable que contiene el mensaje de solicitud que se envía desde el proxy de API al otro servicio. La variable puede crearla una política anterior del flujo o puedes crearla en línea en la 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>

La sintaxis de las etiquetas <Remove>, <Copy>, <Add> y <Set> es la misma que la de la política AssignMessage.

La política devuelve un error si no se puede resolver el mensaje de solicitud o si el tipo de mensaje de solicitud no es válido.

En el ejemplo más sencillo, se pasa una variable que contiene el mensaje de solicitud que se ha rellenado anteriormente en el flujo del proxy de API:

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

También puedes rellenar el mensaje de solicitud enviado al servicio externo en la propia 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>
Predeterminado Si omite el elemento Request o cualquiera de sus atributos, Apigee asignará los siguientes valores predeterminados:

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

Veamos qué significan estos valores predeterminados. En primer lugar, clearPayload=true significa que se crea un nuevo objeto de solicitud cada vez que se ejecuta la política ServiceCallout. Esto significa que la solicitud y la ruta del URI de la solicitud nunca se reutilizan. En segundo lugar, el nombre de variable predeterminado, servicecallout.request, es un nombre reservado que se asigna a la solicitud si no proporcionas un nombre.

Es importante que conozcas este nombre predeterminado si usas máscaras de datos. Si omites el nombre de la variable, debes añadir servicecallout.request a la configuración de la máscara. Por ejemplo, si quieres enmascarar el encabezado Authorization para que no aparezca en las sesiones de depuración, añade lo siguiente a tu configuración de enmascaramiento para capturar el nombre predeterminado:

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

Atributos

Atributo Descripción Predeterminado Presencia
variable

Nombre de la variable que contendrá el mensaje de solicitud.

 servicecallout.request Opcional
clearPayload

Si true, la variable que contiene el mensaje de solicitud se borra después de que se envíe la solicitud al destino HTTP para liberar la memoria utilizada por el mensaje de solicitud.

Asigna el valor false a la opción clearPayload solo si se necesita el mensaje de solicitud después de que se ejecute ServiceCallout.

 true Opcional

Elemento <Request>/<IgnoreUnresolvedVariables>

Si se asigna el valor true a esta política, se ignorará cualquier error de variable sin resolver en la solicitud.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
Predeterminado falso
Presencia Opcional
Tipo Booleano

Elemento <Response>

Incluye este elemento cuando la lógica del proxy de la API requiera la respuesta de la llamada remota para seguir procesando.

Cuando este elemento está presente, especifica el nombre de la variable que contendrá el mensaje de respuesta recibido del servicio externo. La respuesta del destino se asigna a la variable solo cuando la política lee correctamente toda la respuesta. Si la llamada remota falla por cualquier motivo, la política devuelve un error.

Si se omite este elemento, el proxy de API no espera una respuesta y la ejecución del flujo del proxy de API continúa con los pasos de flujo posteriores. Además, como es evidente, si no hay ningún elemento Response, la respuesta del destino no estará disponible para que la procesen los pasos posteriores y el flujo del proxy no podrá detectar ningún fallo en la llamada remota. Un uso habitual de la omisión del elemento Response al usar ServiceCallout es registrar mensajes en un sistema externo.

 <Response>calloutResponse</Response>
Predeterminado N/A
Presencia Opcional
Tipo Cadena

Elemento <Timeout>

Tiempo en milisegundos que la política ServiceCallout esperará una respuesta del destino. No puedes definir este valor de forma dinámica en el tiempo de ejecución. Si ServiceCallout alcanza el tiempo de espera, se devuelve un error HTTP 500, la política falla y el proxy de API pasa a un estado de error, tal como se describe en Gestión de errores.

<Timeout>30000</Timeout>
Predeterminado 55.000 milisegundos (55 segundos), el tiempo de espera HTTP predeterminado de Apigee
Presencia Opcional
Tipo Entero

Elemento <HTTPTargetConnection>

Proporciona detalles del transporte, como la URL, TLS/SSL y las propiedades HTTP. Consulta la <TargetEndpoint>referencia de configuración.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>
Predeterminado N/A
Presencia Obligatorio
Tipo N/A

Elemento <HTTPTargetConnection>/<Authentication>

Genera tokens de OAuth 2.0 de Google o tokens de OpenID Connect emitidos por Google para hacer llamadas autenticadas a servicios de Google y servicios personalizados que se ejecutan en determinados productos de Google Cloud, como Cloud Functions y 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.

Los elementos secundarios GoogleAccessToken y GoogleIDToken te permiten configurar la política para generar tokens de OAuth de Google o de OpenID Connect. Debes elegir uno de estos elementos secundarios en función del tipo de servicio al que quieras llamar.

La política ServiceCallout solo admite llamadas a servicios basados en HTTP.

Predeterminado N/A
¿Es obligatorio? Opcional.
Tipo Tipo complejo
Elemento principal <HTTPTargetConnection>
Elementos secundarios <HeaderName>
<GoogleAccessToken>
<GoogleIDToken>

El elemento Authentication utiliza la siguiente sintaxis:

Sintaxis

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

En el siguiente ejemplo se muestra el elemento GoogleAccessToken:

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

Usar GoogleIDToken

En el siguiente ejemplo se muestra el elemento GoogleIDToken:

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

Usar HeaderName

En el siguiente ejemplo se muestra el elemento HeaderName:

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

Usar LifetimeInSeconds

En el siguiente ejemplo se muestra el elemento HeaderName:

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

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.

Predeterminado N/A
¿Es obligatorio? No
Tipo Cadena
Elemento principal <Authentication>
Elementos secundarios Ninguno

El elemento HeaderName utiliza la siguiente sintaxis:

Sintaxis

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

Con una cadena estática

En este ejemplo, el token de portador generado se añade de forma predeterminada a un encabezado llamado X-Serverless-Authorization que se envía al sistema de destino. El encabezado Authorization, si está presente, se deja sin modificar y también se envía en la solicitud.

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

Con referencia variable

En este ejemplo, el token de portador generado se añade de forma predeterminada a un encabezado llamado X-Serverless-Authorization que se envía al sistema de destino. Si my-variable tiene un valor, se usa ese valor en lugar de la cadena predeterminada. El encabezado Authorization, si está presente, se deja sin modificar y también se envía en la solicitud.

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

Elemento secundario GoogleAccessToken

Genera tokens OAuth 2.0 de Google para hacer llamadas autenticadas a servicios de Google. Los tokens de OAuth de Google se pueden usar para llamar a muchos tipos de servicios de Google, como Cloud Logging y Secret Manager.

Predeterminado N/A
¿Es obligatorio? Debe incluirse el elemento secundario GoogleAccessToken o GoogleIDToken.
Tipo Cadena
Elemento principal <Authentication>
Elementos secundarios <Scopes>
<LifetimeInSeconds>

El elemento GoogleAccessToken utiliza la siguiente sintaxis:

Sintaxis

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

Ejemplo 1

En el siguiente ejemplo se muestra el elemento GoogleAccessToken:

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

Ejemplo 2

En el siguiente ejemplo se muestra cómo conectarse al gestor de secretos para recuperar un secreto mediante la 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>

Ejemplo 3

En el siguiente ejemplo se muestra cómo hacer una llamada a Cloud Run desde la 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 el ámbito del elemento secundario.

Identifica los ámbitos que se incluirán en el token de acceso de OAuth 2.0. Para obtener más información, consulta Permisos de OAuth 2.0 para APIs de Google. Puede añadir uno o varios elementos secundarios <Scope> a este elemento.

Predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo Cadena
Elemento principal <GoogleAccessToken>
Elementos secundarios <Scope>

Elemento secundario de ámbito

Especifica un ámbito de API de Google válido. Para obtener más información, consulta Permisos de OAuth 2.0 para APIs de Google.

Predeterminado N/A
¿Es obligatorio? Se necesita al menos un valor.
Tipo Cadena
Elemento principal <Scopes>
Elementos secundarios Ninguno

Elemento secundario LifetimeInSeconds

Especifica la duración del token de acceso en segundos.

Predeterminado 3600
¿Es obligatorio? Opcional
Tipo Entero
Elemento principal <GoogleAccessToken>
Elementos secundarios Ninguno

Elemento secundario GoogleIDToken

Genera tokens OpenID Connect emitidos por Google para hacer llamadas autenticadas a servicios de Google.

Predeterminado N/A
¿Es obligatorio? Debe estar presente el elemento secundario GoogleAccessToken o GoogleIDToken.
Tipo Cadena
Elemento principal <Authentication>
Elementos secundarios <Audience>
<IncludeEmail>

El elemento GoogleIDToken utiliza la siguiente sintaxis:

Sintaxis

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

Ejemplo 1

En el siguiente ejemplo se muestra el elemento GoogleIDToken:

<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 o la variable ref no se resuelve en un valor válido y useTargetUrl es true, se usa la URL del destino (sin incluir ningún parámetro de consulta) como audiencia. 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'/>
Predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo Cadena
Elemento principal <GoogleIDToken>
Elementos secundarios Ninguno

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.

Predeterminado falso
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <GoogleIDToken>
Elementos secundarios Ninguno

Elemento <HTTPTargetConnection>/<URL>

La URL del servicio al que se llama:

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

Puedes proporcionar parte de la URL de forma dinámica con una variable. Sin embargo, la parte del protocolo de la URL, http://, no se puede especificar mediante una variable. En el siguiente ejemplo, se usa una variable para especificar el valor de un parámetro de consulta:

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

También puede definir una parte de la ruta de la URL con una variable:

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

Si quiere usar una variable para especificar el dominio y el puerto de la URL, utilice una variable para el dominio y el puerto únicamente, y una segunda variable para cualquier otra parte de la URL:

<URL>http://{request.dom_port}/{request.resourcePath}</URL>
Predeterminado N/A
Presencia Obligatorio
Tipo Cadena

Elemento <HTTPTargetConnection>/<SSLInfo>

Configuración de TLS/SSL del servicio de backend. Para obtener ayuda sobre la configuración de TLS/SSL, consulta las opciones para configurar TLS y la sección "Configuración de TargetEndpoint de TLS/SSL" de la referencia de configuración de 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>
Predeterminado N/A
Presencia Opcional
Tipo N/A

Elemento <HTTPTargetConnection>/<Properties>

Propiedades de transporte HTTP al servicio de backend. Para obtener más información, consulta la referencia de propiedades de puntos de conexión.

<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>
Predeterminado N/A
Presencia Opcional
Tipo N/A

Elemento <HTTPTargetConnection>/<LoadBalancer>

Llama a uno o varios servidores de destino y realiza el balanceo de carga en ellos. Consulta el ejemplo Servidores de destino de la llamada en la sección Ejemplos. Consulta también Balanceo de carga en servidores de backend. Consulta también Llamada a servidor o endpoint de destino, donde se describen las formas de llamar a servidores de destino desde la política ServiceCallout y mediante reglas de ruta.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
Predeterminado N/A
Presencia Opcional
Tipo N/A

Elemento <LocalTargetConnection>

Especifica un proxy local (es decir, un proxy de la misma organización y entorno) como destino de las llamadas de servicio.

Para especificar aún más el destino, usa los elementos <APIProxy> y <ProxyEndpoint>, o el elemento <Path>.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>
Predeterminado N/A
Presencia Obligatorio
Tipo N/A

Elemento <LocalTargetConnection>/<APIProxy>

Nombre de un proxy de API que es el destino de una llamada local. El proxy debe estar en la misma organización y en el mismo entorno que el proxy que hace la llamada.

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

Junto con el elemento <APIProxy>, incluye el elemento <ProxyEndpoint> para especificar el nombre del endpoint del proxy al que se debe dirigir la llamada.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>
Predeterminado N/A
Presencia Obligatorio
Tipo Cadena

Elemento <LocalTargetConnection>/<ProxyEndpoint>

Nombre del endpoint de proxy que debe ser el destino de las llamadas. Se trata de un punto de conexión de proxy del proxy de API especificado con el elemento <APIProxy>.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
Predeterminado N/A
Presencia Opcional
Tipo N/A

Elemento <LocalTargetConnection>/<Path>

Ruta al endpoint al que se dirige. El endpoint debe hacer referencia a un proxy de la misma organización y el mismo entorno que el proxy que realiza la llamada.

Usa esta opción en lugar de un par <APIProxy>/<ProxyEndpoint> cuando no sepas el nombre del proxy o no puedas fiarte de él. La ruta puede ser un objetivo fiable.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>
Predeterminado N/A
Presencia Opcional
Tipo N/A

Esquemas

Variables de flujo

Las variables de flujo permiten que las políticas y los flujos tengan un comportamiento dinámico en el tiempo de ejecución, en función de los encabezados HTTP, el contenido de los mensajes o el contexto del flujo. Las siguientes variables de flujo predefinidas están disponibles después de que se ejecute una política ServiceCallout. Para obtener más información sobre las variables de flujo, consulta la referencia de variables de flujo.

Los ServiceCallouts tienen su propia solicitud y respuesta, y puedes acceder a esos datos a través de variables. Como el mensaje principal usa los prefijos de variable request.* y response.*, usa los prefijos myrequest.* y calloutResponse.* (los predeterminados en la configuración de ServiceCallout) para obtener datos de mensajes específicos de ServiceCallout. En el primer ejemplo de la siguiente tabla se muestra cómo obtener los encabezados HTTP en ServiceCallout.

Variable Descripción

A continuación, se muestra un ejemplo de cómo obtener los encabezados de solicitud y respuesta de ServiceCallout de forma similar a como obtendrías los encabezados de la solicitud y la respuesta principales.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

donde calloutResponse es el nombre de la variable de la respuesta en la llamada externa del servicio y myRequest es el nombre de la variable de la solicitud. Por ejemplo:

calloutResponse.header.Content-Length

Devuelve el encabezado Content-Length de la respuesta ServiceCallout.

Ámbito: desde ServiceCallout en adelante
Tipo: cadena
Permiso: lectura/escritura

Un encabezado de mensaje en la solicitud o respuesta de ServiceCallout. Por ejemplo, si el destino del proxy de API es http://example.com y el destino de ServiceCallout es http://mocktarget.apigee.net, estas variables son los encabezados de la llamada a http://mocktarget.apigee.net.
servicecallout.requesturi

Ámbito: desde la solicitud ServiceCallout en adelante
Tipo: cadena
Permiso: lectura/escritura

El URI de TargetEndpoint de una política ServiceCallout. El URI es la URL de TargetEndpoint sin el protocolo ni la especificación del dominio.
servicecallout.{policy-name}.target.url

Ámbito: desde la solicitud ServiceCallout en adelante
Tipo: cadena
Permiso: lectura/escritura

La URL de destino de ServiceCallout.

calloutResponse.content

donde calloutResponse es el <Response>nombre de la variable en la configuración de ServiceCallout.

Ámbito: desde la respuesta de ServiceCallout en adelante
Tipo: cadena
Permiso: lectura/escritura

El cuerpo de la respuesta de ServiceCallout.
servicecallout.{policy-name}.expectedcn

Ámbito: desde la solicitud ServiceCallout en adelante
Tipo: cadena
Permiso: lectura/escritura

Nombre común esperado del TargetEndpoint al que se hace referencia en una política ServiceCallout. Solo tiene sentido cuando TargetEndpoint hace referencia a un endpoint TLS/SSL.
servicecallout.{policy-name}.failed

Ámbito: desde la respuesta de ServiceCallout en adelante
Tipo: booleano
Permiso: lectura/escritura

Valor booleano que indica si la política se ha aplicado correctamente (false) o no (true).

Errores

En esta sección se describen los códigos de error y los mensajes de error que devuelve Apigee, así como las variables de error que define, cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de fallo Estado de HTTP Causa Solucionar
steps.servicecallout.ExecutionFailed 500

Este error puede producirse cuando:

  • Se le pide a la política que gestione una entrada que tiene un formato incorrecto o no es válida.
  • El servicio de destino backend devuelve un estado de error (de forma predeterminada, 4xx o 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 La variable Request especificada en la política no es del tipo Message. Por ejemplo, si es una cadena u otro tipo que no sea de mensaje, verás este error.
steps.servicecallout.RequestVariableNotRequestMessageType 500 La variable Request especificada en la política no es del tipo RequestMessage. Por ejemplo, si es de tipo Response, verás este error.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> está habilitado, pero useTargetUrl tiene el valor "false" y no se ha proporcionado ningún valor para <Audience>, ni directamente ni mediante una referencia en el momento del error.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 Este error puede producirse si el proxy de API se configura con el elemento <Authentication> . Estos son algunos de los posibles motivos:
  • La cuenta de servicio implementada con el proxy:
    • no existe en tu proyecto
    • se ha inhabilitado
    • (Solo en Apigee hybrid) No se ha concedido el rol roles/iam.serviceAccountTokenCreator en la cuenta de servicio apigee-runtime.
  • La API IAMCredentials está inhabilitada en el proyecto de origen de la cuenta de servicio apigee-runtime.
  • Se usa el elemento <GoogleAccessToken> y se proporcionan uno o varios permisos no válidos. Por ejemplo, busca errores tipográficos o ámbitos vacíos.

    • Solo en Apigee hybrid, consulta el registro del contenedor de tiempo de ejecución y busca GoogleTokenGenerationFailure para encontrar mensajes de error más detallados que puedan ayudarte a depurar el problema.

    Errores de implementación

    Estos errores pueden producirse al implementar un proxy que contenga esta política.

    Nombre del error Causa Solucionar
    URLMissing Falta el elemento <URL> en <HTTPTargetConnection> o está vacío.
    ConnectionInfoMissing Este error se produce si la política no tiene un elemento <HTTPTargetConnection> o <LocalTargetConnection>.
    InvalidTimeoutValue Este error se produce si el valor de <Timeout> es negativo o cero.
    FAILED_PRECONDITION Este error se produce si falta la cuenta de servicio cuando el proxy se configura con la etiqueta <Authentication>.

    Por ejemplo: 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED Este error se produce si hay un problema de permisos con la cuenta de servicio si el proxy se configura con la etiqueta <Authentication>. Posibles causas:
    • La cuenta de servicio no existe.
    • La cuenta de servicio no se ha creado en el mismo proyecto de Google Cloud que la organización de Apigee.
    • El usuario que realiza el despliegue tiene el permiso iam.serviceAccounts.actAs en la cuenta de servicio. Para obtener más información, consulta el artículo Acerca de los permisos de las cuentas de servicio.

    Variables de error

    Estas variables se definen cuando se produce un error de tiempo de ejecución. Para obtener más información, consulta el artículo Información sobre los errores de las políticas.

    Variables Dónde Ejemplo
    fault.name="fault_name" fault_name es el nombre del fallo, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name es el nombre de la política especificado por el usuario que ha provocado el error. servicecallout.SC-GetUserData.failed = true

    Ejemplo de respuesta de error

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

    Regla de error de ejemplo

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

    Temas relacionados