Cómo usar complementos

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Edge Microgateway v. 3.1.5 y versiones posteriores

Público

Este tema está dirigido a los operadores de Edge Microgateway que desean usar complementos existentes instalados con la microgateway. También se analiza en detalle la detención de aumentos repentinos y los complementos de cuota (ambos se incluyen en la instalación). Si eres desarrollador y quieres desarrollar complementos nuevos, consulta Cómo desarrollar complementos personalizados.

¿Qué es un complemento de Edge Microgateway?

Un complemento es un módulo de Node.js que agrega funcionalidad a Edge Microgateway. Los módulos de complementos siguen un patrón coherente y se almacenan en una ubicación conocida por Edge Microgateway, lo que permite que la micropuerta de enlace los descubra y los cargue de forma automática. Edge Microgateway incluye varios complementos existentes y también puedes crear complementos personalizados, como se explica en Desarrolla complementos personalizados.

Complementos existentes agrupados con Edge Microgateway

Varios complementos existentes se proporcionan con Edge Microgateway en la instalación. Por ejemplo:

Complemento Habilitado de forma predeterminada Descripción
Analytics Envía datos de estadísticas de Edge Microgateway a Apigee Edge.
oauth Agrega la validación de la clave de API y el token de OAuth a Edge Microgateway. Consulta Configura y configura Edge Microgateway.
cuota No Aplica una cuota en las solicitudes a Edge Microgateway. Usa Apigee Edge para almacenar y administrar las cuotas. Consulta Cómo usar el complemento de cuota.
arranquedepisos No Protege contra aumentos repentinos de tráfico y ataques DoS. Consulta Cómo usar el complemento de protección contra aumentos de tráfico.
encabezado-mayúsculas No Un proxy de ejemplo con comentarios que sirve de guía para ayudar a los desarrolladores a escribir complementos personalizados. Consulta el complemento de muestra de Edge Microgateway.
acumular-solicitud No Acumula datos de solicitud en un solo objeto antes de pasarlos al siguiente controlador en la cadena de complementos. Es útil para escribir complementos de transformación que deben operar en un único objeto de contenido de solicitud acumulado.
acumular-respuesta No Acumula datos de respuesta en un solo objeto antes de pasar los datos al siguiente controlador en la cadena de complementos. Es útil para escribir complementos de transformación que deben operar en un único objeto de contenido de respuesta acumulado.
transform-uppercase No Transforma los datos de solicitud o respuesta. Este complemento representa una implementación recomendada para un complemento de transformación. El complemento de ejemplo realiza una transformación trivial (convierte los datos de solicitud o respuesta en mayúsculas). Sin embargo, se puede adaptar con facilidad para realizar otros tipos de transformaciones, como de XML a JSON.
json2xml No Transforma los datos de solicitud o respuesta basados en encabezados de aceptación o de tipo de contenido. Para obtener más información, consulta la documentación del complemento en GitHub.
memoria de cuota No Aplica una cuota en las solicitudes a Edge Microgateway. Almacena y administra cuotas en la memoria local.
healthcheck No Muestra información sobre el proceso de Edge Microgateway (uso de memoria, de la CPU, etc.). Para usar el complemento, llama a la URL /healthcheck en la instancia de Edge Microgateway. Este complemento está diseñado como un ejemplo que puedes usar para implementar tu propio complemento de verificación de estado.

Dónde encontrar complementos existentes

Los complementos existentes agrupados con Edge Microgateway se encuentran aquí, en el que [prefix] es el directorio del prefijo npm. Consulta Dónde está instalado Edge Microgateway si no puedes encontrar este directorio.

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

Cómo agregar y configurar complementos

Sigue este patrón para agregar y configurar complementos:

  1. Detén Edge Microgateway.
  2. Abre un archivo de configuración de Edge Microgateway. Si quieres obtener más detalles, consulta Cómo realizar cambios en la configuración para ver opciones.
  3. Agrega el complemento al elemento plugins:sequence del archivo de configuración de la siguiente manera. Los complementos se ejecutan en el orden en el que aparecen en esta lista.
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
     level: info
     dir: /var/tmp
     stats_log_interval: 60
  plugins:
     dir: ../plugins
     sequence:   
     - oauth
     - plugin-name
  1. Configura el complemento. Algunos complementos tienen parámetros opcionales que puedes configurar en el archivo de configuración. Por ejemplo, puedes agregar la siguiente estrofa para configurar el complemento de protección contra aumentos repentinos. Consulta Cómo usar el complemento de protección contra aumentos de tráfico para obtener más información.
    edgemicro:
      home: ../gateway
      port: 8000
      max_connections: -1
      max_connections_hard: -1
      logging:
        level: info
        dir: /var/tmp
        stats_log_interval: 60
      plugins:
        dir: ../plugins
        sequence:
          - oauth
          - spikearrest
    spikearrest:
       timeUnit: minute
       allow: 10
    
  1. Guarda el archivo.
  2. Reinicia o vuelve a cargar Edge Microgateway, según el archivo de configuración que editaste.

