Política ServiceCallout

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

Consulta la documentación de Apigee Edge.

Qué

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

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

• En un caso de uso externo, conviertes un texto destacado en 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 la API, enriquece y combina los datos para los usuarios finales de la app. También puedes realizar una solicitud mediante la política ServiceCallout en el flujo de solicitud y, luego, pasar la información en la respuesta al TargetEndpoint del proxy de API.
• En otro caso de uso, debes llamar a un proxy que se encuentra en la misma organización y entorno como desde el que llamas. Por ejemplo, puede resultarte útil cuando tienes un proxy que ofrece alguna funcionalidad discreta de bajo nivel que consumirán uno o más proxies. Por ejemplo, un proxy que expone operaciones de creación, lectura, actualización y eliminación con un almacén de datos de backend puede ser el proxy de destino para varios otros proxies que exponen 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 un texto destacado en un proxy de API local (es decir, uno en la misma organización y entorno) llamado data-manager, que especifica su extremo proxy cuyo nombre es default.

URL como una variable

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

En este ejemplo, se usa una variable en la URL para propagar de forma dinámica la URL de destino. La parte del protocolo de la URL, http://, no se puede especificar mediante una variable. Además, debes usar variables separadas para la parte del dominio de la URL y el resto de la URL.

Geocodificación y definición de solicitudes 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 la política AssignMessage para crear el objeto de solicitud, puedes definirlo directamente en la política ServiceCallout. En este ejemplo, la política ServiceCallout establece los valores de tres parámetros de consulta que se pasan al servicio externo. Puedes crear un mensaje de solicitud completo en la política ServiceCallout que especifica una carga útil, un tipo de codificación, como application/xml, encabezados, parámetros de forma, etcétera.

A continuación, se muestra otro ejemplo en el que se realiza la solicitud antes de que alcance 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 podría propagar, por ejemplo, a través de una política AssignMessage). El mensaje de respuesta se asigna a la variable GeocodingResponse, en la que se encuentra disponible para que la analice una política ExtractVariables o el código personalizado escrito en JavaScript o Java. La política espera 30 segundos para la respuesta de la API de geocodificación de Google antes de que se agote el tiempo de espera.

Llama a los 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 realizar el balanceo de cargas entre ellos. En este ejemplo, la carga se distribuye en dos servidores de destino llamados httpbin y yahoo. Si deseas obtener información para configurar los servidores de destino para tu proxy y configurar el balanceo de cargas, consulta Balanceo de cargas entre servidores de backend.

---

Información sobre la política ServiceCallout

Hay muchas situaciones en las que puedes usar una política ServiceCallout en tu proxy de API. Por ejemplo, puedes configurar un proxy de API para realizar llamadas a un servicio externo a fin de entregar datos de ubicación geográfica, opiniones de los clientes, elementos del catálogo minorista de un socio, etcétera.

Por lo general, un texto destacado se usa con otras dos políticas: AssignMessage y ExtractVariables.

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

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

  Nota: Los encabezados de mensaje de solicitud y respuesta en un ServiceCallout ya están disponibles como variables, como se describe en la sección Variables de flujo. No es necesario que los extraigas con la política ExtractVariables.

La composición típica de la política ServiceCallout incluye las siguientes políticas:

1. Política AssignMessage: Crea un mensaje de solicitud, propaga encabezados HTTP, parámetros de consulta, establece el verbo HTTP, etcétera.

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 muestra el servicio de destino.

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

3. Política ExtractVariables: Por lo general, define una expresión JSONPath o XPath que analiza el mensaje generado por ServiceCallout. Luego, la política establece variables que contienen los valores analizados desde la respuesta de ServiceCallout.

Nota: Un enfoque alternativo para ServiceCallout es un HTTPClient escrito en JavaScript que usa el modelo de objetos de JavaScript.

Control de errores personalizados

Muestra: ¡Aprende con práctica!
En este ejemplo de Learn Apigee, se muestra cómo verificar el código HTTP en una respuesta de ServiceCallout y generar una excepción personalizada en función del valor del código. En el ejemplo, se muestra un mensaje de error personalizado cuando el servicio de destino muestra un estado 404. Solo clona el repositorio y sigue las instrucciones en ese tema. El ejemplo ilustra un patrón común para manejar errores de ServiceCallout.

Referencia del elemento

