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

Это руководство содержит рекомендации по повышению эффективности приложений, созданных на основе AdWords API.

Текущее обслуживание

Обеспечить бесперебойную работу приложения вам помогут следующие рекомендации:

  • Keep your developer contact email in the AdWords API Center up–to-date. так как на этот адрес будет отправляться важная информация. Если мы обнаружим какое-либо нарушение Условий использования и не сможем связаться с вами, доступ к API может быть закрыт. Не рекомендуется указывать личный электронный адрес, связанный с индивидуальным или неконтролируемым аккаунтом.

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

Форум регулярно посещают специалисты по AdWords API, которым можно задать интересующие вас вопросы.

Оптимизация

Объединяйте операции в пакеты для уменьшения числа запросов

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

Например, рассмотрим добавление 50 000 ключевых слов в несколько групп объявлений одной кампании. Вместо 50 000 запросов по одному ключевому слову в каждом лучше выполнить 100 запросов по 500 или 10 запросов по 5000 ключевых слов. Обратите внимание, что существуют ограничения на количество операций в запросе, поэтому вам следует подобрать оптимальный размер пакета.

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

Объединяйте операции по целевой кампании или группе объявлений

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

Кроме того, параллельные запросы к одной и той же кампании или группе объявлений могут вызывать ошибку CONCURRENT_MODIFICATION. Объединение операций, относящихся к определенному целевому объекту, в один запрос позволит избежать такой проблемы.

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

Повторно используйте токены доступа

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

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

После отправки объектов в AdWords API происходит десериализация всех полей, их проверка и сохранение в базе данных. Чтобы обработка не занимала много времени и не снижалась производительность, в AdWords API можно использовать частичное обновление. Оно подразумевает, что заполняются лишь те поля объекта, которые требуют изменения. Незаполненные поля и поля с нулевыми значениями не обрабатываются, что позволяет увеличить скорость выполнения запросов.

Частичные обновления могут быть полезны в приложениях, которые меняют ставки на уровне ключевых слов, поскольку в этом случае заполняются только поля ставок, adGroupID и criterionID. В тесте со 150 ключевыми словами при частичном обновлении производительность была на 20% выше, чем при полной передаче объектов.

Сжимайте SOAP-сообщения

AdWords API поддерживает сжатие SOAP-сообщений с помощью gzip в запросах и ответах. Чтобы включить сжатие в ответе, добавьте в запрос следующие заголовки HTTP:

  • User-Agent: со строкой gzip.
  • Accept-Encoding: со значением gzip.

Пример:

User-Agent: My App (gzip)
Accept-Encoding: gzip

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

Обработка ошибок

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

Подробнее об этом читайте в разделе Устранение неполадок.

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

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

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

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

Определите тип ошибки