Configuración específica de complementos

Puedes anular los parámetros del complemento especificados en el archivo de configuración creando una configuración específica del complemento en este directorio:

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config

donde [prefix] es el directorio del prefijo npm. Consulta Dónde está instalado Edge Microgateway si no puedes encontrar este directorio.

plugins/<plugin_name>/config/default.yaml. Por ejemplo, puedes colocar este bloque en plugins/spikearrest/config/default.yaml, lo que anulará cualquier otra configuración de configuración.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Cómo usar el complemento de protección contra aumentos repentinos

El complemento de protección contra aumentos de tráfico brinda protección contra los aumentos repentinos de tráfico. Limita la cantidad de solicitudes que procesa una instancia de Edge Microgateway.

Cómo agregar el complemento de protección contra aumentos

Consulta la sección Cómo agregar y configurar complementos.

Configuración de muestra para la protección contra aumentos repentinos

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
   bufferSize: 5

Opciones de configuración para la protección contra aumentos repentinos

  • timeUnit: Es la frecuencia con la que se restablece la ventana de ejecución de protección contra aumentos de tráfico. Los valores válidos son segundos o minutos.
  • allow: Es la cantidad máxima de solicitudes que se permiten durante timeUnit. Consulta también Si ejecutas varios procesos de Edge Micro.
  • bufferSize: (opcional, predeterminado = 0) si bufferSize > 0, la protección contra aumentos repentinos almacena esta cantidad de solicitudes en un búfer. En cuanto ocurra la próxima “ventana” de ejecución, las solicitudes almacenadas en búfer se procesarán primero. Consulta también Cómo agregar un búfer.

¿Cómo funciona la prevención del aumento de picos?

Piensa en la protección contra aumentos repentinos como una forma de protegerte, en general, de los aumentos de tráfico, en lugar de limitarlo a una cantidad específica de solicitudes. Tus API y tu backend pueden controlar una cantidad determinada de tráfico, y la política de protección contra aumentos repentinos te ayuda a suavizar el tráfico a las cantidades generales que desees.

El comportamiento de detención de aumentos repentinos del tiempo de ejecución difiere de lo que puedes esperar de los valores literales por minuto o por segundo que ingresas.

Por ejemplo, supongamos que especificas una tasa de 30 solicitudes por minuto, de la siguiente manera:

spikearrest:
   timeUnit: minute
   allow: 30

Durante la prueba, podrías pensar que puedes enviar 30 solicitudes en 1 segundo, siempre que lleguen en un minuto. Pero la política no aplica la configuración de esa manera. Si lo piensas, 30 solicitudes en un período de 1 segundo podrían considerarse un pequeño aumento en algunos entornos.

¿Qué ocurre entonces? Para evitar un comportamiento similar al de los aumentos repentinos, la protección contra aumentos suaviza el tráfico permitido dividiendo la configuración en intervalos más pequeños, de la siguiente manera:

Tarifas por minuto

Las tarifas por minuto se suavizan en intervalos de segundos permitidos para las solicitudes. Por ejemplo, 30 solicitudes por minuto se suavizan de la siguiente manera:

60 segundos (1 minuto) / 30 = intervalos de 2 segundos, o aproximadamente 1 solicitud permitida cada 2 segundos. Una segunda solicitud en un plazo de 2 segundos fallará. Además, la solicitud 31 en un minuto fallará.

Tarifas por segundo

Las tasas por segundo se suavizan en las solicitudes permitidas en intervalos de milisegundos. Por ejemplo, 10 solicitudes por segundo se suavizan de la siguiente manera:

1, 000 milisegundos (1 segundo) / 10 = intervalos de 100 milisegundos o alrededor de 1 solicitud permitida cada 100 milisegundos . Una segunda solicitud dentro de los 100 ms fallarán. Además, una 11a solicitud en un segundo fallará.

Si se excede el límite

Si el número de solicitudes excede el límite dentro del intervalo de tiempo especificado, la protección contra aumentos repentinos muestra este mensaje de error con el estado HTTP 503:

{"error": "spike arrest policy violated"}

Cómo agregar un búfer

Tienes la opción de agregar un búfer a la política. Supongamos que estableces el búfer en 10. Verás que la API no muestra un error de inmediato cuando superas el límite de protección por aumento de errores. En cambio, las solicitudes se almacenan en búfer (hasta el número especificado), y estas se procesan en cuanto esté disponible la siguiente ventana de ejecución adecuada. El valor predeterminado de bufferSize es 0.

