Правила лимитов
Правило лимитов ограничивает потребление или частоту запросов внутри лицензии: для всей лицензии, для выбранных потребителей или API-токенов, для всех нексусов или только для выбранных. Правила бывают двух видов:
- запись таблицы Правила ограничения квоты (mai_quota_limits_rule) ограничивает число кредитов, которое можно израсходовать за период действующей квоты;
- запись таблицы Правила ограничения частоты запросов (mai_rate_limits_rule) ограничивает число запросов в минуту и в сутки.
Лицензия без правил ограничена только своей квотой.
Уровни правил
| Уровень | На что действует | Правила квоты | Правила частоты запросов |
|---|---|---|---|
| Лицензия | Все потребители лицензии | Ограничивает потребление лицензии в целом: когда сумма потребления всех потребителей достигает значения правила, нексусы блокируются для всех. | Задает лимит каждому потребителю лицензии. Лимит считается отдельно для каждого потребителя, а не общий на всех. |
| Потребитель | Потребители, выбранные в правиле | Ограничивает потребление каждого выбранного потребителя отдельно. Достигший значения потребитель блокируется, остальные продолжают работу. | Задает лимит каждому выбранному потребителю. |
| Токен | API-токены, выбранные в правиле | Ограничивает потребление каждого выбранного токена. Достигший значения токен блокируется по квоте, остальные токены и мастер-токен продолжают работу. | Уровень недоступен. |
Если в правиле выбраны нексусы, правило действует на каждый из них отдельно: ограничивается потребление или частота запросов к этому нексусу. Если нексусы не выбраны, правило квоты считает потребление по всем нексусам вместе, а правило частоты запросов задает один и тот же лимит каждому нексусу отдельно. Правило уровня Токен действует на все нексусы.
Правило квоты считает потребление с начала действующей квоты. С началом новой квоты отсчет начинается заново. Правила квоты блокируют потребление в любом режиме контроля лицензии, в том числе в режиме Предупреждающий.
При удалении потребителя он и его API-токены исключаются из правил. Правило, в котором не осталось потребителей или токенов, удаляется.
Совместное действие правил
Правила квоты разных уровней действуют одновременно: потребление сравнивается с каждым подходящим правилом, и нексус блокируется, как только достигнуто значение любого из них. Правило уровня Лицензия сравнивается с потреблением всех потребителей лицензии вместе, правило уровня Потребитель – с потреблением потребителя, правило уровня Токен – с потреблением токена.
Например, правило уровня Лицензия задает 1000 кредитов на нексус A, а правило уровня Потребитель – 500 кредитов потребителю X на нексус A. Потребитель X блокируется на нексусе A, когда израсходует 500 кредитов. Все потребители, включая X, блокируются на нексусе A, когда вместе израсходуют 1000 кредитов.
Из правил частоты запросов действует одно – самое узкое из подходящих. Приоритет от высшего к низшему:
- Потребитель, выбранные нексусы.
- Потребитель, все нексусы.
- Лицензия, выбранные нексусы.
- Лицензия, все нексусы.
Например, правило уровня Лицензия задает 100 запросов в минуту, а правило уровня Потребитель – 30 запросов в минуту потребителю X. Тогда запросы потребителя X ограничены 30 в минуту, а запросы остальных потребителей – 100 в минуту.
Проверки при сохранении
Правило не сохраняется, если нарушено одно из условий ниже. Сообщение называет причину.
Узкое правило не может быть мягче широкого:
- значение правила уровня Потребитель – не больше значения правила уровня Лицензия;
- значение правила уровня Токен – не больше значения правила потребителя этого токена, а если его нет – правила лицензии.
Сообщение называет допустимое значение и потребителей или токены, с правилами которых конфликтует новое значение. Так же проверяется и обратное: широкое правило не сохраняется, если оно строже уже заданного узкого.
Правила одного уровня не пересекаются: пара "потребитель – нексус" или токен встречается только в одном правиле каждого вида. Правило на все нексусы и правило на выбранные нексусы для одного потребителя можно задать одновременно: пересечением это не считается. При пересечении правило не сохраняется, а сообщение содержит ссылку на правила, с которыми оно пересекается.
Пока лицензия удаляется, правила лимитов доступны только для чтения.
Добавление правила
Требуемые роли:
- Чтение – mai_reporter, а также владельцы лицензии.
- Создание – mai_admin и владельцы лицензии.
- Обновление – mai_admin и владельцы лицензии.
- Удаление – mai_admin и владельцы лицензии.
Уровень правила определяется формой, с которой оно добавляется:
| Форма | Уровень | Связанный список, в котором добавляется правило |
|---|---|---|
| Лицензия | Лицензия | Правила ограничения квоты, Правила ограничения частоты запросов |
| Потребитель | Потребитель | Правила ограничения квоты, Правила ограничения частоты запросов |
| API-токен | Токен | Правила ограничения квоты |
- Откройте запись лицензии, потребителя или API-токена.
- В связанном списке Правила ограничения квоты или Правила ограничения частоты запросов нажмите Добавить.
- В окне Добавление правила ограничения квоты или Добавление правила ограничения частоты запросов заполните поля. Поля Уровень и Лицензия заполняются автоматически. На форме потребителя или токена в правило подставляется текущий потребитель или токен.
- Нажмите Добавить правило.

