Политика квот

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

Что

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

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

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

Видео

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

Образцы

Эти примеры правил политики иллюстрируют, как начинать и заканчивать периоды действия квот:

<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 сообщений в первый или последний день этого периода; дополнительные запросы не допускаются до тех пор, пока счетчик квоты автоматически не обнулится в конце указанного временного интервала или пока квота не будет явно сброшена с помощью политики «Сброс квоты» .

Разновидность функции Quota, называемая SpikeArrest, предотвращает всплески трафика, которые могут быть вызваны внезапным увеличением использования, ошибками в работе клиентов или вредоносными атаками. Для получения дополнительной информации о 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 с ограничением в 5 запросов и размещаете ее в нескольких потоках (потоки A, B и C) в API-прокси. Несмотря на использование в нескольких потоках, она поддерживает единый счетчик, который обновляется всеми экземплярами политики:

• Выполняется поток A -> Выполняется MyQuotaPolicy, и его счетчик равен 1.
• Выполняется поток B -> Выполняется MyQuotaPolicy, и его счетчик равен 2.
• Выполняется поток A -> Выполняется 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 приложения в запросе используется политика проверки ключа API под названием "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 async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

Следующие характеристики являются специфическими для данной политики.

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

Элемент <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

<Разрешить> элемент

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

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

<Allow count="2000"/>

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

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

Если указаны значения count и countRef , то приоритет отдаётся значению 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 .

Атрибуты

<Интервал> элемент

