Uso de complementos

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

Edge Microgateway v. 2.4.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 deseas 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 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 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 Usa 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 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í, donde [prefix] es el directorio del prefijo npm. Consulta Dónde está instalado Edge Microgateway.

[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 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, como se explica en Realiza cambios en la configuración.

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.

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

En esta sección, se analiza el complemento de protección contra aumentos repentinos.

Acerca de la protección contra aumentos repentinos

Spike Arrest protege contra los aumentos de tráfico. Limita la cantidad de solicitudes que procesa una instancia de Edge Microgateway. Para obtener más información, consulta ¿Cómo funciona la protección contra aumentos repentinos? Consulta también la sección ¿Cuál es la diferencia entre la retención de aumentos repentinos y la cuota?

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

Para conocer los pasos básicos que se deben seguir para cualquier complemento, 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: 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.
  • 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 la cantidad de solicitudes excede el límite dentro del intervalo de tiempo especificado, la alerta de aumento repentino 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 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.

Cómo usar el complemento de cuota

En esta sección, se analiza el complemento de cuota.

Información acerca del 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

Para conocer los pasos básicos que se deben seguir para cualquier complemento, consulta 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. Consulta también Cómo usar el complemento de cuota.

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.