Usar 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 tus políticas o utilidades (como la herramienta de depuración). Te permiten mantener el estado asociado a una transacción de API procesada por Apigee.

¿Qué son las variables de flujo?

Las variables de flujo se encuentran en el contexto de un flujo de proxy de API y registran el estado de una transacción de API de la misma forma que las variables con nombre registran el estado de 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 enviados desde la aplicación que realiza la solicitud
  • Información del sistema, como la fecha y la hora en las que Apigee recibe una solicitud
  • Datos derivados cuando se ejecuta una política. Por ejemplo, después de que se ejecute 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 que realiza la solicitud.
  • Información sobre la respuesta del sistema de destino.

Algunas variables están integradas en Apigee y se rellenan automáticamente cada vez que se recibe una solicitud de API. Están disponibles durante toda la transacción de la API. También puede crear sus propias variables personalizadas mediante políticas como la política AssignMessage o en código JavaScript y Java.

Como verás, las variables tienen un ámbito y el lugar al que se puede acceder a ellas depende en parte de cuándo se creen en el flujo del proxy de API. Por lo general, cuando se crea una variable, está disponible para todas las políticas y el código que se ejecutan más adelante en el flujo de transacciones de la API.

¿Cómo se usan las variables de flujo?

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

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

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

  • Los flujos condicionales pueden hacer referencia a variables de flujo para dirigir el flujo de una API a través de Apigee, de forma similar a como funciona una instrucción switch en programación.

    Por ejemplo, una política para devolver un error solo se puede ejecutar cuando se define una variable de flujo concreta.

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, la siguiente política AssignMessage toma el valor de la variable de flujo client.ip y lo coloca en un encabezado de solicitud llamado My-Client-IP. Si se añade al flujo de solicitud, esta política define un encabezado que se transfiere al destino de backend. Si se define en el flujo response, el encabezado se envía de vuelta a la aplicación 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>

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

Más adelante, puedes ejecutar un flujo condicional que diga: "Si el recuento de cuota actual es inferior al 50% del máximo y es entre las 9:00 y las 17:00, aplica otra cuota". Esta condición puede depender del valor del recuento de cuota actual y de 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 se suelen usar para cambiar el comportamiento de los flujos, los pasos y las reglas de ruta.

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

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

Ahora te preguntarás de dónde proceden variables como request.verb, client.ip y system.time. ¿Cuándo se instancian y se rellenan con un valor? Para saber cuándo se crean las variables y cuándo están disponibles, consulta el artículo Visualizar el flujo de un proxy de API.

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

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

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

Esta técnica para usar JavaScript con el fin de leer y definir variables es similar a la que puedes usar con la política AssignMessage (que se ha mostrado anteriormente). Es otra forma de hacer lo mismo en Apigee. Lo importante es recordar que el código JavaScript ejecutado por la política JavaScript tiene acceso a todas las variables de flujo que existen y están en el ámbito del flujo del proxy de API.

Visualizar el flujo de un proxy de API

Para entender el ámbito de las variables de flujo, es importante comprender o visualizar la forma en que los mensajes fluyen a través de un proxy de API. Un proxy de API consta de 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 código de política o realizar ramificaciones condicionales.

En la siguiente figura se ilustra esta secuencia de flujos. Fíjate en que los flujos se componen de cuatro segmentos principales: solicitud de ProxyEndpoint, solicitud de TargetEndpoint, respuesta de TargetEndpoint y respuesta de ProxyEndpoint.

Una solicitud de cliente HTTP pasa por un proxy de API al servicio HTTP y, a continuación, la respuesta pasa por el proxy de API y vuelve al cliente.

Ten en cuenta esta estructura de flujo mientras exploramos las variables de flujo en el resto de este tema.

Cómo se relaciona el ámbito de las variables con el flujo de proxy

En cuanto puedas visualizar cómo fluyen los mensajes a través de un proxy, como se ha descrito anteriormente, podrás empezar a entender el ámbito de las variables. Por ámbito, nos referimos al punto del ciclo de vida del flujo del proxy en el que se crea una variable por primera vez.

Por ejemplo, si tiene una política vinculada al segmento de solicitud ProxyEndpoint, esa política no podrá acceder a ninguna variable cuyo ámbito sea el segmento de solicitud TargetEndpoint. Esto se debe a que el segmento de solicitud TargetEndpoint del flujo aún no se ha ejecutado, por lo que el proxy de API no ha tenido la oportunidad de rellenar las variables de ese ámbito.

En la siguiente tabla se muestra el conjunto completo de ámbitos de variables y se indica en qué momento del flujo del proxy están disponibles.

Ámbito de la variable Dónde se rellenan estas variables
solicitud de proxy Segmento de solicitud ProxyEndpoint
solicitud de destino Segmento de solicitud TargetEndpoint
respuesta objetivo Segmento de respuesta de TargetEndpoint
respuesta de proxy El segmento de respuesta de ProxyEndpoint
Siempre disponible En cuanto 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 el alcance de solicitud de proxy. Se rellena automáticamente con la dirección IP del cliente que ha llamado al proxy. Se rellena cuando una solicitud llega por primera vez a ProxyEndpoint y permanece disponible durante todo el ciclo de vida del flujo del proxy.

