Как использовать плагины

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Edge Microgateway версии 3.3.x

Аудитория

Эта статья предназначена для операторов Edge Microgateway, которые хотят использовать существующие плагины, установленные вместе с микрошлюзом. Также в нем подробно рассматриваются плагины spike arrest и quota, которые устанавливаются вместе с продуктом. Если вы разработчик и хотите создавать новые плагины, ознакомьтесь с разделом Разработка собственных плагинов.

Что такое плагин Edge Microgateway?

Плагин – это модуль Node.js, который добавляет функции в Edge Microgateway. Модули плагинов следуют единому шаблону и хранятся в известном Edge Microgateway месте, что позволяет микрошлюзу автоматически обнаруживать и загружать их. Edge Microgateway включает несколько существующих плагинов, а также позволяет создавать собственные плагины, как описано в разделе Разработка собственных плагинов.

Существующие плагины, поставляемые вместе с Edge Microgateway

При установке Edge Microgateway предоставляется ряд плагинов. В таблице ниже описаны некоторые из наиболее часто используемых плагинов.

Где найти существующие плагины

Существующие плагины, поставляемые вместе с Edge Microgateway, находятся в каталоге [prefix], где npm – это префикс каталога. Если вы не можете найти этот каталог, ознакомьтесь с разделом Где установлен Edge Microgateway.

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

Как добавлять и настраивать плагины

Чтобы добавить и настроить плагины, выполните следующие действия:

1. Остановите Edge Microgateway.
2. Откройте файл конфигурации Edge Microgateway. Подробнее о том, как изменить конфигурацию…
3. Добавьте плагин в элемент plugins:sequence файла конфигурации, как показано ниже. Плагины выполняются в том порядке, в котором они указаны в списке.

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

4. Настройте плагин. У некоторых плагинов есть необязательные параметры, которые можно настроить в файле конфигурации. Например, вы можете добавить следующий раздел, чтобы настроить плагин 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

5. Сохраните файл.
6. Перезапустите или обновите Edge Microgateway в зависимости от того, какой файл конфигурации вы отредактировали.

Конфигурация плагина

Вы можете переопределить параметры плагина, указанные в файле конфигурации, создав в этом каталоге конфигурацию для определенного плагина:

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

где [prefix] – это каталог с префиксом npm. Если вы не можете найти этот каталог, ознакомьтесь с разделом Где установлен Edge Microgateway.

plugins/<plugin_name>/config/default.yaml. Например, вы можете поместить этот блок в plugins/spikearrest/config/default.yaml, и он будет переопределять любые другие настройки конфигурации.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Как использовать плагин Spike Arrest

Плагин Spike Arrest защищает от скачков трафика. Ограничивает количество запросов, обрабатываемых экземпляром Edge Microgateway.

Как добавить плагин 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

Параметры конфигурации для подавления скачков

• timeUnit – как часто сбрасывается окно выполнения защиты от скачков. Допустимые значения: second (секунда) или minute (минута).
• allow – максимальное количество запросов, разрешенных в течение периода timeUnit. Также ознакомьтесь с разделом Если вы запустили несколько процессов Edge Micro.
• bufferSize (необязательный параметр, по умолчанию равен 0). Если bufferSize > 0, то функция защиты от пиковых нагрузок сохраняет в буфере указанное количество запросов. Как только наступит следующее окно выполнения, сначала будут обработаны запросы, сохраненные в буфере. Также ознакомьтесь с разделом Добавление буферной зоны.

Как работает защита от скачков напряжения?

Защита от скачков трафика – это способ предотвратить резкие увеличения трафика, а не ограничить его определенным количеством запросов. Ваши API и серверная часть могут обрабатывать определенный объем трафика, и правило ограничения скачков помогает сгладить трафик до нужного вам уровня.

Поведение при подавлении пиков во время выполнения отличается от того, что можно ожидать, исходя из введенных значений в минуту или секунду.

Например, если вы зададите ограничение в 30 запросов в минуту, как показано ниже:

spikearrest:
   timeUnit: minute
   allow: 30

