Ограничения на количество запросов

Чтобы обеспечить бесперебойное обслуживание пользователей AdWords API по всему миру, мы ограничиваем скорость отправки запросов, используя алгоритм набора маркеров. This is intended to prevent malicious or out–of-control software from overwhelming the AdWords API servers and affecting other users.

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

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

Подробнее об ошибке RateExceededError и о том, как избежать превышения скорости отправки запросов, вы узнаете из этого руководства.

История

В более ранних версиях AdWords API сверхлимитные запросы ставились в очередь на обработку на сервере. В результате на выполнение некоторых запросов уходило очень много времени. Вместо того чтобы блокировать работу клиентского приложения на продолжительный срок, текущая версия API немедленно возвращает ошибку RateExceededError. Благодаря этому разработчик сразу же узнает о проблеме и может внести в приложение необходимые коррективы.

Типы ограничений на количество запросов

Мы понимаем, что иногда ваше клиентское приложение может превысить лимит запросов и получить ошибку RateExceededError в силу не зависящих от вас факторов. Поэтому никаких штрафных санкций в таких случаях не предусмотрено. Ошибка RateExceededError обычно является временной и автоматически исчезает через 30 секунд бездействия.

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

Ограничения на количество операций в зависимости от уровня доступа

Есть только одно фиксированное ограничение: на количество операций в зависимости от уровня доступа. Уровень доступа может быть двух типов: базовый и стандартный. При базовом уровне доступа на аккаунт выделяется 10 000 операций и 1000 скачиваний отчетов в день. Каждому новому токену разработчика по умолчанию присваивается базовый уровень доступа. Если вы планируете выполнять больше операций, подайте заявку на стандартный уровень доступа к AdWords API, заполнив эту форму. Оба уровня доступа бесплатны. О том, как подсчитывается число операций, можно узнать из этой статьи.

Остальные ограничения могут меняться, поэтому ваше приложение должно обрабатывать ошибку RateExceededError, чтобы реагировать на эти изменения.

Элементы RateExceededError

Ошибка RateExceededError включает три важных поля:

  • rateScope – указывает уровень ограничения, которое вы превысили. Возможные значения: ACCOUNT (уровень аккаунта) и DEVELOPER (уровень разработчика).
  • rateName – указывает название ограничения, которое вы превысили. Пример: RequestsPerMinute (количество запросов в минуту).
  • retryAfterSeconds – указывает, сколько секунд как минимум следует подождать перед повторной попыткой. Мы рекомендуем задать для поля retryAfterSeconds случайный мультипликатор (то есть значение с плавающей точкой между 1 и 2 включительно). Если ваши программы отправляют запросы параллельно (многопоточная передача), убедитесь, что новые запросы не передаются в одно и то же время после ожидания.

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

Уровень аккаунта и уровень разработчика

Поле RateScope может иметь два значения: ACCOUNT и DEVELOPER. Значение зависит от того, на каком уровне было превышено ограничение: на уровне аккаунта AdWords или на уровне идентификатора разработчика.

Уровень идентификатора разработчика

Каждому управляющему аккаунту AdWords с доступом к AdWords API присваивается один идентификатор (токен) разработчика, с которым связываются все запросы, которые вы отправляете. Если суммарное количество запросов в секунду для одного идентификатора превысит определенный предел, появится ошибка RateExceededError со значением DEVELOPER в поле RateScope.

Допустим, вы управляете 100 аккаунтами AdWords и используете один идентификатор разработчика в нескольких приложениях. Если суммарное количество запросов в секунду по всем процессам, потокам и компьютерам достигнет нескольких сотен, ваше приложение может получить ошибку RateExceededError на уровне идентификатора разработчика.

Уровень аккаунта

Если клиентское приложение отправляет большое число запросов в секунду для одного управляемого аккаунта AdWords, то сервер AdWords API может вернуть ошибку RateExceededError из-за превышения лимита запросов на уровне аккаунта. Это может произойти, например, если ваше программное обеспечение создаст несколько потоков для выполнения сверхлимитного количества операций mutate() над одним аккаунтом AdWords.

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

Приведем пример. Допустим, одним аккаунтом AdWords управляют пять менеджеров. Следовательно, все они могут одновременно отправлять запросы для этого аккаунта. Если суммарное количество запросов в секунду во всех управляющих аккаунтах превысит установленный лимит, клиентское приложение получит ошибку RateExceededError на уровне аккаунта.

Почему важно название ограничения?

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

  • RequestsPerMinute
  • OperationsPerMinute
Разница между запросом и операцией

В чем же разница между RequestsPerMinute и OperationsPerMinute? Запросом считается каждый вызов службы SOAP. Например, каждый раз, когда вы вызываете CampaignService.mutate(), засчитывается один запрос. Если же вы передадите в одном запросе mutate 100 операций CampaignOperation, будет засчитано 100 операций.