Ниже вы найдете четыре основных типа ошибок, для каждого из которых существуют свои методы решения. Категории могут пересекаться, а список не является исчерпывающим. Тем не менее мы рекомендуем использовать его как отправную точку при настройке обработки ошибок в приложении. Подробнее об отдельных ошибках читайте в разделе Распространенные ошибки.

  1. Ошибки аутентификации и авторизации.

    • Аутентификация определяет, предоставил ли пользователь вашему приложению разрешение на выполнение действий в AdWords от его имени. Аутентификация выполняется с использованием учетных данных, созданных процедурой OAuth2.

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

    Чаще всего ошибка аутентификации возникает, когда пользователь отзывает разрешение, предоставленное приложению. Например, если ваш продукт управляет не связанными между собой аккаунтами AdWords и проходит аутентификацию для каждого из них отдельно, клиент может закрыть доступ в любой момент. В зависимости от того, когда было отозвано разрешение, API может возвратить ошибку AuthenticationError.OAUTH_TOKEN_REVOKED либо стандартные объекты учетных данных в клиентских библиотеках могут создать исключение для отмены токена. В любом случае, если в приложении есть пользовательский интерфейс, клиент может получить приглашение повторно запустить процедуру OAuth2 и восстановить разрешение.

    Ошибки авторизации часто возникают из-за изменений в иерархии аккаунта. Приложение, которое работает с иерархией определенного управляющего аккаунта, обычно проходит аутентификацию как его администратор, поскольку такая роль обеспечивает доступ ко всем подчиненным аккаунтам. Если пользователь подчиненного аккаунта отменит связь, то при попытке приложения получить доступ к этому аккаунту возникнет ошибка AuthorizationError.USER_PERMISSION_DENIED. Проверить, удален ли аккаунт из иерархии, можно с помощью службы ManagedCustomerService.

    Также ошибка авторизации может возникнуть, если пользователь изменит права доступа для приложения, прошедшего аутентификацию. Например, другой администратор аккаунта AdWords может предоставить приложению доступ только для чтения. В этом случае все запросы mutate будут завершаться ошибкой AuthorizationError.USER_HAS_READONLY_PERMISSION.

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

  2. Ошибки, допускающие повторение попытки.

    Некоторые ошибки свидетельствуют о временных проблемах, устраняемых выполнением повторной попытки. К ним относятся CONCURRENT_MODIFICATION, UNEXPECTED_INTERNAL_API_ERROR, RATE_EXCEEDED и др.

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

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

    Настраивая повторение попыток, используйте правило экспоненциальной задержки. Например, между первой и второй попыткой может быть пауза 5 секунд, между второй и третьей – 10 секунд, а между третьей и четвертой – 20 секунд. Это предотвратит слишком частые вызовы API.

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

  3. Ошибки проверки.

    Ошибка проверки свидетельствует о том, что входные данные операции неверны. Примеры: PolicyViolationError, DateError, DateRangeError, StringLengthError, UrlError.

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

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

  4. Ошибки, связанные с синхронизацией.

    Многие приложения на основе API сохраняют объекты AdWords в локальной базе данных. Иногда возникают несоответствия между этой базой и информацией в аккаунте AdWords. Например, пользователь удалил группу объявлений в аккаунте, но сведения об этом не были переданы в приложение, поэтому оно будет вызывать API, учитывая такую группу объявлений как существующую. К ошибкам, связанным с синхронизацией, относятся INVALID_ID, DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD и многие другие.

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

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

Используйте функцию частичного отказа

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

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

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

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

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

Обратите внимание, что некоторые ошибки отражают зависимость между операциями, хотя одна из них может быть допустимой сама по себе. Пример: AdGroupAdError.ENTITY_REFERENCED_IN_MULTIPLE_OPS и AdParamError.AD_PARAM_CANNOT_BE_SPECIFIED_MULTIPLE_TIMES.

Синхронизируйте данные

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

Используйте журнал ошибок

Регистрируйте ошибки в журнале, чтобы их было легче отслеживать и устранять. Основная информация, которая вам потребуется: идентификатор запроса, название операции, вызвавшей ошибку, и название ошибки. Дополнительные сведения: идентификатор клиента, сервис API, задержка обмена данными при выполнении запроса, количество попыток, необработанные запрос и ответ SOAP.

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

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

Другое

Используйте тестовый аккаунт

Тестовый аккаунт – это аккаунт AdWords, который не используется для показа рекламы. В нем можно экспериментировать с AdWords API, а также проверять соединение приложения, логику управления кампаниями и другие настройки и процессы. Для тестового аккаунта не требуется одобренный идентификатор разработчика, поэтому вы можете приступить к работе, не дожидаясь, когда ваше приложение будет рассмотрено.

Объединяйте ключевые слова в один запрос

При использовании сервиса TargetingIdeaService вы указываете в селекторе TargetingIdeaSelector тип запроса (RequestType) – IDEAS или STATS. Тип STATS позволяет получать статистику по известным ключевым словам, которые можно объединить в один запрос, указав их в параметре RelatedToQuerySearchParameter. Для каждого ключевого слова будет возвращен один объект TargetingIdea. Этот метод более эффективен, так как сокращает количество запросов.

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

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