Используйте этот параметр, чтобы указать целое число (например, 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>

<Распределенный> элемент

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

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

<Distributed>true</Distributed>

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

<Distributed>true</Distributed>
<Synchronous>true</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>

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

элемент <Идентификатор>

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

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

Этот элемент также обсуждается в следующем сообщении сообщества Apigee: Идентификатор квоты в разных политиках .

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

Атрибуты

<MessageWeight> элемент

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

Например, вы хотите, чтобы POST-сообщения считались вдвое более «тяжелыми» или «дорогими», чем GET-сообщения. Поэтому вы устанавливаете MessageWeight равным 2 для POST-запросов и 1 для GET-запросов. Вы даже можете установить 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>

Схемы

Связанные темы

Политика сброса квоты

Политика SpikeArrest

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

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

Что

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

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

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

Видео

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

Образцы

Эти примеры правил политики иллюстрируют, как начинать и заканчивать периоды действия квот:

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

About the Quota policy

A Quota is an allotment of request messages that an API proxy can handle over a time period, such as minute, hour, day, week, or month. The policy maintains counters that tally the number of requests received by the API proxy. This capability enables API providers to enforce limits on the number of API calls made by apps over an interval of time. Using Quota policies you can, for example, limit apps to 1 request per minute, or to 10,000 requests per month.

For example, if a Quota is defined as 10,000 messages per month, rate-limiting begins after the 10,000th message. It doesn't matter whether 10,000 messages were counted on the first day or the last day of that period; no additional requests area allowed until the Quota counter automatically resets at the end of the specified time interval, or until the Quota is explicitly reset using Reset Quota policy .

A variation on Quota called SpikeArrest prevents traffic spikes (or bursts) that can be caused by a sudden increase in usage, buggy clients, or malicious attacks. For more information on SpikeArrest, see Spike Arrest policy .

Quotas apply to individual API proxies and are not distributed among API proxies. For example, if you have three API proxies in an API product, a single quota is not shared across all three even if all three use the same quota policy configuration.

Quota policy types

The Quota policy supports several different types of policies: default, calendar , flexi , and rollingwindow . Each type defines when the quota counter starts and when it resets, as shown in the following table:

For type="calendar" , you must specify the value of <StartTime> .

The table does not list the value for the rollingwindow type. Rolling window quotas work by setting the size of a quota "window", such as a one hour or one day window. When a new request comes in, the policy determines if the quota has been exceeded in the past "window" of time.

For example, you define a two hour window that allows 1000 requests. A new request comes in at 4:45 PM.The policy calculates the quota count for the past two hour window, meaning the number of requests since 2:45 PM. If the quota limit has not been exceeded in that two-hour window, then the request is allowed.

One minute later, at 4:46 PM, another request comes in. Now the policy calculates the quota count since 2:46 PM to determine if the limit has been exceeded.

For the rollingwindow type, the counter never resets, but is recalculated on each request.

Understanding quota counters

By default, a Quota policy maintains a single counter, regardless of how many times you reference it in an API proxy. The name of the quota counter is based on the name attribute of the policy.

For example, you create a Quota policy named MyQuotaPolicy with a limit of 5 requests and place it on multiple flows (Flow A, B, and C) in the API proxy. Even though it is used in multiple flows, it maintains a single counter that is updated by all instances of the policy:

• Flow A is executed -> MyQuotaPolicy is executed and its counter = 1
• Flow B is executed -> MyQuotaPolicy is executed and its counter = 2
• Flow A is executed -> MyQuotaPolicy is executed and its counter = 3
• Flow C is executed -> MyQuotaPolicy is executed and its counter = 4
• Flow A is executed -> MyQuotaPolicy is executed and its counter = 5

The next request to any of the three flows is rejected because the quota counter has reached its limit.

Using the same Quota policy in more than one place in an API proxy flow, which can unintentionally cause Quota to run out faster than you expected, is an anti-pattern described in The Book of Apigee Edge Antipatterns .

Alternatively, you can define multiple Quota policies in your API proxy and use a different policy in each flow. Each Quota policy maintains its own counter, based on the name attribute of the policy.

Or, use the <Class> or <Identifier> elements in the Quota policy to define multiple, unique counters in a single policy. By using these elements, a single policy can maintain different counters based on the app making the request, the app developer making the request, a client ID or other client identifier, and more. See the examples above for more information on using the <Class> or <Identifier> elements.

Time notation

All Quota times are set to the Coordinated Universal Time (UTC) time zone.

Quota time notation follows the international standard date notation defined in International Standard ISO 8601 .

Dates are defined as year, month, and day, in the following format: YYYY-MM-DD . For example, 2015-02-04 represents February 4, 2015.

Time of day is defined as hours, minutes, and seconds in the following format: hours:minutes:seconds . For example, 23:59:59 represents the time one second before midnight.

Note that two notations, 00:00:00 and 24:00:00 , are available to distinguish the two midnights that can be associated with one date. Therefore 2015-02-04 24:00:00 is the same date and time as 2015-02-05 00:00:00 . The latter is usually the preferred notation.

Getting quota settings from the API product configuration

You can set quota limits in API product configurations. Those limits don't automatically enforce quota. Instead, you can reference product quota settings in a quota policy. Here are some advantages of setting a quota on the product for quota policies to reference:

• Quota policies can use a uniform setting across all API proxies in the API product.
• You can make runtime changes to the quota setting on an API product, and quota policies that reference the value automatically have updated quota values.

For more information on using quota settings from an API product, see the "Dynamic Quota" example above. .

For info on configuring API products with quota limits, see Create API products .

Ссылка на элемент

Following are elements and attributes you can configure on this policy. Note that some element combinations are mutually exclusive or not required. See the samples for specific usage. The verifyapikey.VerifyAPIKey.apiproduct.* variables below are available by default when a Verify API Key policy called "VerifyAPIKey" is used to check the app's API key in the request. The variable values come from the quota settings on the API product that the key is associated with, as described in Getting quota settings from the API product configuration .

<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> attributes

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

Следующие характеристики являются специфическими для данной политики.

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

Элемент <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

<Allow> element

Specifies the count limit for the quota. If the counter for the policy reaches this limit value, subsequent calls are rejected until the counter resets.

Shown below are three ways to set the <Allow> element:

<Allow count="2000"/>

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

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

If you specify both count and countRef , then countRef gets the priority. If countRef does not resolve at runtime, then the value of count is used.

Атрибуты

<Allow>/<Class> element

The <Class> element lets you conditionalize the value of the <Allow> element based on the value of a flow variable. For each different <Allow> child tag of <Class> , the policy maintains a different counter.

To use the <Class> element, specify a flow variable using the ref attribute to the <Class> tag. Edge then uses the value of the flow variable to select one of the <Allow> child tags to determine the allowed count of the policy. Edge matches the value of the flow variable to the class attribute of the <Allow> tag, as shown below:

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

In this example, the current quota counter is determined by the value of the time_variable query param passed with each request. That variable can have a value of peak_time or off_peak_time . If the query param contains an invalid value, the policy returns a quota violation error.

Атрибуты

<Allow>/<Class>/<Allow> element

The <Allow> element specifies the limit for a quota counter defined by the <Class> element. For each different <Allow> child tag of <Class> , the policy maintains a different counter.

Например:

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

In this example, the Quota policy maintains two quota counters named of peak_time and off_peak_time .

Атрибуты

<Interval> element

Use to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the TimeUnit you specify (minute, hour, day, week, or month) to determine a time period during which Edge calculates quota use.

For example, an Interval of 24 with a TimeUnit of hour means that the quota will be calculated over the course of 24 hours.

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

Атрибуты

<TimeUnit> element

Use to specify the unit of time applicable to the quota.

For example, an Interval of 24 with a TimeUnit of hour means that the quota will be calculated over the course of 24 hours.

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

Атрибуты

<StartTime> element

When type is set to calendar, specifies the date and time when the quota counter will begin counting, regardless of whether any requests have been received from any apps.

Например:

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

<Distributed> element

An installation of Edge can use one or more Message Processors to process requests. Set this element to true to specify that the policy should maintain a central counter and continuously synchronize it across all Message Processors. The message processors can be across availability zones and/or regions.

If you use the default value of false , then you might exceed your quota because the count for each Message Processor is not shared:

<Distributed>true</Distributed>

To guarantee that the counters are synchronized, and updated on every request, set <Distributed> and <Synchronous> to true:

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

<Synchronous> element

Set to true to update a distributed quota counter synchronously. This means that the update to the counter are made at the same time the quota is checked on a request to the API. Set to true if it is essential that you not allow any API calls over the quota.

Set to false to update the quota counter asynchronously. This means that it is possible that some API calls exceeding the quota will go through, depending on when the quota counter in the central repository is asynchronously updated. However, you will not face the potential performance impacts associated with synchronous updates.

The default asynchronous update interval is 10 seconds. Use the AsynchronousConfiguration element to configure this asynchronous behavior.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration> element

Configures the synchronization interval amongst distributed quota counters when the policy configuration element <Synchronous> is either not present or present and set to false .

You can synchronize either after a time period or a message count, using either the SyncIntervalInSeconds or SyncMessageCount child elements. They are mutually exclusive. For example,

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

или

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

<AsynchronousConfiguration>/<SyncIntervalInSeconds> element

Use this to override the default behavior in which asynchronous updates are performed after an interval of 10 seconds.

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

The sync interval must be >= 10 seconds as described in the Limits topic.

<AsynchronousConfiguration>/<SyncMessageCount> element

Specifies the number of requests across all Apigee message processors between quota updates.

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

This example specifies that the quota count is updated every 5 requests across each Apigee Edge message processor.

<Identifier> element

Use the <Identifier> element to configure the policy to create unique counters based on a flow variable.

If you don't use this element, the policy uses a single counter that is applied against the quota.

This element is also discussed in the following Apigee Community post: Quota identifier across different policies .

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

Атрибуты

<MessageWeight> element

Use to specify the weight assigned to each message. Use message weight to increase impact of request messages that, for example, consume more computational resources than others.

For example, you want to count POST messages as being twice as "heavy" or expensive, as GET messages. Therefore, you set the MessageWeight to 2 for a POST and 1 for a GET. You can even set the MessageWeight to 0 so the request does not affect the counter. In this example, if the quota is 10 messages per minute and the MessageWeight for POST requests is 2 , then the quota will permits 5 POST requests in any 10 minute interval. Any additional request, POST or GET, before the counter resets are rejected.

A value representing MessageWeight must be specified by a flow variable, and can be extracted from HTTP headers, query parameters, an XML or JSON request payload, or any other flow variable. For example, you set it in a header named weight :

<MessageWeight ref="message_weight"/>

Переменные потока

The following predefined Flow variables are automatically populated when a Quota policy executes. For more information about Flow variables, see Variables reference .

Ссылка на ошибку

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются 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 policy

Политика SpikeArrest

Comparing Quota, Spike Arrest, and Concurrent Rate Limit Policies