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

Público

Este tema está destinado a los operadores de Edge Microgateway que deseen usar los complementos existentes que se instalan con el microgateway. También se analizan en detalle los complementos de Spike Arrest 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. Por ejemplo:

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 Cómo usar el complemento de cuotas.
spikearrest No Protege contra los aumentos repentinos de tráfico y los ataques DoS. Consulta Cómo usar el complemento de Spike Arrest.
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 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 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 datos de solicitud o respuesta en función de los encabezados de aceptación o de 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 se instala 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 sección para configurar el complemento de Spike Arrest. Consulta Cómo usar el complemento de Spike Arrest 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 se instala 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

Cómo usar el complemento de Spike Arrest

El complemento de Spike Arrest protege 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 Spike Arrest

Consulta Cómo agregar y configurar complementos.

Configuración de muestra para Spike Arrest

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 Spike Arrest

  • timeUnit: La frecuencia con la que se restablece la ventana de ejecución de Spike Arrest. 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, Spike Arrest 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 búfer. Consulta también Cómo agregar un búfer.

¿Cómo funciona Spike Arrest?

Piensa en Spike Arrest 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 Spike Arrest te ayuda a reducir el tráfico a las cantidades generales que deseas.

El comportamiento de Spike Arrest 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 frecuencia 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, Spike Arrest 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 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 = 100 milisegundos o 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 especificado, Spike Arrest muestra 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 muestra un error de inmediato cuando superas el límite de Spike Arrest. En cambio, las solicitudes se almacenan en búfer (hasta la cantidad especificada) y las solicitudes almacenadas en búfer se procesan tan pronto como 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 trabajo de Edge Micro que se estén ejecutando. Spike Arrest 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 quieres que Spike Arrest 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 Spike Arrest. En resumen, la regla general es establecer el parámetro de configuración allow en el valor "cantidad deseada de Spike Arrest / cantidad de procesos".

Cómo usar 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 Spike Arrest y la cuota?

Cómo agregar el complemento de cuotas

Consulta Cómo agregar y configurar complementos.

Configuración de productos 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 cuotas

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 cuotas

Para configurar el complemento de cuotas, agrega el quotas elemento 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 (Integer) El tamaño del búfer que se establecerá para el intervalo especificado. Las unidades de tiempo permitidas incluyen: hour, minute, day, week, month y default.
failOpen Cuando se habilita esta función, si se produce un error de procesamiento de cuotas o si la solicitud de “aplicación de cuotas” a Edge no actualiza los contadores de cuotas remotas, la cuota se procesará en función de los recuentos locales solo hasta que se produzca la siguiente sincronización de cuotas remotas exitosa. En ambos casos, se establece una marca quota-failed-open en el objeto de solicitud.

Para habilitar la función de “apertura de cuotas”, 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 cuotas.

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

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

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

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

Cómo usar un almacén de respaldo de Redis para cuotas

Para usar un almacén de respaldo de Redis para cuotas, usa la misma configuración que se usa para la función 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 Cómo usar el sincronizador.

Cómo probar el complemento de cuotas

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

{"error": "exceeded quota"}

¿Cuál es la diferencia entre Spike Arrest 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 Spike Arrest para protegerte contra los aumentos repentinos en el tráfico de API. Por lo general, Spike Arrest se usa para evitar posibles ataques DDoS o de otro tipo.