A continuación, se describen los elementos y los atributos que puedes 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 principales de las políticas:

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. De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.	N/A	Obligatorio
continueOnError	Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta lo siguiente: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual	falso	Opcional
enabled	Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.	true	Opcional
async	Este atributo dejó de estar disponible.	falso	Obsoleta

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Predeterminada	N/A Si omites este elemento, se usa el valor del atributo name de la política.
Presencia	Opcional
Tipo	String

Elemento <Request>

Especifica la variable que contiene el mensaje de la solicitud que se envía desde el proxy de API al otro servicio. La variable se puede crear mediante una política anterior en el flujo, o puedes crearla intercalada 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 igual que para la política AssignMessage.

Los subelementos de <Set> y <Add> admiten la función de sustitución de strings de variables llamada plantillas de mensajes.

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

En el ejemplo más simple, pasas una variable que contiene el mensaje de la solicitud que se propagó antes en el flujo del proxy de API:

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

También puedes propagar el mensaje de solicitud enviado al servicio externo en la 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>

Valor predeterminado	Si omites el elemento de la solicitud o alguno de sus atributos, Apigee asigna los siguientes valores predeterminados: <Request clearPayload="true" variable="servicecallout.request"/> Veamos qué significan estos valores predeterminados. Primero, clearPayload=true significa que se crea un objeto de solicitud nuevo cada vez que se ejecuta la política ServiceCallout. Esto significa que la solicitud y la ruta del URI de 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 sepas este nombre predeterminado si usas enmascarado de datos, si omites el nombre de la variable, debes agregar servicecallout.request a la configuración de la máscara. Por ejemplo, si quieres enmascarar el encabezado de autorización para que no aparezca en las sesiones de depuración, debes agregar lo siguiente a tu configuración de enmascaramiento a fin de 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 la solicitud.	servicecallout.request	Opcional
clearPayload	Si es true, la variable que contiene el mensaje de solicitud se borra después de que la solicitud se envía al destino HTTP para liberar la memoria que usa el mensaje de solicitud. Configura la opción clearPayload como falsa solo si el mensaje de solicitud es obligatorio después de que se ejecute el ServiceCallout.	true	Opcional

Elemento <Request>/<IgnoreUnresolvedVariables>

Cuando se establece en true, la política ignora cualquier error de variable sin resolver en la solicitud.

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

Valor predeterminado	falso
Presencia	Opcional
Tipo	Booleano

Elemento <Response>

Incluye este elemento cuando la lógica del proxy de API requiera la respuesta de la llamada remota para su posterior procesamiento.

Cuando este elemento está presente, especifica el nombre de la variable que contendrá el mensaje de respuesta recibido del servicio externo. La respuesta del objetivo se asigna a la variable solo cuando la política lee la respuesta de forma correcta. Si por algún motivo la llamada remota falla, la política muestra un error.

Si se omite este elemento, el proxy de API no espera una respuesta. La ejecución del flujo del proxy de API continúa con los pasos de flujo posteriores. Además, a fin de afirmar lo obvio, sin un elemento Response, la respuesta del destino no está disponible para su procesamiento en pasos posteriores, y no hay forma de que el flujo del proxy detecte una falla en la llamada remota. Un uso común a fin de omitir el elemento Response cuando se usa ServiceCallout: para registrar mensajes en un sistema externo.

 <Response>calloutResponse</Response>

Valor predeterminado	NA
Presencia	Opcional
Tipo	String

Elemento <Timeout>

El tiempo en milisegundos que la política ServiceCallout espera una respuesta del objetivo. No puedes establecer este valor de forma dinámica en el entorno de ejecución. Si el ServiceCallout alcanza un tiempo de espera, se muestra un HTTP 500, la política falla y el proxy de API entra en un estado de error, como se describe en Maneja las fallas.

<Timeout>30000</Timeout>

Valor predeterminado	55,000 milisegundos (55 segundos), la configuración de tiempo de espera HTTP predeterminada para Apigee
Presencia	Opcional
Tipo	Entero

Elemento <HTTPTargetConnection>

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

Nota: Puedes usar variables de flujo para construir la URL en un elemento <HttpTargetConnection>.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

Valor predeterminado	N/A
Presencia	Obligatorio
Tipo	N/A

Elemento <HTTPTargetConnection>/<Authentication>

