Usa variables de flujo

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

Consulta la documentación de Apigee Edge.

Las variables de flujo son objetos a los que puedes acceder desde las políticas o utilidades (como la herramienta de depuración). Te permiten mantener el estado asociado con una transacción de API que procesa Apigee.

Guía de inicio rápido: Para obtener una lista completa de todas las variables de flujo y sus propiedades, consulta Referencia de variables de flujo.

Video

Nota: En el siguiente video, se muestra el Editor de proxies clásico en la IU de Apigee. Apigee presenta una versión nueva del Editor de proxies, que tiene un diseño diferente al de la versión clásica que se muestra en el video.

El siguiente video proporciona una introducción a las variables de flujo:

¿Qué son las variables de flujo?

Las variables de flujo existen dentro del contexto de un flujo de proxy de API y realizan un seguimiento del estado en una transacción de API de la manera en que las variables denominadas realizan el seguimiento del estado en un programa de software. Las variables de flujo almacenan información como la siguiente:

• La dirección IP, los encabezados, la ruta de URL y la carga útil que se envía desde la app solicitante
• Información del sistema, como la fecha y la hora en que Apigee recibe una solicitud
• Datos derivados cuando se ejecuta una política. Por ejemplo, después de que se ejecuta una política que valida un token de OAuth, Apigee crea variables de flujo que contienen información como el nombre de la aplicación solicitante.
• Información sobre la respuesta del sistema de destino

Algunas variables están integradas en Apigee y se propagan automáticamente cada vez que se recibe una solicitud a la API. Están disponibles a lo largo de una transacción de API. También puedes crear tus propias variables personalizadas mediante políticas como la política de AssignMessage o en JavaScript y el código Java.

Como verás, las variables tienen permiso y las ubicaciones en las que se puede acceder dependen, en parte, del momento en que se crean en el flujo de proxy de API. En general, cuando se crea una variable, esta está disponible para todas las políticas y el código que se ejecutan más adelante en el flujo de transacción de la API.

¿Cómo se usan las variables de flujo?

Las variables de flujo se usan en políticas y flujos condicionales:

• Las políticas pueden recuperar el estado de las variables de flujo y usarlas para realizar su trabajo.

  Por ejemplo, una política de VerifyJWT puede recuperar el token que se verificará desde una variable de flujo y, luego, realizará la verificación. Otro ejemplo es una política de JavaScript, que puede recuperar variables de flujo y codificar los datos que contienen esas variables.

• Los flujos condicionales pueden hacer referencia a las variables de flujo para dirigir el flujo de una API a través de Apigee, de forma similar al funcionamiento de una declaración de interruptor en programación.

  Por ejemplo, una política para mostrar una falla solo puede ejecutarse cuando se establece una variable de flujo en particular.

Veamos ejemplos de cómo se usan las variables en cada uno de estos contextos.

Variables de flujo en las políticas

Algunas políticas toman variables de flujo como entrada.

Por ejemplo, en la siguiente política de AssignMessage, se toma el valor de la variable de flujo client.ip y se coloca en un encabezado de solicitud llamado My-Client-IP. Si se agrega al flujo de solicitud, esta política establece un encabezado que se pasa al objetivo de backend. Si se configura en el flujo de respuesta, el encabezado se envía a la app cliente.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Como otro ejemplo, cuando se ejecuta una política de cuotas, se propagan varias variables de flujo con valores relacionados con la política. Una de estas variables se llama ratelimit.my-quota-policy.used.count (en la que my-quota-policy es el nombre de la política de cuotas que te interesa).

Luego, puedes ejecutar un flujo condicional que diga "si el recuento de cuota actual es inferior al 50% y está entre las 9 a.m. y las 5 p.m., aplica una cuota diferente". Esta condición puede depender del valor del recuento de cuota actual y en una variable de flujo llamada system.time, que es una de las variables integradas de Apigee.

Variables de flujo en flujos condicionales

Los flujos condicionales evalúan las variables de flujo y permiten que los proxies se comporten de forma dinámica. Las condiciones suelen usarse para cambiar el comportamiento de los flujos, los pasos y las reglas de enrutamiento.

