Рекомендации

В этой статье приведены рекомендации по разработке приложений, использующих Google Ad Manager API.

Повторно используйте клиенты/заглушки сервиса во время выполнения.

Создание нового клиента/заглушки сервиса связано с незначительными затратами на получение WSDL и выделение ресурсов. По возможности создайте клиент/заглушку сервиса один раз в начале выполнения и сделайте его доступным для классов и функций по мере необходимости.

Используйте разбиение на страницы при получении объектов

Все сервисы поддерживают метод get*ByStatement(), который позволяет фильтровать результаты с помощью синтаксиса PQL. Предложения LIMIT и OFFSET можно использовать, чтобы разбивать большие наборы результатов на страницы. Это позволяет избежать тайм-аутов и поддерживать разумный размер страниц ответов. Рекомендуемый размер страницы – от 200 до 500 объектов в зависимости от их сложности.

Запросы на пакетное обновление

Если вы хотите изменить несколько объектов одного типа, то для повышения производительности отправьте все объекты в одном запросе update*(). Каждый запрос создает небольшую нагрузку на клиент и сервер, и пакетная обработка может быть эффективным способом уменьшить количество запросов. Например, используйте updateOrders, чтобы обновить сразу несколько заказов, а не по одному за раз.

Как использовать параметры привязки в PQL

Параметры привязки позволяют добавлять переменные в запрос PQL. В PQL связанная переменная обозначается именем без пробелов, которое начинается с двоеточия, например :name. Пример кода приведен на странице Синтаксис PQL.

Мы рекомендуем использовать связанные переменные, поскольку они улучшают читаемость кода, устраняя необходимость объединять строки и переменные в оператор запроса. Кроме того, они позволяют повторно использовать операторы PQL, поскольку новые запросы можно создавать, заменяя значения параметров привязки.

Предоставляйте права пользователей с осторожностью

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

Как соблюдать квоту

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

Квота для API

Первая квота, которая применяется к запросам к API, – это квота на уровне сети. Для аккаунтов Менеджера рекламы 360 ограничение составляет восемь запросов в секунду, а для аккаунтов Менеджера рекламы – два запроса в секунду. Если превысить это ограничение, возникнет ошибка QuotaError.EXCEEDED_QUOTA. Эта квота распространяется на все запросы к API, выполненные в вашей сети, в том числе на запросы сторонних приложений, которым вы или кто-то из ваших коллег предоставил доступ к API в вашей сети.

Квоты для отдельных систем

Одной квоты API недостаточно для адекватной защиты некоторых ресурсоемких систем в Менеджере рекламы. В системах отчетов и прогнозов заданы собственные квоты, которые могут приводить к ошибкам API: QuotaError.REPORT_JOB_LIMIT и ForecastError.EXCEEDED_QUOTA соответственно.

Как устранять ошибки, связанные с квотами

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