Usuarios de Apigee Hybrid: Si usas Apigee Hybrid, ten en cuenta que esta característica solo es compatible con Apigee Hybrid v1.6.x y versiones posteriores.

Genera tokens de Google OAuth 2.0 o OpenID Connect emitidos por Google para realizar llamadas autenticadas a los servicios de Google y servicios personalizados que se ejecutan en ciertos productos de Google Cloud. , como Cloud Functions y Cloud Run. Para usar este elemento, se requieren pasos de configuración y de implementación que se describen en Usa la autenticación de Google. Con una configuración adecuada, la política crea un token de autenticación y lo agrega a la solicitud de servicio.

Los elementos secundarios, GoogleAccessToken y GoogleIDToken, te permiten configurar la política para generar tokens de OpenID Connect o Google OAuth. Debes elegir uno de estos elementos secundarios según el tipo de servicio al que desees llamar.

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

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

El elemento Authentication usa 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>

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

Usa GoogleIDToken

En el siguiente ejemplo, se muestra el elemento GoogleIDToken:

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

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

Usa 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 de HeaderName

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

Valor predeterminado	N/A
¿Es obligatorio?	No
Tipo	String
Elemento principal	<Authentication>
Elementos secundarios	Ninguna

El elemento HeaderName usa la siguiente sintaxis:

Sintaxis

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

Con cadena estática

En este ejemplo, el token del portador generado se agrega, 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 de variable

En este ejemplo, el token del portador generado se agrega, 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 de GoogleAccessToken

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

Valor predeterminado	N/A
¿Es obligatorio?	Debe estar presente el elemento secundario GoogleAccessToken o GoogleIDToken.
Tipo	String
Elemento principal	<Authentication>
Elementos secundarios	<Scopes> <LifetimeInSeconds>

El elemento GoogleAccessToken usa 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 administrador 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 que un texto destacado en Cloud se ejecute 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>

Elemento secundario de los permisos

Identifica los permisos que se incluirán en el token de acceso de OAuth 2.0. Si deseas obtener más información, consulta Permisos de OAuth 2.0 para las API de Google. Puedes agregar uno o más elementos secundarios <Scope> debajo de este elemento.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	<GoogleAccessToken>
Elementos secundarios	<Scope>

Elemento secundario del permiso

Especifica un alcance de API de Google válido. Si deseas obtener más información, consulta Permisos de OAuth 2.0 para las API de Google.

Valor predeterminado	N/A
¿Es obligatorio?	Debes ingresar al menos un valor.
Tipo	String
Elemento principal	<Scopes>
Elementos secundarios	Ninguno

elemento secundario de LifetimeInSeconds

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

Nota: El valor predeterminado de LifetimeInSeconds es 3600. No recomendamos cambiar el valor predeterminado, a menos que quieras limitar el riesgo de que se filtren los tokens de acceso o mejorar el rendimiento.

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

Elemento secundario de GoogleIDToken

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

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

El elemento GoogleIDToken usa 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 del público

El público del token de autenticación que se generó, como la API o la cuenta a la que el token otorga acceso.

Si el valor de Audience está vacío o si la variable ref no se resuelve en un valor válido, y useTargetUrl es true, la URL del destino (excluyendo cualquier parámetro de consulta) se usa como público. El valor predeterminado de useTargetUrl es false.

Usuarios de Apigee Hybrid: Si usas Apigee Hybrid, ten en cuenta que el atributo useTargetUrl está disponible en la versión de Apigee Hybrid 1.8 y posteriores.

<Audience>explicit-audience-value-here</Audience>

or:

<Audience ref='variable-name-here'/>

or:

<Audience ref='variable-name-here' useTargetUrl='true'/>

or:

<Audience useTargetUrl='true'/>

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	<GoogleIDToken>
Elementos secundarios	Ninguno

Elemento secundario de IncludeEmail

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

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

Elemento <HTTPTargetConnection>/<URL>

La URL del servicio a la que se llamará:

El elemento <URL> es compatible con la función de sustitución de string variable llamada plantillas de mensajes.

<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, usarás una variable para especificar el valor de un parámetro de consulta:

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

O bien, configura una parte de la ruta de URL con una variable:

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

Si quieres usar una variable a fin de especificar el dominio y el puerto de la URL, usa una variable solo para el dominio y el puerto, y una segunda variable para cualquier otra parte de la URL:

<URL>http://{request.dom_port}/{request.resourcePath}</URL>