Si ejecutas varios procesos de Edge Micro

La cantidad de solicitudes permitidas depende de la cantidad de procesos de trabajadores de Edge Micro que se ejecuten. La protección contra aumentos repentinos calcula la cantidad permitida de solicitudes por proceso de trabajador. De forma predeterminada, la cantidad de procesos de Edge Micro equivale a la cantidad de CPU en la máquina en la que está instalado Edge Micro. Sin embargo, puedes configurar la cantidad de procesos trabajadores cuando inicias Edge Micro mediante la opción --processes en el comando start. Por ejemplo, si deseas que la protección contra aumentos de tráfico se active a las 100 solicitudes en un período determinado y, si inicias Edge Microgateway con la opción --processes 4, configura allow: 25 en la configuración de la protección contra aumentos de tráfico. En resumen, la regla general es establecer el parámetro de configuración de allow en el valor "recuento de protección contra aumentos repentinos deseado / cantidad de procesos".

Cómo usar el complemento de cuota

Una cuota especifica la cantidad de mensajes de solicitud que una app puede enviar a una API en el transcurso de una hora, un día, una semana o un mes. Cuando una app alcanza su límite de cuota, se rechazan las siguientes llamadas a la API. Consulta también la sección ¿Cuál es la diferencia entre la retención de aumentos repentinos y la cuota?

Agrega el complemento de cuota

Consulta la sección Cómo agregar y configurar complementos.

Configuración del producto en Apigee Edge

Las cuotas se configuran en la IU de Apigee Edge donde configuras los productos de API. Debes saber qué producto contiene el proxy compatible con micropuertas de enlace que quieres limitar con una cuota. Se debe agregar este producto a una app de desarrollador. Cuando realices llamadas a la API que se autentican con claves en la app de desarrollador, la cuota se aplicará a esas llamadas a la API.

  1. Accede a tu cuenta de organización de Apigee Edge.
  2. En la IU de Edge, abre el producto asociado con el proxy compatible con micropuerta de enlace al que deseas aplicar la cuota.
    1. En la IU, selecciona Productos en el menú Publicar.
    2. Abre el producto que contiene la API a la que quieres aplicar la cuota.
    3. Haz clic en Editar.
    4. En el campo Cuota, especifica el intervalo de la cuota. Por ejemplo, 100 solicitudes cada un minuto. O 50,000 solicitudes cada 2 horas.

  1. Haz clic en Guardar.
  2. Asegúrate de que el producto se agregue a una app de desarrollador. Necesitarás las claves de esta app para realizar llamadas autenticadas a la API.

Configuración de muestra para la cuota

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota

Opciones de configuración para la cuota

Para configurar el complemento de cuota, agrega el elemento quotas a tu archivo de configuración, como se muestra en el siguiente ejemplo:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota
quotas:
    bufferSize:
      hour: 20000
      minute: 500
      month: 1
      default: 10000
    useDebugMpId: true
    failOpen: true
...
Opción Descripción
bufferSize

La configuración bufferSize te permite ajustar la frecuencia con la que Edge Microgateway sincroniza el recuento de cuotas con Apigee Edge. Para comprender bufferSize, considera el siguiente ejemplo de configuración:

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: true

De forma predeterminada, la micropuerta de enlace sincroniza su contador de cuotas con Apigee Edge cada 5 segundos si el intervalo de cuota se establece en “minuto”. La configuración anterior indica que, si el intervalo de cuota se establece en el producto de la API como “minuto”, Edge Microgateway se sincronizará con Edge para obtener el recuento de cuota actual después de cada 500 solicitudes o después de 5 segundos, lo que ocurra primero. Para obtener más información, consulta Información sobre cómo se cuentan las cuotas.

Las unidades de tiempo permitidas incluyen las siguientes: minute, hour, day, week, month y default.

failOpen Cuando esta función está habilitada, si se produce un error de procesamiento de cuota o si la solicitud de “aplicación de cuota” a Edge no puede actualizar los contadores de cuotas remotas, la cuota se procesará en función de los recuentos locales solo hasta que se produzca la próxima sincronización de cuota remota. En ambos casos, se establece una marca quota-failed-open en el objeto de la solicitud.

Para habilitar la función de "fail open" de la cuota, establece la siguiente configuración:

edgemicro:
...
quotas:
  failOpen: true
...
useDebugMpId Establece esta marca en true para habilitar el registro del ID de MP (procesador de mensajes) en las respuestas de cuota.

Para utilizar esta función, debes establecer la siguiente configuración:

edgemicro:
...
quotas:
  useDebugMpId: true
...

Cuando se configura useDebugMpId, las respuestas de cuota de Edge contendrán el ID de MP y Edge Microgateway registrará. Por ejemplo:

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}
useRedis Si se configura en true, el complemento usa Redis para el almacén de respaldo de cuotas. Para obtener más información, consulta Cómo usar un almacén de copia de seguridad de Redis para la cuota.

