Cómo usar complementos

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

Edge Microgateway v. 3.2.x

Público

Este tema está dirigido a los operadores de Edge Microgateway que deseen usar complementos existentes que se instalan con microgateway. También se analizan los complementos de cuotas y protección contra el aumento (ambos están incluidos en la instalación). Si eres desarrollador y quieres desarrollar nuevos consulta Desarrollo de aplicaciones complementos personalizados.

¿Qué es un complemento de Edge Microgateway?

Un complemento es un módulo de Node.js que agrega funcionalidad a Edge Microgateway. Módulos de complementos siguen un patrón coherente y se almacenan en una ubicación conocida por Edge Microgateway, lo que permite microgateway para descubrirlos y cargarlos automáticamente. Edge Microgateway incluye varios componentes y también puedes crear complementos personalizados, como se explica en Cómo desarrollar complementos personalizados.

Complementos existentes empaquetados con Edge Micropuerta de enlace

Edge Microgateway proporciona varios complementos existentes en la instalación. Estos incluyen:

Complemento Habilitado de forma predeterminada Descripción
Analytics Sí Envía datos de estadísticas de Edge Microgateway a Apigee Edge.
oauth Sí Agrega el token de OAuth y la validación de la clave de API a Edge Microgateway. Consulta Configuración configurar y configurar Edge Microgateway.
cuota No Aplica la cuota de las solicitudes a Edge Microgateway. Usa Apigee Edge para almacenar y administrar las cuotas. Consulta Cómo usar el complemento de cuota.
pezarto No Protege contra los aumentos repentinos de tráfico y los ataques DoS. Consulta Cómo usar el complemento de protección contra aumentos de tráfico.
encabezado-mayúscula No Un proxy de muestra con comentarios diseñado 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 de la cadena de complementos. Es útil para escribir complementos de transformación que deben operar en un único objeto de contenido de solicitud acumulado.
accumulate-response No Acumula datos de respuesta en un único objeto antes de pasar los datos al siguiente de la cadena de complementos. Es útil para escribir complementos de transformación que deben operar en un único objeto de contenido de respuesta acumulado.
transformar mayúsculas No Transforma datos de solicitudes o respuestas. Este complemento representa una práctica recomendada de un complemento de transformación. El complemento de ejemplo realiza una transformación trivial (convierte los datos de las solicitudes o las respuestas en mayúsculas). sin embargo, puede adaptarse fácilmente a realizar otros tipos de transformaciones, como XML a JSON.
json2xml No Transforma datos de solicitudes o respuestas en función de encabezados de aceptación o de tipo de contenido. Para detalles, consulta la página del complemento en GitHub.
memoria-de-cuota No Aplica la cuota de las solicitudes a Edge Microgateway. Almacena y administra cuotas en almacenamiento local memoria.
verificación de estado No Devuelve información sobre el proceso de Edge Microgateway: el uso de memoria, de la CPU, etc. Para usar el complemento, llama a la URL /healthcheck en tu perímetro. Instancia de Microgateway. Este complemento está diseñado para ser un ejemplo que puedas usar en implementar tu propio complemento de verificación de estado.

Dónde encontrar los complementos existentes

Los complementos existentes que se incluyen en 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. Para obtener detalles, consulta Realiza cambios en la configuración de las 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 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 de configuración de Terraform. Por ejemplo, puedes agregar la siguiente estrofa para configurar la protección contra aumentos de tráfico . 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 hayas editado.

Configuración específica de complementos

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

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