Este es un flujo condicional que evalúa el valor de la variable request.verb en un paso de flujo del proxy. En este caso, si el verbo de solicitud es POST, se ejecuta la política VerifyAPIKey. Este es un patrón común que se usa en las configuraciones del proxy de API.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

Ahora quizá te preguntes de dónde provienen las variables como request.verb, client.ip y system.time. ¿Cuándo se crean instancias de ellas y se propagan con un valor? Para ayudarte a comprender cuándo se crean las variables y cuándo están disponibles, consulta Visualiza el flujo de un proxy de API.

Variables de flujo en el código JavaScript llamado con la política de JavaScript

Con la política de JavaScript, puedes ejecutar un código JavaScript desde el contexto de un flujo de proxy de API. El JavaScript que se ejecuta en esta política usa el modelo de objeto de JavaScript de Apigee, que proporciona a tu código personalizado acceso a objetos de solicitud, respuesta y contexto asociados con el flujo del proxy de API en el que se ejecuta tu código. Por ejemplo, este código establece un encabezado de respuesta con el valor obtenido a partir de la variable de flujo target.name.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

Esta técnica de usar JavaScript para leer y configurar variables es similar al trabajo que puedes hacer con la política de AssignMessage (como se mostró antes). Es otro método para lograr los mismos objetivos en Apigee. Lo que se debe recordar es que el JavaScript que ejecuta la política de JavaScript tiene acceso a todas las variables de flujo que existen y están dentro del permiso del flujo del proxy de API.

Visualiza el flujo de un proxy de API

Para comprender el permiso de la variable de flujo, es importante entender o visualizar la forma en que fluyen los mensajes a través de un proxy de API. Un proxy de API consiste en una serie de pasos de procesamiento de mensajes organizados como un flujo. En cada paso de un flujo de proxy, el proxy evalúa la información disponible y decide qué hacer a continuación. Durante el proceso, el proxy puede ejecutar el código de la política o realizar ramificaciones condicionales.

En la siguiente figura, se ilustra esta secuencia de flujos. Observa cómo los flujos se componen de cuatro segmentos principales: solicitud de ProxyEndpoint, solicitud de TargetEndpoint, respuesta de TargetEndpoint y respuesta de ProxyEndpoint.

Ten en cuenta esta estructura de flujo cuando comencemos a describir variables de flujo en el resto de este tema.

Lecturas adicionales Si deseas leer sobre la estructura de flujo del proxy con más detalle, consulta Configura flujos.

Cómo se relaciona el permiso de la variable con el flujo del proxy

En cuanto puedas visualizar cómo fluyen los mensajes a través de un proxy, como se describió antes, puedes comenzar a comprender el permiso de las variables. Por permiso, nos referimos al punto en el ciclo de vida del flujo de proxy cuando se crea una instancia por primera vez.

Por ejemplo, si tienes una política conectada al segmento de solicitud de ProxyEndpoint, esa política no podrá acceder a ninguna variable con permiso para el segmento de solicitud de TargetEndpoint. La razón de esto es que el segmento de solicitud de TargetEndpoint del flujo aún no se ejecutó, por lo que el proxy de la API no tuvo la oportunidad de propagar variables en él.

En la siguiente tabla, se muestra el conjunto completo de permisos de variables y se indica cuándo están disponibles en el flujo del proxy.

Nota: Después de que una variable de flujo se propaga dentro de su permiso determinado, permanece disponible durante el resto del ciclo de vida del flujo del proxy. Si intentas acceder a una variable que aún no está dentro del permiso, recibirás un error o un valor NULL.

Alcance de la variable	Dónde se propagan estas variables
Solicitud de proxy	El segmento de solicitud de ProxyEndpoint
Solicitud de destino	El segmento de solicitud de TargetEndpoint
Respuesta de destino	El segmento de respuesta de TargetEndpoint
Respuesta de proxy	El segmento de respuesta de ProxyEndpoint
Siempre disponible	Tan pronto el proxy recibe una solicitud. Estas variables están disponibles durante todo el ciclo de vida del flujo del proxy.

