Политики в отношении квот

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

Что

Используйте правило "Квота", чтобы настроить количество сообщений запросов, которые прокси-сервер API разрешает за определенный период времени, например минуту, час, день, неделю или месяц. Вы можете задать одинаковую квоту для всех приложений, обращающихся к прокси-серверу API, или установить квоту на основе следующих параметров:

• Продукт, содержащий прокси API
• Приложение, запрашивающее API
• Разработчик приложения
• Множество других критериев

Не используйте квоту для защиты от общих скачков трафика. Для этого используйте правило Spike Arrest. Ознакомьтесь с правилами защиты от скачков трафика.

Видео

В этих видео рассказывается об управлении квотами с помощью правил квот:

Примеры

В приведенных ниже примерах кода показано, как начинать и заканчивать периоды квоты, используя:

<Quota name="CheckQuota">
  <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit"/>
</Quota>

<Quota name="DeveloperQuota">
  <Identifier ref="verifyapikey.verify-api-key.client_id"/>
  <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/>
  <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/>
  <Allow countRef="verifyapikey.verify-api-key.developer.limit"/>
</Quota>

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2017-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

<AssignMessage async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars">
    <AssignTo createNew="false" type="response"/>
    <Set>
        <Headers>
            <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header>
            <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header>
            <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

<Quota name="MyQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</Quota>

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/>
  <StartTime>2017-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

<Identifier ref="request.queryparam.id"/>

<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>

<Quota name="QuotaPolicy">
  <Interval>1</Interval>
  <TimeUnit>day</TimeUnit>
  <Allow>
    <Class ref="request.header.developer_segment">
      <Allow class="platinum" count="10000"/>
      <Allow class="silver" count="1000" />
    </Class>
  </Allow>
</Quota>

Правила в отношении квот

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

Например, если квота составляет 10 000 сообщений в месяц, ограничение скорости начнет действовать после отправки 10 000-го сообщения. Неважно,были ли 10 000 сообщений подсчитаны в первый или последний день этого периода. Дополнительные запросы будут запрещены, пока счетчик квоты не будет автоматически сброшен по истечении указанного интервала времени или пока квота не будет сброшена явным образом с помощью правила сброса квоты.

Вариант квоты под названием SpikeArrest предотвращает скачки трафика, которые могут быть вызваны внезапным увеличением использования, ошибками клиентов или вредоносными атаками. Подробнее о правилах в отношении SpikeArrest…

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

Типы правил в отношении квот

Правило квоты поддерживает несколько типов правил: по умолчанию, calendar, flexi и rollingwindow. В таблице ниже показано, когда счетчик квоты запускается и когда он сбрасывается.

Для поля type="calendar" необходимо указать значение <StartTime>.

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

Например, вы можете задать двухчасовой интервал, в течение которого разрешено 1000 запросов. В 16:45 поступает новый запрос.Правило рассчитывает количество запросов за последние два часа, то есть с 14:45. Если в течение двух часов квота не была превышена, запрос разрешается.

Через минуту, в 16:46, поступает ещё один запрос. Теперь правило рассчитывает количество квот с 14:46, чтобы определить, превышено ли ограничение.

Для типа rollingwindow счетчик никогда не сбрасывается, но пересчитывается при каждом запросе.

Счетчики квот

По умолчанию правило квоты поддерживает один счетчик, независимо от того, сколько раз вы ссылаетесь на него в прокси-сервере API. Название счетчика квоты основано на атрибуте name правила.

Например, вы создаете правило квоты с названием MyQuotaPolicy и ограничением в пять запросов и применяете его к нескольким потокам (А, Б и В) в прокси-сервере API. Несмотря на то что это правило используется в нескольких потоках, оно поддерживает единый счетчик, который обновляется всеми экземплярами правила:

• Выполняется поток А -> выполняется MyQuotaPolicy, счетчик = 1
• Выполняется поток B -> выполняется MyQuotaPolicy, счетчик = 2
• Выполняется поток А -> выполняется MyQuotaPolicy, счетчик которого равен 3.
• Выполняется поток C -> выполняется MyQuotaPolicy, и его счетчик равен 4.
• Выполняется поток A -> выполняется MyQuotaPolicy, и его счетчик равен 5.

Следующий запрос к любому из трех потоков будет отклонен, поскольку счетчик квоты достиг лимита.

Использование одного и того же правила квоты в нескольких местах потока прокси-сервера API, что может привести к непреднамеренному исчерпанию квоты быстрее, чем ожидалось, является антипаттерном, описанным в Книге антипаттернов Apigee Edge.

