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

Вы просматриваете документацию 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, выполняемых приложениями за определенный промежуток времени. Используя политики квот, вы можете, например, ограничить приложения 1 запросом в минуту или 10 000 запросов в месяц.

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

Разновидность Quota под названием SpikeArrest предотвращает скачки трафика (или всплески), которые могут быть вызваны внезапным увеличением использования, глючными клиентами или вредоносными атаками. Для получения дополнительной информации о SpikeArrest см. Политика Spike Arrest .

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

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

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

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

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

Например, вы определяете двухчасовое окно, которое разрешает 1000 запросов. Новый запрос поступает в 4:45 PM. Политика вычисляет количество квот за последние два часа, то есть количество запросов с 2:45 PM. Если предел квоты не был превышен за это двухчасовое окно, то запрос разрешается.

Минуту спустя, в 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 .

Атрибуты

Элемент <Разрешить>/<Класс>

Элемент <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: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html .

<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 см. Справочник переменных .

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

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

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