Por ejemplo, hay una variable integrada de Apigee llamada client.ip. Esta variable tiene alcance de solicitud de proxy. Se propaga de forma automática con la dirección IP del cliente que llamó al proxy. Se propaga cuando una solicitud llega al ProxyEndpoint, y permanece disponible durante todo el ciclo de vida del flujo del proxy.

Nota: Los permisos de todas las variables de Apigee integradas se enumeran en la Referencia de variables de flujo.

Hay otra variable integrada llamada target.url. El permiso de esta variable es una solicitud de destino. Se propaga en el segmento de solicitud de TargetEndpoint con la URL de la solicitud enviada al destino de backend. Si intentas acceder a target.url en el segmento de solicitud de ProxyEndpoint, recibirás un valor NULL. Si intentas configurar esta variable antes de que esté dentro del alcance, el proxy no hace nada; no genera ningún error y no establece la variable.

Nota: Es posible configurar algunas políticas para que generen un error o muestren NULL cuando se accede a una variable no definida. Consulta las páginas de referencia de políticas individuales para obtener más detalles.

Aquí te mostramos un ejemplo simple que demuestra cómo pensar en el permiso de una variable. Supongamos que deseas copiar todo el contenido de un objeto de solicitud (encabezados, parámetros, cuerpo) y asignarlo a la carga útil de la respuesta para que se envíe de vuelta a la app que realiza la llamada. Puedes usar la política de AssignMessage para esta tarea. El código de la política se verá así:

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

Esta política simplemente copia el objeto request y lo asigna al objeto response. Pero ¿dónde se debe colocar esta política en el flujo de proxy? La respuesta es que debe colocarse en la respuesta de TargetEndpoint, porque el permiso de la variable de respuesta es respuesta de destino.

Haz referencia a variables de flujo

Todas las variables integradas en Apigee siguen una convención de nomenclatura con notación de puntos. Esta convención facilita la determinación del propósito de la variable. Por ejemplo, usa system.time.hour y request.content.

Práctica recomendada: Google te recomienda que uses la convención de nomenclatura de notación de puntos cuando crees variables de flujo personalizadas. Puede ser útil usar puntos para organizar una jerarquía de tus variables personalizadas.

Por ejemplo, approval.code y approval.status pueden hacer referencia a una función de aprobación dentro del flujo.

Apigee reserva varios prefijos para organizar las variables relevantes de manera adecuada. Estos prefijos incluyen lo siguiente:

• request
• response
• system
• target

Para hacer referencia a una variable en una política, enciérrala entre llaves. Por ejemplo, la siguiente política de AssignMessage toma el valor de la variable client.ip y lo coloca en un encabezado de solicitud llamado Client-IP.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

En los flujos condicionales, no es necesario usar las llaves. La siguiente condición de ejemplo evalúa la variable request.header.accept:

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

También puedes hacer referencia a variables de flujo en JavaScript y código de Java. Para obtener más información, consulta:

• Trabaja con variables de flujo en código JavaScript
• Política JavaScript

Tipos de datos de variables de flujo

Cada propiedad de una variable de flujo tiene un tipo de datos bien definido, como String, Long, Integer, Boolean o Collection. Puedes encontrar los tipos de datos en la referencia de variables de flujo. Para conocer las variables que creó una política, consulta el tema de referencia de la política específico para obtener información sobre los tipos de datos.

Las variables que creas de forma manual asumen el tipo otorgado cuando se crearon y dependen de los tipos de valores permitidos.

Usa variables de flujo en las políticas

Muchas políticas crean variables de flujo como parte de su ejecución normal. La referencia de políticas documenta todas estas variables específicas de la política.

Cuando trabajes con proxies y políticas, asegúrate de consultar la referencia de políticas para saber qué variables se crean y para qué se usan. Por ejemplo, la Política de Cuotas crea un conjunto de variables que contienen información sobre los límites y los recuentos de las cuotas, la hora de vencimiento, etcétera.

Algunas variables de política son útiles para la depuración. Puedes usar la herramienta de depuración , por ejemplo, para ver qué variables se configuraron en una instancia en particular en un flujo del proxy.

