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. 2.5.x

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

No hay opciones de configuración adicionales para el complemento de cuota.

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.