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

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

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

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

Квоты применяются к отдельным прокси API и не распределяются между прокси 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 под названием «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 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> <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 , если для type явно задано значение calendar, Вы не можете использовать ссылку на переменную потока. Если вы укажете значение StartTime , когда значение type не установлено, вы получите сообщение об ошибке.

Например:

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

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

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

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

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

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