Política ServiceCallout

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X. información

Qué

La política de texto destacado de servicios 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).

• 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 de texto destacado del servicio 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

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

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

<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>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

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

Acerca de la política de texto destacado del servicio

Hay muchas situaciones en las que puedes usar una política de texto destacado del servicio 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: asignar mensajes y extraer variables.

• Solicitud: La asignación de mensaje propaga el mensaje de solicitud enviado al servicio remoto.

• Respuesta: Las variables de extracción analizan la respuesta y extraen contenido específico.

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

1. Política Asignar mensaje: Crea un mensaje de solicitud, propaga encabezados HTTP, parámetros de consulta, establece el verbo HTTP, etcétera.
2. Política de Texto destacado de servicio: Hace referencia a un mensaje creado por la política de Asignar mensaje, 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 texto destacado de servicio, como se describe en esta conversación de la comunidad de Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. Política de extracción de variables: Por lo general, define una expresión JSONPath o XPath que analiza el mensaje generado por el texto destacado del servicio. Luego, la política establece variables que contienen los valores analizados desde la respuesta de solicitud de oferta de servicio.

Consulta Usar la composición de políticas para ver un proxy de API de muestra completo que usa la política de texto destacado del servicio junto con las políticas de asignación de mensajes y variables de extracción.

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>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </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:

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>

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 de texto destacado del servicio.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

La sintaxis de las etiquetas <Remove>, <Copy>, <Add> y <Set> es igual que para la política de asignación 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 de texto destacado del servicio:

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

Atributos

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> 

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> 

Elemento <Timeout>

El tiempo en milisegundos que la política de texto destacado del servicio espera una respuesta del objetivo. No puedes establecer este valor de forma dinámica en el entorno de ejecución. Si el texto destacado del servicio 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>

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>

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>

Elemento <HTTPTargetConnection>/<SSLInfo>

La configuración de TLS/SSL para el servicio de backend Para obtener ayuda con la configuración de TLS/SSL, consulta Configura TLS desde el extremo hasta el backend (en la nube y en la nube privada) y “Configuración de TargetEndpoint en TLS/SSL” en la referencia sobre la configuración del proxy de la 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>

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>

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. También consulta esta publicación de la comunidad en la que se analizan las formas de llamar a los servidores de destino desde la política de texto destacado del servicio y el uso de las reglas de enrutamiento.

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

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>

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> 

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>

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>

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 de texto destacado del servicio. Para obtener más información sobre las variables de flujo, consulta Referencia de las variables.

Los textos destacados del servicio 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 texto destacado del servicio) a fin de obtener datos de mensajes específicos para la solicitud de oferta. En el primer ejemplo de la siguiente tabla, se muestra cómo debes obtener los encabezados HTTP en el texto destacado del servicio.

Errores

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

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="VariableOfNonMsgType"></faultrule><FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

Temas relacionados

• Genera o modifica mensajes: Asigna una política de mensajes
• Extrae variables: Política de extracción de variables
• Variables: Referencia de variables
• Configuración de TLS/SSL
  • Configuración TLS desde el perímetro hasta el backend (nube y nube privada)
  • “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 al texto destacado de servicio: HTTPClient escrito en JavaScript, consulta Modelo de objetos de JavaScript