Hay otra variable integrada llamada target.url. El ámbito de esta variable es solicitud de destino. Se rellena en el segmento de solicitud TargetEndpoint con la URL de solicitud enviada al destino de backend. Si intentas acceder a target.url en el segmento de solicitud ProxyEndpoint, recibirás el valor NULL. Si intentas definir esta variable antes de que esté en el ámbito, el proxy no hará nada: no generará ningún error ni definirá la variable.

A continuación, se muestra un ejemplo sencillo que explica cómo se debe pensar en el ámbito de las variables. Supongamos que quieres copiar todo el contenido de un objeto de solicitud (encabezados, parámetros y cuerpo) y asignarlo a la carga útil de la respuesta para enviarla de vuelta a la aplicación que ha llamado. Puedes usar la política AssignMessage para esta tarea. El código de la política tiene este aspecto:

<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 del proxy? La respuesta es que debe colocarse en la respuesta TargetEndpoint, ya que el ámbito de la variable de respuesta es respuesta de destino.

Hacer referencia a variables de flujo

Todas las variables integradas de 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, system.time.hour y request.content.

Apigee reserva varios prefijos para organizar las variables pertinentes de forma adecuada. Entre estos prefijos se incluyen los siguientes:

  • request
  • response
  • system
  • target

Para hacer referencia a una variable en una política, escríbela entre llaves. Por ejemplo, la siguiente política 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 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 puede hacer referencia a variables de flujo en código JavaScript y Java. Para obtener más información, consulta estos artículos:

Tipo de datos de las variables de flujo

Cada propiedad de una variable de flujo tiene un tipo de datos bien definido, como String, Long, Integer, Boolean o Collection. Puede consultar los tipos de datos en la referencia de variables de flujo. En el caso de las variables creadas por una política, consulta el tema de referencia de la política específica para obtener información sobre el tipo de datos.

Las variables que creas manualmente adoptan el tipo que se les asigna al crearlas y dependen de los tipos de valores permitidos.

Usar variables de flujo en las políticas

Muchas políticas crean variables de flujo como parte de su ejecución normal. En los documentos de referencia de las políticas se incluyen todas estas variables específicas de las políticas.

Cuando trabajes con proxies y políticas, consulta la referencia de políticas para saber qué variables se crean y para qué se utilizan. Por ejemplo, la política de cuota crea un conjunto de variables que contienen información sobre los recuentos y los límites de cuota, la hora de vencimiento, etc.

Algunas variables de política son útiles para depurar. Por ejemplo, puedes usar la herramienta de depuración para ver qué variables se han definido en una instancia concreta de un flujo de proxy.

La política ExtractVariables le permite rellenar variables personalizadas con datos extraídos de mensajes. Puede extraer parámetros de consulta, encabezados y otros datos. Por ejemplo, puedes analizar mensajes de solicitud y respuesta mediante patrones para extraer datos específicos de los mensajes.

En el ejemplo siguiente, la política ExtractVariables analiza un mensaje de respuesta y almacena datos específicos extraídos 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>

Recuerda que muchas políticas crean variables automáticamente. Puede acceder a esas variables en el contexto del flujo del proxy. Se describen en la referencia de políticas, en el tema de cada política.

Trabajar con variables de flujo en código JavaScript

Puede acceder a las variables y definirlas directamente en el código JavaScript que se ejecuta en el contexto de un proxy de API. Mediante el modelo de objetos de JavaScript de Apigee, el JavaScript que se ejecuta en Apigee tiene acceso directo a las variables de flujo del proxy.

Para acceder a las variables en el código JavaScript, llama a los métodos getter o setter de cualquiera de estos objetos:

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

Como puede ver, estas referencias de objetos se corresponden con los segmentos del modelo de flujo de proxy que ya conoce, tal como se ha explicado en el artículo Visualizar el flujo de un proxy de API.

El objeto context corresponde a las variables disponibles globalmente, como las variables del 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, puede llamar a setVariable() para definir el valor de una variable personalizada o de cualquier variable predeterminada de escritura. Aquí creamos una variable personalizada llamada organization.name.myorg y le asignamos un valor.

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

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

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

Qué debes recordar

A continuación, se indican algunos aspectos importantes que debes tener en cuenta sobre las variables de flujo:

  • Algunas variables out-of-the-box se instancian y se rellenan automáticamente por el propio proxy. Se describen en la referencia de variables de flujo.
  • Puedes crear variables personalizadas que se puedan usar en el flujo de proxy. Es posible crear variables mediante políticas como AssignMessage y JavaScript.
  • Las variables tienen un ámbito. Por ejemplo, algunas variables se rellenan automáticamente cuando el primer proxy recibe una solicitud de una aplicación. Otras variables se rellenan en el segmento de flujo de respuesta del proxy. Estas variables de respuesta no se definen hasta que se ejecuta el segmento de respuesta.
  • Cuando se ejecutan las políticas, pueden crear y rellenar variables específicas de la política. En la documentación de cada política se enumeran todas estas variables específicas relevantes.
  • Los flujos condicionales suelen evaluar una o varias variables. Debes entender las variables si quieres crear flujos condicionales.
  • Muchas políticas usan variables como entrada o salida. Quizá una variable creada por una política se use más adelante en otra.

Temas relacionados

  • Todas las variables que se rellenan automáticamente en un proxy de API se indican en la referencia de variables de flujo. En la referencia también se indica el tipo y el ámbito de cada variable.
  • Si quieres saber qué variables rellena una política específica, consulta el tema de referencia de esa política. Por ejemplo, consulta las variables de flujo en la referencia de la política de cuota.