Вы также можете определить несколько правил квоты в прокси-сервере API и использовать разные правила в каждом потоке. Каждое правило квоты поддерживает собственный счетчик на основе атрибута name правила.

Или используйте элементы <Class> или <Identifier> в правиле квоты, чтобы определить несколько уникальных счетчиков в одном правиле. Используя эти элементы, можно настроить разные счетчики для одного правила в зависимости от приложения, отправившего запрос, разработчика приложения, идентификатора клиента или другого идентификатора клиента и т. д. Примеры использования элементов <Class> и <Identifier> приведены выше.

Обозначение времени

Все временные значения квот задаются в часовом поясе Всемирного координированного времени (UTC).

Временные отметки квот соответствуют международному стандарту ISO 8601.

Даты указываются в формате "год, месяц, день": YYYY-MM-DD. Например, 2015-02-04 соответствует 4 февраля 2015 г.

Время суток указывается в часах, минутах и секундах в следующем формате: hours:minutes:seconds. Например, 23:59:59 обозначает время за одну секунду до полуночи.

Обратите внимание, что для обозначения двух полуночей, которые могут быть связаны с одной датой, используются две нотации: 00:00:00 и 24:00:00. Таким образом, 2015-02-04 24:00:00 – это та же дата и время, что и 2015-02-05 00:00:00. Последний вариант обычно предпочтительнее.

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

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

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

Подробнее о том, как использовать настройки квоты из продукта API, рассказывается в примере "Динамическая квота" выше..

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

Сведения об элементах

Ниже перечислены элементы и атрибуты, которые можно настроить в этом правиле. Обратите внимание, что некоторые сочетания элементов являются взаимоисключающими или необязательными. Примеры использования приведены ниже. Переменные verifyapikey.VerifyAPIKey.apiproduct.*, перечисленные ниже, доступны по умолчанию, если для проверки ключа API приложения в запросе используется правило Verify API Key с названием VerifyAPIKey. Значения переменных берутся из настроек квоты для продукта API, с которым связан ключ, как описано в разделе Как получить настройки квоты из конфигурации продукта API.

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2017-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
</Quota>

Атрибуты <Quota>

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

Ниже перечислены атрибуты, относящиеся к этим правилам.

В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:

Элемент <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Элемент <Allow>

Указывает ограничение на количество для квоты. Если счетчик для правила достигнет этого значения, последующие вызовы будут отклоняться до тех пор, пока счетчик не будет сброшен.

Ниже показаны три способа задать элемент <Allow>:

<Allow count="2000"/>

<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>

<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>

Если вы укажете оба countcountRef параметра, приоритет будет у countRef. Если во время выполнения значение countRef не будет определено, будет использовано значение count.

Атрибуты

Элемент <Allow>/<Class>

Элемент <Class> позволяет задать условие для значения элемента <Allow> на основе значения переменной потока. Для каждого дочернего тега <Allow> элемента <Class> в правиле поддерживается отдельный счетчик.

Чтобы использовать элемент <Class>, укажите переменную потока с помощью атрибута ref в теге <Class>. Затем Edge использует значение переменной потока, чтобы выбрать один из дочерних тегов <Allow> и определить допустимое количество правил. Edge сопоставляет значение переменной потока со значением атрибута class тега <Allow>, как показано ниже:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

В этом примере текущий счетчик квоты определяется значением параметра запроса time_variable, передаваемого с каждым запросом. Эта переменная может иметь значение peak_time или off_peak_time. Если параметр запроса содержит недопустимое значение, правило возвращает ошибку нарушения квоты.

Атрибуты

Элемент <Allow>/<Class>/<Allow>

Элемент <Allow> задает лимит для счетчика квоты, определенного элементом <Class>. Для каждого дочернего тега <Allow> тега <Class> правило ведет отдельный счетчик.

Пример:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

В этом примере в правилах квот поддерживаются два счетчика квот с названиями peak_time и off_peak_time.

Атрибуты

Элемент <Interval>

Используйте целое число (например, 1, 2, 5, 60 и т. д.), которое будет сопоставлено с TimeUnit (минута, час, день, неделя или месяц), чтобы определить период времени, в течение которого Edge рассчитывает использование квоты.

Например, Interval из 24 с TimeUnit из hour означает, что квота будет рассчитываться в течение 24 часов.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

Атрибуты

Элемент <TimeUnit>

Используется для указания единицы времени, применимой к квоте.

Например, Interval из 24 с TimeUnit из hour означает, что квота будет рассчитываться в течение 24 часов.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>

Атрибуты

Элемент <StartTime>

