Controlar proxies de APIs mediante los flujos

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

Consulta la documentación de Apigee Edge.

Los flujos son los elementos básicos de los proxies de API. Los flujos te permiten programar el comportamiento de una API configurando la secuencia en la que un proxy de API ejecuta las políticas y el código.

Los flujos son fases secuenciales a lo largo de la ruta de procesamiento de solicitudes de la API. Cuando añades lógica de proxy, como verificar una clave de API, la añades como un paso en la secuencia especificada por un flujo. Cuando defines una condición para especificar si se ejecuta la lógica y cuándo, añades la condición a un flujo.

En el siguiente ejemplo de configuración de flujo se define un flujo en el que se ejecuta la política VerifyAPIKey si la ruta de la solicitud entrante termina en / y el verbo HTTP de la solicitud es GET.

<Flow name="Get Food Carts">
    <Description>Get Food Carts</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

El valor Verify-API-Key del elemento <Name> del flujo sirve para incluir una política configurada en otra parte del proxy con XML como el siguiente:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <Properties/>
    <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

Diseñar la secuencia de ejecución del flujo

Estructura los flujos para que la lógica se ejecute en la secuencia correcta a lo largo de la ruta de procesamiento.

Cuando decidas dónde añadir la lógica, primero tendrás que elegir si quieres añadirla a un endpoint proxy o a un endpoint de destino. Un proxy de API divide su código entre el código que interactúa con el cliente del proxy (endpoint del proxy) y el código opcional que interactúa con el destino de backend del proxy, si lo hay (endpoint de destino).

Ambos endpoints contienen flujos, como se describe a continuación:

El flujo se configura con un archivo XML que especifica qué debe ocurrir y en qué orden. En la siguiente ilustración se muestra cómo se ordenan las secuencias de forma secuencial en un endpoint de proxy y en un endpoint de destino:

El endpoint de proxy y el endpoint de destino contienen flujos que puedes organizar en la siguiente secuencia:

Hacer que el código se ejecute primero con un PreFlow

Un PreFlow es útil cuando necesitas asegurarte de que se ejecute un código determinado antes de que ocurra cualquier otra cosa.

En un endpoint de proxy, PreFlow es un lugar ideal para el código que autentica a un cliente y limita el tráfico de los clientes. En un endpoint de destino, donde empieza a prepararse para enviar una solicitud a un destino de backend, un PreFlow es útil para dar los primeros pasos en la preparación del envío de la solicitud.

Por ejemplo, normalmente no querrás dar servicio a un cliente que haya superado su cuota. Para cumplir estos requisitos, debes colocar las políticas de seguridad y de cuota en el segmento PreFlow. De esta forma, no tendrás que preocuparte de que una condición no se evalúe en un flujo condicional posterior. Las políticas de este flujo siempre se ejecutarán antes de que se lleve a cabo cualquier otro proceso.

En el siguiente ejemplo, las políticas SpikeArrest y Quota se ejecutan antes de que el procesamiento pase a los flujos condicionales.

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

Hacer que el código se ejecute de forma condicional con un flujo condicional

Entre un PreFlow y un PostFlow, puedes tener flujos que se ejecuten de forma condicional. De esta forma, puedes configurar varias secuencias de lógica, pero solo se ejecutará una en función del estado de tu proxy. Un flujo condicional es opcional si puedes ejecutar toda la lógica en PreFlow o PostFlow y no se requiere ninguna condición (en otras palabras, solo se admite una ruta a través del endpoint).

Cada flujo especifica una condición que comprueba diferentes valores de estado. De esta forma, se bifurca la ejecución en función de las condiciones. Por ejemplo, puede que quieras convertir XML a JSON solo cuando la aplicación que hace la solicitud se esté ejecutando en un dispositivo móvil.

En este caso, las restricciones de cuota solo se aplican si la solicitud es una solicitud GET con un patrón de URI /issue/** (/issue/ con cualquier elemento en el URI después de la última barra inclinada).

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

Las variables de flujo se usan para especificar condiciones. Para obtener más información sobre el uso de variables en condiciones, consulta Condiciones con variables de flujo.

Para ver ejemplos de cómo usar la coincidencia de patrones en las condiciones, consulta Coincidencia de patrones.

Ejecutar código después de la lógica principal con un PostFlow

Un PostFlow es un buen lugar para realizar acciones después de la lógica principal de tu endpoint y antes de que finalice el procesamiento del endpoint. Un PostFlow se ejecuta después de los flujos condicionales y PreFlow.

Un PostFlow es un buen lugar para registrar algunos datos, enviar una notificación de que ha ocurrido algo, transformar el formato del mensaje de respuesta, etc.

En el siguiente ejemplo, una política AssignMessage llamada SetResponseHeaders define los encabezados del mensaje de respuesta antes de que Apigee envíe la respuesta al cliente.

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

Ejecutar código después de que el cliente reciba la respuesta de tu proxy con un PostClientFlow

Un PostClientFlow solo puede incluir las siguientes políticas. No se pueden usar otras políticas en un PostClientFlow:

• Política de FlowCallout^*
• Política MessageLogging
• Política ServiceCallout

^* La política FlowCallout solo puede llamar a flujos compartidos que cumplan los criterios para estar en PostClientFlow (es decir, que solo contengan políticas compatibles).

Si incluyes uno, PostClientFlow será el último flujo que se ejecute, después de que se envíe una respuesta al cliente.

PostClientFlow es útil para el registro final. También puedes registrar las marcas de tiempo de inicio y finalización del mensaje de respuesta.

A continuación, se muestra un ejemplo de PostClientFlow con una política MessageLogging adjunta.

  <ProxyEndpoint name="endpoint1">
    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...
  </ProxyEndpoint>

Para obtener más información, consulta la referencia de configuración de proxies de APIs.

Añadir lógica a los flujos

Cuando añades lógica a tu proxy, lo haces añadiendo políticas a los flujos del proxy. Al igual que los flujos se ejecutan en una secuencia (PreFlow, Flow y PostFlow, como se describe en este tema), el contenido de un flujo se ejecuta en una secuencia.

La siguiente configuración de flujo de ejemplo hace referencia a tres políticas (configuradas en otros lugares en sus propios archivos XML). La política a la que se hace referencia en Verify-API-Key se ejecuta antes que la política a la que se hace referencia en Assign-Message. Ambas se siguen por la política representada por Quota.

<Flow name="Get Food Cart Menus">
  <Description>Get Food Cart Menus</Description>
  <Request>
    <Step>
      <Name>Verify-API-Key</Name>
    </Step>
    <Step>
      <Name>Assign-Message</Name>
    </Step>
    <Step>
      <Name>Quota</Name>
    </Step>
  </Request>
  <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Depurar flujos

La herramienta de depuración ofrece una forma gráfica de ver cómo se ejecuta la lógica de tu proxy de API después de una solicitud. La herramienta muestra el procesamiento entre la solicitud y la respuesta. No se ilustra específicamente la separación entre PreFlow, los flujos condicionales y PostFlow.

Para obtener más información sobre la depuración de proxies, consulta Usar la herramienta de depuración.

Gestionar errores en los flujos

Puedes generar errores desde varios lugares de un proxy de API, incluidos los flujos.

El siguiente ejemplo es la stanza de respuesta de un PreFlow en un endpoint de destino. En otras palabras, es el código que se ejecuta inmediatamente después de recibir la respuesta de un destino backend. En el ejemplo, se produce un error si la respuesta del destino no es 200 (correcto).

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

Para obtener más información sobre la gestión de errores, consulta Gestión de errores.