При тестировании вы можете подумать, что можете отправить 30 запросов за одну секунду, если они будут отправлены в течение минуты. Однако правило не обеспечивает соблюдение этого параметра. Если подумать, 30 запросов за одну секунду в некоторых средах можно считать небольшим скачком.

Что же происходит на самом деле? Чтобы предотвратить скачки трафика, функция "Подавление скачков" сглаживает разрешенный трафик, разбивая настройки на более мелкие интервалы, как описано ниже.

Тарифы с поминутной оплатой

Значения в минуту преобразуются в интервалы в секундах. Например, если вы отправляете 30 запросов в минуту, то они будут распределены следующим образом:

60 секунд (1 минута) / 30 = интервалы в 2 секунды, то есть примерно 1 запрос каждые 2 секунды. Второй запрос, отправленный в течение двух секунд после первого, будет отклонен. Если отправить 31 запрос в течение минуты, он не будет обработан.

Цена за секунду.

Значения в секунду преобразуются в запросы, разрешенные в интервалах в миллисекундах. Например, если вы отправляете 10 запросов в секунду, то они будут обрабатываться следующим образом:

1000 миллисекунд (1 секунда) / 10 = интервалы по 100 миллисекунд, или примерно 1 запрос каждые 100 миллисекунд . Второй запрос, отправленный в течение 100 мс после первого, будет отклонен. Также не будет выполнен 11-й запрос, отправленный в течение секунды.

Что происходит при превышении лимита

Если количество запросов превышает лимит в течение заданного интервала времени, функция Spike Arrest возвращает следующее сообщение об ошибке со статусом HTTP 503:

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

Добавление буферной зоны

Вы можете добавить к правилу буфер. Предположим, вы установили буферное время 10. Вы увидите, что API не возвращает ошибку сразу после превышения лимита. Вместо этого запросы буферизуются (до указанного количества) и обрабатываются, как только становится доступно следующее подходящее окно выполнения. Значение по умолчанию для параметра bufferSize – 0.

Если вы запустили несколько процессов Edge Micro

Количество разрешенных запросов зависит от числа запущенных рабочих процессов Edge Micro. Функция Spike Arrest рассчитывает допустимое количество запросов для каждого рабочего процесса. По умолчанию количество микропроцессов Edge равно количеству ЦП на компьютере, на котором установлен Edge Micro. Однако вы можете настроить количество рабочих процессов при запуске Edge Micro, используя параметр --processes в команде start. Например, если вы хотите, чтобы функция защиты от скачков трафика срабатывала при 100 запросах за определенный период времени и запускаете Edge Microgateway с параметром --processes 4, задайте значение allow: 25 в конфигурации защиты от скачков трафика. Таким образом, общее правило заключается в том, чтобы задать для параметра конфигурации allow значение "желаемое количество подавлений скачков / количество процессов".

Как использовать плагин квот

Квота определяет количество запросов, которые приложение может отправлять в API в течение часа, дня, недели или месяца. Когда приложение достигает лимита квоты, последующие вызовы API отклоняются. Также ознакомьтесь со статьей В чем разница между ограничением пиковых нагрузок и квотой?

Как добавить плагин квот

Подробнее о добавлении и настройке плагинов…

Настройка продукта в Apigee Edge

Квоты настраиваются в интерфейсе Apigee Edge, где вы настраиваете продукты API. Вам нужно знать, в каком продукте находится прокси-сервер с поддержкой микрошлюза, который вы хотите ограничить квотой. Этот продукт необходимо добавить в приложение разработчика. Когда вы будете выполнять вызовы API, аутентифицированные с помощью ключей в приложении разработчика, к этим вызовам API будет применяться квота.

1. Войдите в аккаунт организации Apigee Edge.
2. В интерфейсе Edge откройте продукт, связанный с прокси-сервером, поддерживающим микрошлюз, к которому вы хотите применить квоту.
   1. В интерфейсе выберите Товары в меню "Публикация".
   2. Откройте продукт, содержащий API, к которому вы хотите применить квоту.
   3. Нажмите Изменить.
   4. В поле "Квота" укажите интервал квоты. Например, 100 запросов в минуту. или 50 000 запросов каждые два часа.
      
      

