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.
La composición típica de la política ServiceCallout incluye las siguientes políticas:
- Política AssignMessage: Crea un mensaje de solicitud, propaga encabezados HTTP, parámetros de consulta, establece el verbo HTTP, etcétera.
-
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é?
- 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.
Control de errores personalizados
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 De forma opcional, usa el elemento |
N/A | Obligatorio |
continueOnError |
Configúralo como Configúralo como |
falso | Opcional |
enabled |
Configúralo como Configúralo como |
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 |
---|---|
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.
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,
Es importante que sepas este nombre predeterminado si usas enmascarado de datos, si omites el nombre de la variable, debes agregar |
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 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>
.
<HTTPTargetConnection> <URL>http://example.com</URL> <LoadBalancer/> <SSLInfo/> <Properties/> </HTTPTargetConnection>
Valor predeterminado | N/A |
Presencia | Obligatorio |
Tipo | N/A |
Elemento <HTTPTargetConnection>/<Authentication>
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.
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
.
<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á:
<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.
<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
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.
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:
Muestra el encabezado Content-Length de la respuesta del ServiceCallout. |
Alcance: Desde el desvío del ServiceCallout 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 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 La URL de destino para un ServiceCallout. |
En la que |
Alcance: Desde la respuesta del ServiceCallout El cuerpo de la respuesta del ServiceCallout. |
servicecallout.{policy-name}.expectedcn |
Alcance: Desde el inicio del texto destacado del ServiceCallout 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 Booleano que indica si la política se realizó de forma correcta, si es falsa, falló o si es verdadera. |
Errores
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause | Fix |
---|---|---|---|
steps.servicecallout.ExecutionFailed |
500 |
This error can occur when:
|
build |
steps.servicecallout.RequestVariableNotMessageType |
500 |
The Request variable specified in the policy is not of type Message . For example, if
it's a string or other non-message type, you'll see this error. |
build |
steps.servicecallout.RequestVariableNotRequestMessageType |
500 |
The Request variable specified in the policy is not of type RequestMessage . For
example, if it's a Response type, you'll see this error. |
build |
googletoken.EmptyIDTokenAudience |
500 |
|
|
messaging.adaptors.http.filter.GoogleTokenGenerationFailure |
500 |
This error can happen if the API proxy is configured with the <Authentication>
element. Possible causes include:
<GoogleAccessToken> element is used and one or more
invalid scopes are provided. For example, look for typos or empty scopes.
For Apigee hybrid only, check the runtime container's log and search for
|
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause | Fix |
---|---|---|
URLMissing |
The <URL> element inside <HTTPTargetConnection>
is missing or empty. |
build |
ConnectionInfoMissing |
This error happens if the policy does not have an
<HTTPTargetConnection> or <LocalTargetConnection>
element. |
build |
InvalidTimeoutValue |
This error happens if the <Timeout> value is negative or zero. |
build |
FAILED_PRECONDITION |
This error happens if the service account is missing when the proxy is
configured with the <Authentication> tag.
For example: Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service account identity, but one was not provided with the request. |
|
PERMISSION_DENIED |
This error happens if there is a permission problem with the service account if
the proxy is
configured with the <Authentication> tag. Possible causes:
|
Fault variables
These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.
Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name = "RequestVariableNotMessageType" |
servicecallout.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | servicecallout.SC-GetUserData.failed = true |
Example error response
{ "fault":{ "detail":{ "errorcode":"steps.servicecallout.RequestVariableNotMessageType" }, "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: request variable data_str value is not of type Message" } }
Example fault rule
<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.