En el ejemplo anterior, [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 poner esta bloquear en plugins/spikearrest/config/default.yaml y anularán cualquier otro de la configuración.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Cómo usar el complemento de protección contra aumentos de tráfico

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

Agrega el complemento de protección contra aumentos de tráfico

Consulta Cómo agregar y configurar complementos.

Configuración de ejemplo para protección contra disparos

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 protección contra disparos

  • timeUnit: Es la frecuencia con la que se restablece la ventana de ejecución de protección contra aumentos de tráfico. Valores válidos son segundos o minutos.
  • allow: La cantidad máxima de solicitudes que se permiten durante la timeUnit. Consulta Si ejecutas múltiples aplicaciones procesos.
  • bufferSize: (opcional, predeterminado = 0) si bufferSize > 0, protección contra puntas almacena esta cantidad de solicitudes en un búfer. En cuanto la siguiente "ventana" de ejecución se produce el las solicitudes almacenadas en búfer se procesarán primero. Consulta también Cómo agregar un elemento búfer.

¿Cómo funciona la protección contra puntas?

Piensa en la protección contra aumentos repentinos como una forma de protegerse generalmente contra los aumentos repentinos de tráfico, en lugar de como y permite limitar el tráfico a una cantidad específica de solicitudes. Tus APIs y backend pueden controlar una cierta de tráfico, y la política de protección contra aumentos repentinos de tráfico te ayuda a facilitar el tráfico a las cantidades generales deseado.

El comportamiento de protección contra aumentos repentinos en el tiempo de ejecución difiere de lo que podrías esperar ver en relación los valores por minuto o por segundo que ingreses.

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 puedes enviar 30 solicitudes en 1 segundo, siempre y cuando lleguen en un minuto. Pero esa no es la forma en que la política aplica la configuración. Si lo piensas, 30 solicitudes realizadas en un período de 1 segundo podrían considerarse un aumento repentino en algunos entornos.

¿Qué ocurre entonces? Para evitar un comportamiento similar a un pico, la protección contra puntas suaviza las de tráfico dividiendo tu configuración en intervalos más pequeños, de la siguiente manera:

Tarifas por minuto

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

60 segundos (1 minuto) / 30 = intervalos de 2 segundos, o bien se permite aproximadamente 1 solicitud cada 2 segundos. R por una segunda solicitud en un plazo de 2 segundos fallará. Además, si la solicitud número 31 falla en un minuto, también fallará.

Tarifas por segundo

Las tasas por segundo se suavizan en 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 aproximadamente 1 solicitud permitida cada 100 milisegundos . Una segunda solicitud dentro de los 100 ms fallarán. Además, una undécima solicitud un segundo fallará.

Si se supera el límite

Si la cantidad de solicitudes excede el límite dentro del intervalo de tiempo especificado, la detención del aumento repentino devuelve este mensaje de error con un 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 devuelve un error de inmediato cuando excedas la protección contra el aumento repentino. límite. En cambio, las solicitudes se almacenan en búfer (hasta el número especificado) y las solicitudes almacenadas en búfer se almacenan en búfer tan pronto como esté disponible el siguiente período de ejecución adecuado. Predeterminado bufferSize es 0.

Si ejecutas varias funciones de Edge Micro procesos

La cantidad de solicitudes permitidas depende de la cantidad de procesos de microtrabajadores de Edge que se en ejecución. La detención de picos calcula la cantidad permitida de solicitudes por proceso de trabajador. De forma predeterminada, La cantidad de procesos de Edge Micro es igual a la cantidad de CPU de la máquina en la que está Edge Micro esté instalado. Sin embargo, puedes configurar la cantidad de procesos de trabajadores cuando inicias Edge Micro. Mediante la opción --processes en el comando start. Por ejemplo, si quieres que la detección de aumentos repentinos se active a las 100 solicitudes en un período determinado y, si inicias Microgateway con la opción --processes 4 y, luego, configurar allow: 25 en el configuración de protección contra aumentos de tráfico. En resumen, la regla general es establecer la configuración de allow. con el valor "recuento deseado de protección contra aumentos de tráfico / 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, día, semana o mes. Cuando una app alcanza su límite de cuota, las Se rechazan las llamadas a la API. Consulta también ¿Cuál es la diferencia entre la cuota y la detención del aumento repentino?

Agrega el complemento de cuota

Consulta Cómo agregar y configurar complementos.

Configuración de productos en Apigee Perimetrales

Las cuotas se configuran en la IU de Apigee Edge, en la que se configuran los productos de API. Debes saber qué producto contiene el proxy con micropuertas de enlace que quieres limitar con una cuota. Esta El producto debe agregarse a una app de desarrollador. Cuando realizas llamadas a la API que se autentican con en la app de desarrollador, se aplicará la cuota 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 con reconocimiento de micropuertas de enlace al que en el que quieres 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 de desarrollador. Necesitarás las claves de esta app para hacer lo siguiente: las 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 de la cuota

Para configurar el complemento de cuota, agrega el elemento quotas al 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

(Número entero) La configuración de bufferSize te permite ajustar la frecuencia con la que Edge Microgateway y sincroniza su recuento de cuotas con Apigee Edge. Para comprender bufferSize, considera la siguiente configuración de ejemplo: 

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

De forma predeterminada, microgateway sincroniza su contador de cuotas con Apigee Edge cada 5 segundos si de que el intervalo de cuota se establezca en "minuto". La configuración anterior indica que si el intervalo de cuota se establece en el producto de API, "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 Comprende cómo se cuentan las cuotas.

Tiempo permitido unidades incluyen: 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 "cuota aplicable" solicitud a Edge no puede actualizar los contadores de cuota remotos, la cuota se procesarán en función de recuentos locales solo hasta la próxima cuota remota exitosa de que ocurra la sincronización. En ambos casos, una marca quota-failed-open se establece en el objeto de la solicitud.

Habilita la cuota “fail open” establece la siguiente configuración: 

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

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

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

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

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

Comprende cómo se cuentan las cuotas

De forma predeterminada, microgateway sincroniza su contador de cuotas con Apigee Edge cada 5 segundos si de que el intervalo de cuota se establezca en "minuto". Si el intervalo se establece en un nivel superior a "minuto", como "semana" o “mes”, el período de actualización predeterminado es 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 están permitidas por minuto, hora, día, semana o mes. Por ejemplo, el producto A puede tener un intervalo de cuota de 100 solicitudes por minuto y el producto B puede tener un intervalo de cuota de 10,000 solicitudes por hora.

El YAML del complemento quota de Edge Microgateway configuración no establece la cuota interval; sino que proporciona una forma de ajustar la frecuencia con la que una Edge Microgateway local la instancia sincroniza su cuota con Apigee Edge.

Por ejemplo, supongamos que hay tres productos de API definidos en Apigee Edge con los siguientes elementos: 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 debería el complemento quota de Edge Microgateway configurar? La práctica recomendada es configurar Edge Microgateway con intervalos de sincronización que son inferiores a 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 "minuto". durante un intervalo de tiempo determinado. Edge Microgateway se sincronizará con Edge después de cada 50 segundos o cada 50 segundos, lo que ocurra primero.
  • El producto B se establece en la "hora" durante un intervalo de tiempo determinado. Edge Microgateway se sincronizará con Edge después de cada 2,000 solicitudes o 1 minuto, lo que ocurra primero.
  • El producto C se establece en "mes". durante un intervalo de tiempo determinado. Edge Microgateway se sincronizará con Edge después de con cada solicitud o cada minuto, lo que ocurra primero.

Cada vez que una instancia de microgateway se sincroniza con Edge, el el recuento de la cuota se establece en el recuento de cuota recuperado.

La configuración de bufferSize te permite ajustar la forma en que el contador de cuotas se sincroniza con Edge. En situaciones de mucho tráfico, la configuración de bufferSize Permite que el contador de 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 la cuota se limita a un entorno de una organización. Para lograr este alcance, Edge Microgateway crea un identificador de cuota que es una combinación de “org + env + appName + productName".

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

Para usar un almacén de respaldo de Redis para la cuota, usa la misma configuración que Función Synchronizer. A continuación, encontrarás la configuración básica necesaria para usar Redis cuota de almacenamiento: 

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

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

Prueba el complemento de cuota

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

{"error": "exceeded quota"}

Cuál es la diferencia entre la protección contra un aumento repentino y la cuota?

Es importante elegir la herramienta adecuada para cada trabajo. Configuración de las políticas de cuotas la cantidad de mensajes de solicitud que una app cliente puede enviar a una API durante el curso de una hora, día, semana o mes. La política de cuotas aplica límites de consumo en las apps cliente mantener un contador distribuido que cuente las solicitudes entrantes.

Usar una política de cuotas para hacer cumplir los contratos comerciales o ANS con los desarrolladores y socios, en lugar que para la administración de tráfico operativo. Por ejemplo, se podría usar una cuota para limitar el tráfico un servicio gratuito, al mismo tiempo que permite el acceso completo a los clientes que pagan.

Usa la protección contra los aumentos repentinos en el tráfico de API. Por lo general, la protección contra aumentos repentinos que se usan para evitar posibles ataques de DDoS u otros ataques maliciosos.