Valor predeterminado	N/A
Presencia	Obligatorio
Tipo	String

Elemento <HTTPTargetConnection>/<SSLInfo>

La configuración de TLS/SSL para el servicio de backend Si deseas obtener ayuda sobre la configuración de TLS/SSL, consulta Opciones para configurar TLS y la “Configuración de extremo de destino de TLS/SSL” en la referencia de configuración de proxy de API.

Nota: Especifica el nombre KeyStore en el elemento SSLInfo como una referencia en el formato ref://mykeystoreref. Se recomienda usar una referencia en lugar de un nombre directo o una variable de flujo. Consulta Información sobre cómo configurar los elementos <KeyStore> y <TrustStore>.

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

Valor 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 Referencia de propiedades de extremos.

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

Valor predeterminado	N/A
Presencia	Opcional
Tipo	N/A

Elemento <HTTPTargetConnection>/<LoadBalancer>

Llamar a uno o más servidores de destino y realiza el balanceo de cargas en ellos. Consulta la muestra Llamar a servidores de destino en la sección Muestras. También consulta Balanceo de cargas entre servidores de backend. Consulta también Texto destacado del extremo o servidor de destino que analiza las formas de llamar a los servidores de destino desde la política ServiceCallout y las reglas de enrutamiento.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>

Valor predeterminado	N/A
Presencia	Opcional
Tipo	N/A

Elemento <LocalTargetConnection>

Especifica un proxy local, es decir, un proxy en la misma organización y entorno, como el objetivo de los textos destacados del servicio.

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

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>

Valor predeterminado	N/A
Presencia	Obligatorio
Tipo	N/A

Elemento <LocalTargetConnection>/<APIProxy>

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

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

Junto con el elemento <APIProxy>, incluye el elemento <ProxyEndpoint> a fin de especificar el nombre del extremo del proxy que se debe orientar para la llamada.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>

Valor predeterminado	N/A
Presencia	Obligatorio
Tipo	String

Elemento <LocalTargetConnection>/<ProxyEndpoint>

El nombre del extremo del proxy que debe ser el objetivo de las llamadas. Este es un extremo proxy en el proxy de API especificado con el elemento <APIProxy>.

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

Valor predeterminado	N/A
Presencia	Opcional
Tipo	N/A

Elemento <LocalTargetConnection>/<Path>

Una ruta de acceso al extremo que se orientará. El extremo debe hacer referencia a un proxy en la misma organización y entorno que el proxy que realiza la llamada.

Usa esto en lugar de un par <APIProxy>/<ProxyEndpoint> cuando no lo sepas o no puedas confiar en el nombre de proxy. La ruta podría ser un objetivo confiable.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>

Valor predeterminado	N/A
Presencia	Opcional
Tipo	N/A

Esquemas

Muestra: Consulta nuestros repositorios de GitHub para ver los esquemas más recientes.

Variables de flujo

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

Los ServiceCallouts tienen sus propias solicitudes y respuestas, y puedes acceder a esos datos a través de variables. Debido a que el mensaje principal usa los prefijos de variable request.* y response.*, usa los prefijos myrequest.* y calloutResponse.* (los valores predeterminados en la configuración de ServiceCallout) a fin de obtener datos de mensajes específicos para el ServiceCallout. En el primer ejemplo de la siguiente tabla, se muestra cómo debes obtener los encabezados HTTP en el ServiceCallout.

