Usa variables de flujo

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

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

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 hora en que Edge recibe una solicitud
• Datos derivados cuando se ejecuta una política. Por ejemplo, después de que una política se ejecuta y valida un token de OAuth, Edge 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 Edge 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, Node.js 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 Edge, de forma similar al funcionamiento de una declaración de interruptor en programación.

  Por ejemplo, una política para devolver una falla puede ejecutarse solo cuando está configurada una variable de flujo en particular. Por último, puedes obtener y configurar variables de flujo en una aplicación de destino de Node.js.

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 cuotas actual y de una variable de flujo llamada system.time, que es una de las variables de Edge integradas.

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 Comprende el alcance de las variables de flujo.

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 (que se mostró antes). Es otro método para lograr los mismos objetivos en Edge. 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.

Variables de flujo en el código de Node.js

Si requieres el módulo apigee-access, puedes configurar y acceder a las variables de flujo desde el código de Node.js que se implementa en Edge.

Este es un ejemplo sencillo en el que una variable llamada custom.foo se establece en el valor Bar. Una vez que se establece, esta variable nueva está disponible para cualquier política o código que ocurra en el flujo del proxy después de que se ejecute el código de Node.js.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

Puedes obtener más información sobre el uso de apigee-access para trabajar con variables en Cómo acceder a las variables de flujo en Node.js.

Comprende el alcance de las variables de flujo

El alcance de la variable está relacionado con el flujo o el “ciclo de vida” general de una llamada del proxy de la 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.

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.

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 de Edge integrada llamada client.ip. Esta variable tiene el permiso 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.

Hay otra variable integrada llamada target.url. El alcance de la variable es "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.

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

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, consulte:

• Cómo trabajar con variables en JavaScript
• Accede a variables de flujo en Node.js
• 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. Por ejemplo, las variables creadas en el código de Node.js se limitan a Number, String, Boolean, null o undefined.

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 seguimiento, por ejemplo, para ver qué variables se configuraron en una instancia en particular en un flujo de 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 siguiente ejemplo, Extract Variables analiza un mensaje de respuesta y almacena 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 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 objetos de JavaScript de Apigee, JavaScript que se ejecuta en Edge tiene acceso directo a las variables de flujo del proxy.

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 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');

De manera similar, puedes llamar a setVariable() para configurar el valor de una variable personalizada o para cualquier variable que admita escritura 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).

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

Cómo acceder a las variables de flujo en aplicaciones de Node.js

Puedes obtener, establecer y borrar variables de flujo desde el código de Node.js implementado en Edge. Solo debes “requerir” el módulo apigee-access en tu código. Para obtener más información, consulta Cómo acceder a las variables de flujo en Node.js.

Qué debes recordar

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

• De forma automática, el proxy crea instancias de algunas variables “listas para usar” y las propaga. 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, y en el código de Node.js.
• 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.
• Puedes obtener y configurar muchas variables de flujo desde Node.js con JavaScript puro (y nuestro modelo de objetos de JavaScript) o la política de JavaCallout, que ejecuta código en Edge.

Muestras de código relacionadas

Las muestras de proxy de API se encuentran en GitHub y son fáciles de descargar y usar. Consulta Usa los proxies de API de muestra para obtener información sobre la descarga y el uso de las muestras. Consulta la Lista de muestras para obtener una descripción de las muestras del proxy de API y lo que hacen.

Entre los proxies de muestra que ejemplifican el uso y el procesamiento de variables, se incluyen los siguientes:

• variables: muestra cómo extraer y configurar variables en función del transporte y el contenido de los mensajes JSON y XML.
• policy-mashup-cookbook: Una aplicación completa que usa la composición de políticas para llamar a dos API públicas, combina los resultados y genera una respuesta enriquecida para la app cliente. Para obtener más información sobre esta muestra, consulta Usa la composición de políticas.
• conditional-policy: Implementa la política condicional simple basada en valores de variables.

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.