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

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

Что

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

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

Не используйте квоту для защиты от пиков общего трафика. Для этого используйте политику Spike Arrest. См. раздел «Политика 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 см. в разделе «Политика Spike Arrest» .

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

Типы политики квот

Политика квот поддерживает несколько различных типов политик: default, calendar , flexi и rollingwindow . Каждый тип определяет время запуска и сброса счётчика квот, как показано в следующей таблице:

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

В таблице не указано значение для типа rollingwindow . Квоты 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, которое может непреднамеренно привести к более быстрому исчерпанию квоты, чем ожидалось, является антипаттерном, описанным в книге The Book of Apigee Edge Antipatterns .

В качестве альтернативы вы можете определить несколько политик квот в вашем 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 «VerifyAPIKey» для проверки ключа API приложения в запросе. Значения переменных берутся из настроек квоты продукта 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 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"/>

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

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

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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

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