3. Нажмите Сохранить.
4. Убедитесь, что продукт добавлен в приложение разработчика. Вам понадобятся ключи из этого приложения, чтобы выполнять аутентифицированные вызовы API.

Пример конфигурации для квоты

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 в файл конфигурации, как показано в следующем примере:

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
    isHTTPStatusTooManyRequestEnabled: true
...

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

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: true

edgemicro:
...
quotas:
  failOpen: true

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

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}

Как учитываются квоты

По умолчанию микрошлюз синхронизирует счетчик квоты с Apigee Edge каждые пять секунд, если интервал квоты задан в минутах. Если интервал задан на уровне выше "минуты", например "неделя" или "месяц", период обновления по умолчанию составляет 1 минуту.

Обратите внимание, что интервалы квот задаются в продуктах API, определенных в Apigee Edge. Интервалы квот определяют, сколько запросов разрешено в минуту, час, день, неделю или месяц. Например, для продукта А может быть задан интервал квоты в 100 запросов в минуту,а для продукта Б – 10 000 запросов в час.

В файле YAML плагина Edge Microgateway quota не задается интервал квоты. Вместо этого в нем можно настроить частоту, с которой локальный экземпляр Edge Microgateway синхронизирует счетчик квоты с Apigee Edge.

Предположим, что в Apigee Edge определены три продукта API со следующими интервалами квоты:

• Для продукта А задана квота в 100 запросов в минуту.
• У продукта Б квота составляет 5000 запросов в час.
• У продукта В квота на количество запросов в месяц составляет 1 000 000.

Как настроить плагин Edge Microgateway quota с учетом этих ограничений? Рекомендуется настроить Edge Microgateway с интервалами синхронизации, которые меньше интервалов квот, заданных в продуктах API. Пример:

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

Эта конфигурация определяет следующие интервалы синхронизации для описанных выше продуктов API:

• Для товара А задан интервал "минута". Edge Microgateway будет синхронизироваться с Edge после каждого 50-го запроса или каждые 5 секунд (в зависимости от того, что произойдет раньше).
• Для товара Б задан интервал "час". Edge Microgateway будет синхронизироваться с Edge после каждого 2000-го запроса или через 1 минуту (в зависимости от того, что произойдет раньше).
• Для товара В задан интервал "месяц". Edge Microgateway будет синхронизироваться с Edge после каждого запроса или через минуту (в зависимости от того, что произойдет раньше).

Каждый раз, когда экземпляр микрошлюза синхронизируется с Edge, счетчик квоты микрошлюза устанавливается на полученное значение.

Настройки bufferSize позволяют задать, как счетчик квоты синхронизируется с Edge. В ситуациях с высоким трафиком настройки bufferSize позволяют синхронизировать счетчик буфера до того, как будет запущена синхронизация на основе времени по умолчанию.

Область действия квоты

Квота действует в пределах среды организации. Для этого Edge Microgateway создает идентификатор квоты, который представляет собой комбинацию "org + env + appName + productName".

Использование хранилища Redis для квот

Чтобы использовать хранилище Redis для квот, примените ту же конфигурацию, что и для функции синхронизатора. Ниже приведена базовая конфигурация, необходимая для использования Redis в качестве хранилища квот:

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

quotas:
  useRedis: true

Как протестировать плагин квот

Если квота превышена, клиенту возвращается статус HTTP 403 и следующее сообщение:

{"error": "exceeded quota"}

В чем разница между ограничением пиков и квотой?

Важно выбрать подходящий инструмент для выполнения задачи. Правила квот позволяют настроить количество запросов, которые клиентское приложение может отправлять в API в течение часа, дня, недели или месяца. Правила квоты позволяют задавать ограничения на использование клиентских приложений, поддерживая распределенный счетчик, который подсчитывает входящие запросы.

Используйте правила квоты, чтобы обеспечить соблюдение договоров с разработчиками и партнерами, а не для управления трафиком. Например, квота может использоваться для ограничения трафика бесплатного сервиса, при этом платные клиенты получают полный доступ.

Используйте функцию Spike Arrest, чтобы защититься от внезапных скачков трафика API. Как правило, защита от всплесков используется для предотвращения возможных DDoS-атак и других вредоносных действий.