Cómo usar complementos

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

Edge Microgateway v. 2.5.x

Público

Este tema está dirigido a los operadores de Edge Microgateway que desean usar los complementos existentes que se instalan con el microgateway. También se analizan en detalle los complementos de protección contra aumentos repentinos y de cuotas (ambos se incluyen con la instalación). Si eres desarrollador y quieres crear 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 que conoce Edge Microgateway, lo que permite que el microgateway los descubra y los cargue automáticamente. Edge Microgateway incluye varios complementos existentes y también puedes crear complementos personalizados, como se explica en Cómo desarrollar complementos personalizados.

Complementos existentes incluidos con Edge Microgateway

Se proporcionan varios complementos existentes con Edge Microgateway durante la instalación. Estos incluyen los siguientes:

Complemento Habilitado de forma predeterminada Descripción
Analytics Sí Envía datos de estadísticas de Edge Microgateway a Apigee Edge.
oauth Sí Agrega la validación de la clave de API y el token de OAuth a Edge Microgateway. Consulta Cómo configurar Edge Microgateway.
quota No Aplica cuotas a las solicitudes a Edge Microgateway. Usa Apigee Edge para almacenar y administrar las cuotas. Consulta Usa el complemento de cuotas.
spikearrest No Protege contra los aumentos repentinos de tráfico y los ataques DoS. Consulta Usa el complemento de protección contra aumentos repentinos.
header-uppercase No Un proxy de muestra comentado que se diseñó como guía para ayudar a los desarrolladores a escribir complementos personalizados. Consulta Complemento de muestra de Edge Microgateway.
accumulate-request No Acumula datos de solicitud 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 solo objeto de contenido de solicitud acumulado.
accumulate-response 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 solo objeto de contenido de respuesta acumulado.
transform-uppercase No Transforma los datos de solicitud o respuesta. Este complemento representa una implementación de práctica recomendada implementación de un complemento de transformación. El complemento de ejemplo realiza una transformación trivial (convierte los datos de solicitud o respuesta a mayúsculas); sin embargo, se puede adaptar fácilmente para realizar otros tipos de transformaciones, como de XML a JSON.
json2xml No Transforma los datos de solicitud o respuesta en función de los encabezados de aceptación o tipo de contenido. Para obtener más detalles, consulta la documentación del complemento en GitHub.
quota-memory No Aplica cuotas a 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, uso de CPU, etcétera). Para usar el complemento, llama a la URL /healthcheck en tu instancia de Edge Microgateway. Este complemento está diseñado para ser un ejemplo que puedes usar para implementar tu propio complemento de verificación de estado.

Dónde encontrar complementos existentes

Los complementos existentes incluidos con Edge Microgateway se encuentran aquí, donde [prefix] es el npm directorio de prefijo. 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. Para obtener más detalles, consulta Cómo realizar cambios de configuración para las opciones.
  3. Agrega el complemento al elemento plugins:sequence del archivo de configuración, como se indica a continuación. Los complementos se ejecutan en el orden en 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 Usa el complemento de protección contra aumentos repentinos 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 del complemento

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 de 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 y anulará cualquier otro parámetro de configuración.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Usa el complemento de protección contra aumentos repentinos

El complemento de protección contra aumentos repentinos protege contra los aumentos repentinos de tráfico. Limita la cantidad de solicitudes procesadas por una instancia de Edge Microgateway.

Agrega el complemento de protección contra aumentos repentinos

Consulta 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: La frecuencia con la que se restablece la ventana de ejecución de la protección contra aumentos repentinos. Los valores válidos son segundo o minuto.
  • allow: La cantidad máxima de solicitudes que se permiten durante el timeUnit. Consulta también Si ejecutas varios procesos de Edge Micro processes.
  • bufferSize: (opcional, valor predeterminado = 0) si bufferSize > 0, la protección contra aumentos repentinos almacena esta cantidad de solicitudes en un búfer. Tan pronto como se produzca la siguiente "ventana" de ejecución, se procesarán primero las solicitudes almacenadas en el búfer. Consulta también Agrega un búfer.

¿Cómo funciona la protección contra aumentos repentinos?

Piensa en la protección contra aumentos repentinos como una forma de protección general acerca de los aumentos repentinos de tráfico en lugar de como una forma de limitar el tráfico a una cantidad específica de solicitudes. Tus APIs y backend pueden manejar una cierta cantidad de tráfico y la política de protección contra aumentos repentinos te ayuda a reducir el tráfico a las cantidades generales que deseas.

El comportamiento de la protección contra aumentos repentinos del entorno de ejecución es distinto a lo que podrías 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

En las pruebas, podrías pensar que podrías enviar 30 solicitudes en 1 segundo, siempre que estén dentro de un minuto. Pero esa no es la forma en que la política aplica la configuración. Si lo piensas, 30 solicitudes en un período de 1 segundo se podrían considerar un pequeño aumento en algunos entornos.

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

Tarifas por minuto

Las tarifas por minuto se suman a las solicitudes completas permitidas en intervalos de segundos. Por ejemplo, 30 solicitudes por minuto se mitigan de la siguiente manera:

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

Tarifas por segundo

Las tarifas por segundo se suman a las solicitudes completas permitidas en intervalos de milisegundos. Por ejemplo, 10 solicitudes por segundo se mitigan de la siguiente manera:

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

Cuando se supera el límite

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

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

Agrega 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 contra aumentos repentinos. En cambio, las solicitudes se almacenan en el búfer (hasta la cantidad especificada) y las solicitudes almacenadas en el búfer se procesan tan pronto como esté disponible la siguiente ventana de ejecución adecuada. El bufferSize predeterminado es 0.

Si ejecutas varios procesos de Edge Micro

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

Usa el complemento de cuotas

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

Agrega el complemento de cuotas

Consulta Cómo agregar y configurar complementos.

Configuración del producto en Apigee Edge

Configuras las cuotas en la IU de Apigee Edge, donde configuras los productos de API. Debes saber qué producto contiene el proxy adaptado al microgateway que deseas limitar con una cuota. Este producto se debe agregar a una app para desarrolladores. Cuando realizas llamadas a la API que se autentican con claves en la app para desarrolladores, 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 adaptado al microgateway 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 deseas aplicar la cuota.
    3. Haz clic en Editar.
    4. En el campo Cuota, especifica el intervalo de 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 para desarrolladores. Necesitarás las claves de esta app para realizar llamadas a la API autenticadas.

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

Prueba el complemento de cuotas

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 protección contra aumentos repentinos y la cuota?

Es importante elegir la herramienta adecuada para la tarea 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, día, semana o mes. La política de cuotas aplica límites de consumo a las apps cliente mediante el mantenimiento de un contador distribuido que aumenta 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, a la vez que permite el acceso completo a los clientes que pagan.

Usa la protección contra aumentos repentinos para protegerte contra los aumentos repentinos en el tráfico de API. Por lo general, la protección contra aumentos repentinos se usa para evitar posibles ataques DDoS o de otro tipo.