Если для параметра type задано значение calendar,, счетчик квоты начнет отсчет в указанную дату и время независимо от того, были ли получены какие-либо запросы от приложений.

Пример:

<StartTime>2017-7-16 12:00:00</StartTime>

Элемент <Distributed>

В установке Edge может использоваться один или несколько процессоров сообщений для обработки запросов. Задайте для этого элемента значение true, чтобы правило поддерживало центральный счетчик и постоянно синхронизировало его со всеми процессорами сообщений. Обработчики сообщений могут находиться в разных зонах доступности и/или регионах.

Если вы используете значение по умолчанию false, то можете превысить квоту, поскольку счетчик для каждого Message Processor не является общим:

<Distributed>true</Distributed>

Чтобы гарантировать синхронизацию счетчиков и их обновление при каждом запросе, установите для параметров <Distributed> и <Synchronous> значение true:

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

Элемент <Synchronous>

Установите значение true, чтобы синхронно обновить счетчик распределенной квоты. Это означает, что счетчик обновляется одновременно с проверкой квоты в запросе к API. Установите значение true, если вам важно, чтобы вызовы API не превышали квоту.

Установите значение false, чтобы асинхронно обновить счетчик квоты. Это означает, что некоторые вызовы API, превышающие квоту, могут быть выполнены в зависимости от того, когда счетчик квоты в центральном хранилище будет обновлен асинхронно. Однако вы не столкнетесь с потенциальным снижением производительности, связанным с синхронными обновлениями.

По умолчанию интервал асинхронного обновления составляет 10 секунд. Чтобы настроить асинхронное поведение, используйте элемент AsynchronousConfiguration.

<Synchronous>false</Synchronous>

Элемент <AsynchronousConfiguration>

Настраивает интервал синхронизации между распределенными счетчиками квот, если элемент конфигурации правила <Synchronous> отсутствует или присутствует и имеет значение false.

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

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

или

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Элемент <AsynchronousConfiguration>/<SyncIntervalInSeconds>

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

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

Интервал синхронизации должен быть не менее 10 секунд, как описано в разделе Ограничения.

Элемент <AsynchronousConfiguration>/<SyncMessageCount>

Указывает количество запросов ко всем процессорам сообщений Apigee между обновлениями квоты.

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

В этом примере указано, что счетчик квоты обновляется каждые пять запросов в каждом процессоре сообщений Apigee Edge.

Элемент <Identifier>

Используйте элемент <Identifier>, чтобы настроить правила для создания уникальных счетчиков на основе переменной потока.

Если вы не используете этот элемент, в правиле будет использоваться один счетчик, который применяется к квоте.

Этот элемент также обсуждается в следующем сообщении сообщества Apigee: Quota identifier across different policies.

<Identifier ref="verifyapikey.verify-api-key.client_id"/>

Атрибуты

Элемент <MessageWeight>

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

Например, вы хотите, чтобы сообщения POST считались в два раза более "тяжелыми" или дорогими, чем сообщения GET. Поэтому для запроса POST нужно задать значение MessageWeight, равное 2, а для запроса GET – 1. Вы даже можете установить для параметра MessageWeight значение 0, чтобы запрос не влиял на счетчик. В этом примере, если квота составляет 10 сообщений в минуту, а MessageWeight для запросов POST – 2, то квота разрешает 5 запросов POST в любой 10-минутный интервал. Все дополнительные запросы POST или GET, отправленные до сброса счетчика, отклоняются.

Значение, представляющее MessageWeight, должно быть указано переменной потока и может быть извлечено из заголовков HTTP, параметров запроса, полезной нагрузки запроса XML или JSON или любой другой переменной потока. Например, вы задали его в заголовке weight:

<MessageWeight ref="message_weight"/>

Переменные процесса

При выполнении правила квоты автоматически заполняются следующие предопределенные переменные потока. Подробнее о переменных потока…

Справочник по ошибкам

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

Ошибки времени выполнения

Эти ошибки могут возникать при выполнении правил.

Ошибки развертывания

Переменные ошибок

Эти переменные задаются, когда правило вызывает ошибку. Подробнее о нарушениях правил…

Пример ответа об ошибке

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      },
      "faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
   }
}

Пример правила обработки ошибок

<FaultRules>
    <FaultRule name="Quota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "QuotaViolation") </Condition>
        </Step>
        <Condition>ratelimit.Quota-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Схемы

Статьи по теме

Правила ResetQuota

Правила в отношении функции SpikeArrest

Сравнение правил квоты, защиты от скачков и ограничения скорости одновременных запросов