Таким образом, вы можете объединить несколько операций в один запрос и тем самым соблюсти ограничение на количество запросов в минуту (RequestPerMinute), но превысить лимит на число операций в минуту (OperationsPerMinute).

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

Другие ограничения

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

Как снизить скорость отправки запросов

Если ваше приложение получает ошибку RateExceededError, снизьте скорость отправки запросов. В противном случае эта ошибка может существенно замедлить работу вашего приложения. Самый простой способ решить проблему – подождать столько секунд, сколько указано в RateExceededError.retryAfterSeconds, и повторно отправить этот же или следующий запрос.

Например, если вы программируете на Java, то проще всего приостановить поток можно с помощью метода Thread.sleep().

try {
  ...
} catch (ApiException e) {
  for (ApiError error : e.getErrors()) {
    if (error instanceof RateExceededError) {
      RateExceededError rateExceeded = (RateExceededError) error;
      Thread.sleep(rateExceeded.getRetryAfterSeconds() * 1000);
    }
  }
  ...
}

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

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

В следующем разделе мы рассмотрим методы контроля запросов. Тем не менее помните, что даже несмотря на реализацию этих механизмов ваше приложение все равно должно обрабатывать ошибку RateExceededError.

Контроль

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

Рекомендуемые способы контроля (от простого к сложному):

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

Ограничение числа параллельных потоков

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

Поэтому мы рекомендуем установить предел для общего количества последовательных потоков (по всем процессам и системам), которые будут отправлять запросы, и затем понемногу повышать его. Это позволит вам достичь оптимального быстродействия, не выходя за рамки ограничений.

Кроме того, попробуйте регулировать количество запросов в секунду по всем потокам (см. раздел Ограничители скорости передачи).

Группировка запросов

По возможности старайтесь объединять несколько запросов в один пакет. В особенности это касается вызовов mutate(). Например, если вам нужно обновить статус нескольких объектов AdGroupAd, то вместо того чтобы вызывать метод mutate() для каждого объекта AdGroupAd по отдельности, можно вызвать mutate() всего один раз и передать ему сразу несколько операций AdGroupAdOperation. В разделе Рекомендуемые методы работы вы найдете другие примеры пакетирования запросов и группировки операций.

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

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

Использование службы BatchJobService

Если на выполнение заданий требуется много времени или вам нужно произвести большое число операций, в том числе задействуя разные службы, попробуйте использовать службу BatchJobService. Она может асинхронно выполнять тысячи операций, используя облачное хранилище Google. Вам остается только получать информацию о результатах выполнения заданий.

Подробнее читайте в этом руководстве.

Ограничители скорости передачи

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

Вы можете использовать ограничитель из библиотек Google Guava или разработать собственный механизм на основе пакета маркеров для кластерной среды. Например, можно создавать токены и хранить их в общем хранилище, например базе данных. Каждый клиент должен будет получить и использовать токен, прежде чем обработать запрос. Если все токены были истрачены, то приложению придется подождать, пока не будет создан новый пакет токенов.

В большинстве случаев этот метод позволит вам избежать превышения лимитов на уровне токена разработчика.

Распределение запросов между несколькими аккаунтами

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

Допустим, вам нужно выполнить 5000 операций mutate() над 10 аккаунтами. Можно последовательно отправить пакеты операций сначала в аккаунт 1, затем в аккаунт 2, 3 и так далее:

  1. Отправьте 500 операций mutate для аккаунта 1 (повторить 10 раз, пока не будет достигнуто 5000 операций).
  2. Отправьте 500 операций mutate для аккаунта 2 (тоже повторить 10 раз).
  3. И так далее для всех 10 аккаунтов.

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

Чтобы этого избежать, можно распределить запросы между аккаунтами следующим образом:

  1. Отправьте 500 операций mutate для аккаунта 1.
  2. Отправьте 500 операций mutate для аккаунта 2.
  3. Отправьте 500 операций mutate для аккаунта 3
  4. И так далее для всех 10 аккаунтов.
  5. Отправьте 500 операций mutate для аккаунта 1.
  6. Отправьте 500 операций mutate для аккаунта 2.
  7. И так далее, пока не будет выполнено 5000 операций для каждого аккаунта.

В таких случаях можно также с успехом использовать службу BatchJobService. Подробнее о ней читайте в этом руководстве.

Очереди сообщений

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

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

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

Установка разных ограничений для новых и существующих аккаунтов

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

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

Как правило, лимит для новых аккаунтов AdWords повышается, как только начинается показ объявлений.

Оставить отзыв о...

Текущей странице
Нужна помощь? Обратитесь в службу поддержки.