Variable	Descripción
A continuación, se muestra un ejemplo de cómo obtener los encabezados de respuesta y solicitud del ServiceCallout, de manera similar a como obtendrías los encabezados de la solicitud y la respuesta principal. calloutResponse.header.HeaderName myRequest.header.HeaderName En el ejemplo anterior, calloutResponse es el nombre de la variable para la respuesta en el texto destacado del servicio, y myRequest es el nombre de variable de la solicitud. Por ejemplo: calloutResponse.header.Content-Length Muestra el encabezado Content-Length de la respuesta del ServiceCallout.	Alcance: Desde el desvío del ServiceCallout Tipo: String Permiso: Lectura y escritura Un encabezado de mensaje en la solicitud o respuesta del ServiceCallout. Por ejemplo, si la orientación del proxy de API es http://example.com y la orientación del ServiceCallout es http://mocktarget.apigee.net, estas variables son los encabezados del texto destacado para http://mocktarget.apigee.net.
servicecallout.requesturi	Alcance: Desde el inicio del texto destacado del ServiceCallout Tipo: String Permiso: Lectura y escritura El URI de TargetEndpoint para una política ServiceCallout. El URI es la URL de TargetEndpoint sin la especificación del protocolo y el dominio.
servicecallout.{policy-name}.target.url	Alcance: Desde el inicio del texto destacado del ServiceCallout Tipo: String Permiso: Lectura y escritura La URL de destino para un ServiceCallout.
calloutResponse.content En la que calloutResponse es el nombre de la variable <Response> en la configuración de ServiceCallout.	Alcance: Desde la respuesta del ServiceCallout Tipo: String Permiso: Lectura y escritura El cuerpo de la respuesta del ServiceCallout.
servicecallout.{policy-name}.expectedcn	Alcance: Desde el inicio del texto destacado del ServiceCallout Tipo: String Permiso: Lectura y escritura El nombre común esperado del TargetEndpoint, al que se hace referencia en una política ServiceCallout. Esto es significativo solo cuando el TargetEndpoint hace referencia a un extremo TLS/SSL.
servicecallout.{policy-name}.failed	Alcance: Desde la respuesta del ServiceCallout Tipo: Booleano Permiso: Lectura y escritura. Booleano que indica si la política se realizó de forma correcta, si es falsa, falló o si es verdadera.

Errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

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

Sugerencia: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Corregir para obtener información detallada sobre la solución de problemas.

Código de falla	Estado de HTTP	Causa	Corregir
steps.servicecallout.ExecutionFailed	500	Este error puede ocurrir en las siguientes situaciones: Se le solicita a la política que controle la entrada con formato incorrecto o no válido. El servicio de destino del backend muestra 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 string o algún 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 un tipo de respuesta, verás este error.
googletoken.EmptyIDTokenAudience	500	<GoogleIDToken> está habilitado, pero useTargetUrl se configura como falso y no se proporciona ningún valor para <Audience>, ya sea directamente o mediante referencia en el momento del error.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure	500	Este error puede ocurrir si el proxy de API se configuró con el elemento <Authentication>. Las siguientes son algunas de las posibles causas: La cuenta de servicio implementada con el proxy: no existe en tu proyecto Se inhabilitó (Solo para Apigee Hybrid) no otorgó 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 más alcances no válidos. Por ejemplo, busca errores tipográficos o permisos vacíos. Solo para Apigee Hybrid: Revisa el registro del contenedor del entorno de ejecución y busca GoogleTokenGenerationFailure para encontrar mensajes de error más detallados que puedan ayudar a depurar el problema.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Sugerencia: ¿Necesitas ayuda para arreglar un error? Haz clic en en la columna Corregir para obtener información detallada sobre la solución de problemas.

Nombre del error	Causa	Corregir
URLMissing	Falta el elemento <URL> dentro de <HTTPTargetConnection> o está vacío.
ConnectionInfoMissing	Este error se produce si la política no tiene un elemento <HTTPTargetConnection> o <LocalTargetConnection>.
InvalidTimeoutValue	Este error ocurre 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 está configurado con la etiqueta <Authentication>. Causas posibles: La cuenta de servicio no existe. La cuenta de servicio no se creó en el mismo proyecto de Google Cloud que la organización de Apigee. El implementador tiene el permiso iam.serviceAccounts.actAs en la cuenta de servicio. Para obtener más detalles, consulta Permisos de cuenta de servicio.

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables	Donde	Ejemplo
fault.name="fault_name"	fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla.	fault.name = "RequestVariableNotMessageType"
servicecallout.policy_name.failed	policy_name es el nombre especificado por el usuario de la política que generó la falla.	servicecallout.SC-GetUserData.failed = true

Ejemplo de respuesta de error

Nota: Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

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

Ejemplo de regla de falla

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

Temas relacionados

• Genera o modifica mensajes: Política AssignMessage
• Extrae variables: Política ExtractVariables
• Variables: Referencia de las variables de flujo
• Configuración de TLS/SSL
  • Opciones para configurar TLS
  • “Configuración de TargetEndpoint de TLS/SSL” en la referencia de configuración del proxy de API
• Propiedades de transporte HTTP: Referencia de propiedades de extremos
• Alternativa a ServiceCallout: HTTPClient escrito en JavaScript. Consulta Modelo de objetos de JavaScript.