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 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:
- Política AssignMessage: crea un mensaje de solicitud, rellena los encabezados HTTP y los parámetros de consulta, define el verbo HTTP, etc.
-
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é?
- 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 Opcionalmente, usa el elemento |
N/A | Obligatorio |
continueOnError |
Asigna el valor Asigna el valor |
falso | Opcional |
enabled |
Asigna el valor Selecciona |
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 |
---|---|
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,
Es importante que conozcas este nombre predeterminado si usas máscaras de datos. Si omites el nombre de la variable, debes añadir |
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 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.
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:
Devuelve el encabezado Content-Length de la respuesta ServiceCallout. |
Ámbito: desde ServiceCallout en adelante 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 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 La URL de destino de ServiceCallout. |
donde |
Ámbito: desde la respuesta de ServiceCallout en adelante El cuerpo de la respuesta de ServiceCallout. |
servicecallout.{policy-name}.expectedcn |
Ámbito: desde la solicitud ServiceCallout en adelante 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 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:
|
build |
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. |
build |
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. |
build |
googletoken.EmptyIDTokenAudience |
500 |
|
|
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:
<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
|
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. |
build |
ConnectionInfoMissing |
Este error se produce si la política no tiene un elemento <HTTPTargetConnection> o <LocalTargetConnection> . |
build |
InvalidTimeoutValue |
Este error se produce si el valor de <Timeout> es negativo o cero. |
build |
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:
|
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
- Generar o modificar mensajes: política AssignMessage
- Extraer variables: política ExtractVariables
- Variables: Referencia de 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 de proxies de APIs
- Propiedades de transporte HTTP: referencia de propiedades de puntos de conexión
- Alternativa a ServiceCallout: HTTPClient escrito en JavaScript. Consulta el modelo de objetos de JavaScript.