La política de ExtractVariables te permite propagar variables personalizadas con datos extraídos de los mensajes. Puedes extraer parámetros de búsqueda, encabezados y otros datos. Por ejemplo, puedes analizar los mensajes de solicitud y respuesta con patrones para extraer datos específicos de los mensajes.

En el ejemplo siguiente, la política de ExtractVariables permite analizar un mensaje de respuesta y almacenar datos específicos tomados de la respuesta. La política crea dos variables personalizadas, geocoderesponse.latitude y geocoderesponse.longitude, y les asigna valores.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Reiteramos, ten en cuenta que muchas políticas crean variables automáticamente. Puedes acceder a esas variables dentro del contexto de flujo del proxy, y se documentan en la referencia de políticas en cada tema de política individual.

Trabaja con variables de flujo en el código JavaScript

Puedes acceder a variables y configurarlas directamente en el código JavaScript que se ejecuta en el contexto de un proxy de API. A través del modelo de objeto de JavaScript de Apigee, JavaScript que se ejecuta en Apigee tiene acceso directo a las variables de flujo del proxy.

Nota: Puedes llamar a JavaScript desde un proxy con la política de JavaScript.

Para acceder a las variables en código JavaScript, llama a los métodos get y set en cualquiera de estos objetos:

• context
• proxyRequest
• proxyResponse
• targetRequest
• targetResponse

Como puedes ver, estas referencias de objeto se mapean a los segmentos conocidos del modelo de flujo del proxy, como se explicó antes en Visualiza el flujo de un proxy de API.

El objeto context corresponde a variables globales disponibles, como las variables de sistema. Por ejemplo, puedes llamar a getVariable() en el objeto context para obtener el año actual:

var year = context.getVariable('system.time.year');

Del mismo modo, puedes llamar a setVariable() para configurar el valor de una variable personalizada o para cualquier variable que se pueda escribir lista para usar. Aquí, creamos una variable personalizada llamada organization.name.myorg y le asignamos un valor.

var org = context.setVariable('organization.name.myorg', value);

Debido a que esta variable se crea con el objeto context, estará disponible para todos los segmentos de flujo (básicamente, es como crear una variable global).

Nota: La referencia de las variables de flujo indica qué variables se pueden escribir y cuáles son de solo lectura. Para obtener más información, consulta el modelo de objeto de JavaScript.

También puedes obtener o configurar variables de flujo del proxy en código Java que ejecutes con la política de JavaCallout.

Qué debes recordar

A continuación, presentamos algunos aspectos importantes que debes recordar sobre las variables de flujo:

• El proxy crea instancias de algunas variables out-of-the-box y las propaga de forma automática. Estas se documentan en la Referencia de variables de flujo.
• Puedes crear variables personalizadas disponibles para usar en el flujo de proxy. Es posible crear variables usando políticas, como la política de AssignMessage y la política de JavaScript.
• Las variables tienen permisos. Por ejemplo, algunas variables se propagan de forma automática cuando el primer proxy recibe una solicitud de una app. Otras variables se propagan en el segmento de flujo de respuesta del proxy. Estas variables de respuesta siguen sin estar definidas hasta que se ejecuta el segmento de respuesta.
• Cuando se ejecutan las políticas, pueden crear y propagar variables específicas de la política. La documentación de cada política enumera todas estas variables específicas de la política relevantes.
• Por lo general, los flujos condicionales evalúan una o más variables. Debes comprender las variables si quieres crear flujos condicionales.
• Muchas políticas usan variables como entrada o salida. Puede ser que una variable creada por una política sea usada más tarde por otra política.

Sugerencia: Verás una serie de muestras que usan variables de una manera u otra. Busca las que usen la política de ExtractVariables, que se suele usar para procesar variables en un flujo de proxy.

Temas relacionados

• Todas las variables que se propagan automáticamente en un proxy de API se enumeran en la Referencia de variables de flujo. En la referencia, también se enumera el tipo y el permiso de cada variable.
• Si deseas saber qué variables se propagan en una política específica, consulta el tema de referencia para la política. Por ejemplo, consulta Variables de flujo en la referencia de la política de cuotas.