Чтобы правило уровня Потребитель действовало сразу на нескольких потребителей, добавьте его с формы любого из них и в окне укажите остальных потребителей в поле Потребители. Так же правило уровня Токен с формы одного токена распространяется на несколько токенов через поле API-Токены.
Правило уровня Потребитель можно добавить и в личном кабинете: на странице потребителя нажмите Добавить на вкладке Правила ограничения квоты или Правила ограничения частоты запросов.
Изменения правил частоты запросов сразу отправляются на платформу. Правила квоты применяются при ближайшем пересчете потребления – раз в 5 минут.

Поля правила
| Поле | Обязательно | Описание |
|---|---|---|
| Уровень | Да | Уровень правила. Поле заполняется автоматически по форме, с которой добавляется правило, и доступно только для чтения. Доступные опции:
|
| Лицензия | Да | Лицензия, в которой действует правило. Поле заполняется автоматически и доступно только для чтения. |
| Потребители | Да/Нет | Укажите потребителей лицензии, на которых действует правило. Поле отображается и обязательно для уровня Потребитель. |
| API-Токены | Да/Нет | Укажите API-токены потребителей лицензии, на которые действует правило. Отозванные токены выбрать нельзя. Поле отображается и обязательно для уровня Токен. |
| Нексусы | Нет | Укажите нексусы, на которые действует правило. Если поле не заполнено, правило действует на все нексусы. Для уровня Лицензия доступны нексусы лицензии, для уровня Потребитель – нексусы выбранных потребителей. Нексусы в состоянии Черновик и Выведен из эксплуатации выбрать нельзя. Поле отображается для уровней Лицензия и Потребитель. |
| Квота (А-Токены) | Да | Укажите, сколько кредитов можно израсходовать за период действующей квоты. Значение должно быть больше 0. А-токены в подписи поля – другое название кредитов. Поле есть только у правил квоты. |
| Лимит запросов в минуту | Да/Нет | Укажите, сколько запросов в минуту допускается. Значение должно быть больше 0. Поле обязательно, если заполнено поле Лимит запросов в день или не заполнены затухающие лимиты. Поле есть только у правил частоты запросов. |
| Лимит запросов в день | Да/Нет | Укажите, сколько запросов в сутки допускается. Значение должно быть больше 0. Поле обязательно, если заполнено поле Лимит запросов в минуту или не заполнены затухающие лимиты. Поле есть только у правил частоты запросов. |
| Затухающий лимит запросов в минуту | Да/Нет | Укажите, сколько запросов в минуту допускается после исчерпания квоты. Значение должно быть больше 0. Поле обязательно, если заполнено поле Затухающий лимит запросов в день или не заполнены обычные лимиты. Поле есть только у правил частоты запросов. |
| Затухающий лимит запросов в день | Да/Нет | Укажите, сколько запросов в сутки допускается после исчерпания квоты. Значение должно быть больше 0. Поле обязательно, если заполнено поле Затухающий лимит запросов в минуту или не заполнены обычные лимиты. Поле есть только у правил частоты запросов. |
Затухающие лимиты
Затухающие лимиты действуют у лицензии с режимом контроля Ограничение скорости, когда потребление достигло значения действующей квоты. Вместо полного отказа запросы продолжают обслуживаться с меньшей частотой. Затухающие лимиты задаются в правилах частоты запросов вместе с обычными.
Для запроса выбирается самое узкое правило, в котором заполнены затухающие лимиты. Если таких правил нет, продолжают действовать обычные лимиты: режим Ограничение скорости без затухающих лимитов не замедляет запросы. С началом следующей квоты или после увеличения текущей снова действуют обычные лимиты.
Ответ при срабатывании правила
Если превышен лимит частоты запросов, клиент получает ответ 429. Если потребление достигло значения правила квоты, нексусы блокируются: клиент получает ответ 429 с подстрокой is blocked в теле. Токен, потребление которого достигло значения правила уровня Токен, блокируется по квоте, и запросы с ним получают ответ 403. Читайте подробнее в статье Ошибки и лимиты.
Блокировка снимается при ближайшем пересчете потребления после того, как значение правила увеличено, правило удалено, потребитель, токен или нексус исключен из правила либо началась новая квота.