Comprende cómo se cuentan las cuotas

De forma predeterminada, la micropuerta de enlace sincroniza su contador de cuotas con Apigee Edge cada 5 segundos si el intervalo de cuota se establece en “minuto”. Si el intervalo se establece en un nivel superior a "minuto", como "semana" o "mes", el período de actualización predeterminado será de 1 minuto.

Es importante tener en cuenta que especificas intervalos de cuota en los productos de API que se definen en Apigee Edge. Los intervalos de cuota especifican cuántas solicitudes se permiten por minuto, hora, día, semana o mes. Por ejemplo, el producto A podría tener un intervalo de cuota de 100 solicitudes por minuto, y el producto B podría tener un intervalo de cuota de 10,000 solicitudes por hora.

La configuración YAML del complemento quota de Edge Microgateway no establece el intervalo de la cuota, sino que proporciona una forma de ajustar la frecuencia con la que una instancia local de Edge Microgateway sincroniza su recuento de cuotas con Apigee Edge.

Por ejemplo, supongamos que hay tres productos de API definidos en Apigee Edge con los siguientes intervalos de cuota especificados:

  • El producto A tiene una cuota de 100 solicitudes por minuto.
  • El producto B tiene una cuota de 5,000 solicitudes por hora.
  • El producto C tiene una cuota de 1,000,000 de solicitudes por mes

Con esa configuración de cuota en mente, ¿cómo se debe configurar el complemento quota de Edge Microgateway? La práctica recomendada es configurar Edge Microgateway con intervalos de sincronización que sean menores que los intervalos de cuota definidos en los productos de API. Por ejemplo:

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

Esta configuración define los siguientes intervalos de sincronización para los productos de API descritos anteriormente:

  • El producto A se establece en el intervalo de “minutos”. Edge Microgateway se sincronizará con Edge cada 50 solicitudes o 5 segundos, lo que ocurra primero.
  • El producto B se establece en el intervalo de “horas”. Edge Microgateway se sincronizará con Edge después de cada solicitud número 2,000 o 1 minuto, lo que ocurra primero.
  • El producto C está configurado en el intervalo “mes”. Edge Microgateway se sincronizará con Edge después de cada solicitud o 1 minuto, lo que ocurra primero.

Cada vez que una instancia de micropuerta de enlace se sincroniza con Edge, el recuento de cuotas de esta se establece en el recuento de cuotas recuperado.

La configuración de bufferSize te permite ajustar la forma en que se sincroniza el contador de cuotas con Edge. En situaciones de mucho tráfico, la configuración bufferSize permite que el contador del búfer se sincronice antes de que se active la sincronización predeterminada basada en el tiempo.

Información sobre el alcance de la cuota

El recuento de cuotas se limita a un entorno de una organización. Para lograr este alcance, Edge Microgateway crea un identificador de cuotas que es una combinación de “organización + env + appName + productName”.

Usa un almacén de respaldo de Redis para la cuota

Si quieres usar un almacén de copia de seguridad de Redis para la cuota, usa la misma configuración de la función de Synchronizer. A continuación, se muestra la configuración básica necesaria para usar Redis para el almacenamiento de cuotas:

edgemicro:
  redisHost: localhost
  redisPort: 6379
  redisDb: 2
  redisPassword: codemaster

quotas:
  useRedis: true
Para obtener detalles sobre los parámetros edgemicro.redis*, consulta Usa el sincronizador.

Prueba el complemento de cuota

Cuando se supera la cuota, se muestra un estado HTTP 403 al cliente, junto con el siguiente mensaje:

{"error": "exceeded quota"}

¿Cuál es la diferencia entre la retención contra aumentos repentinos y la cuota?

Es importante elegir la herramienta adecuada para el trabajo en cuestión. Las políticas de cuotas configuran la cantidad de mensajes de solicitud que una app cliente puede enviar a una API en el transcurso de una hora, un día, una semana o un mes. La política de cuotas aplica límites de consumo en las apps cliente mediante el mantenimiento de un contador distribuido que cuenta las solicitudes entrantes.

Usa una política de cuotas para aplicar contratos comerciales o ANS con desarrolladores y socios, en lugar de hacerlo para la administración del tráfico operativo. Por ejemplo, una cuota podría usarse para limitar el tráfico de un servicio gratuito y, al mismo tiempo, permitir el acceso completo a los clientes que pagan.

Usa la protección contra aumentos de tráfico para protegerte de los aumentos repentinos en el tráfico de la API. Por lo general, la protección contra aumentos repentinos se usa para evitar posibles ataques DSD y otros tipos maliciosos.