Мы разделили ошибки на следующие широкие категории:
- Аутентификация
- Повторная попытка
- Проверка
- Связанные с синхронизацией
Хотя эти категории не охватывают все возможные ошибки, а некоторые могут входить в более чем одну категорию, они, тем не менее, могут служить отправной точкой для структурирования обработки ошибок вашего приложения. Дополнительные сведения о конкретной ошибке см. в разделе «Распространенные ошибки» .
Ошибки аутентификации
Аутентификация означает, было ли ваше приложение разрешено пользователем на доступ к Google Рекламе от его имени. Аутентификация управляется с помощью учетных данных, генерируемых потоком OAuth2 .
Наиболее распространенная причина ошибки аутентификации, возникающая из-за факторов, находящихся вне вашего контроля, заключается в том, что аутентифицированный пользователь отозвал разрешение, которое он дал вашему приложению действовать от его имени. Например, если ваше приложение управляет отдельными аккаунтами Google Рекламы для независимых клиентов и выполняет аутентификацию каждого клиента отдельно при управлении аккаунтом этого клиента, клиент может в любой момент отозвать доступ вашего приложения. В зависимости от того, когда ваш доступ был отозван, API может напрямую вернуть ошибку AuthenticationError.OAUTH_TOKEN_REVOKED , либо встроенные объекты учетных данных в клиентских библиотеках могут выдать исключение отзыва токена. В любом случае, если ваше приложение имеет пользовательский интерфейс для ваших клиентов, оно может попросить их перезапустить поток OAuth2, чтобы восстановить разрешение вашего приложения действовать от их имени.
Повторные ошибки
Некоторые ошибки, такие как TRANSIENT_ERROR или INTERNAL_ERROR , могут указывать на временную проблему, которую можно решить, повторив запрос после небольшой паузы.
Для запросов, инициированных пользователем, одна из стратегий — немедленно указать на ошибку в пользовательском интерфейсе и предоставить пользователю возможность инициировать повторную попытку. В качестве альтернативы ваше приложение может сначала автоматически повторить запрос, отображая ошибку в пользовательском интерфейсе только после достижения максимального количества повторов или общего времени ожидания пользователя.
Для запросов, инициированных на серверной стороне, ваше приложение должно автоматически повторять запрос до максимального количества попыток.
При повторных запросах используйте политику экспоненциальной отсрочки. Например, если вы сначала сделаете паузу за 5 секунд до первой повторной попытки, вы можете сделать паузу через 10 секунд после второй и через 20 секунд после третьей попытки. Экспоненциальная отсрочка помогает гарантировать, что вы не будете вызывать API слишком агрессивно.
Ошибки валидации
Ошибки проверки указывают на то, что входные данные для операции были неприемлемы. Например, PolicyViolationError , DateError , DateRangeError , StringLengthError и UrlFieldError .
Ошибки проверки чаще всего возникают в запросах, инициированных пользователем, когда пользователь ввел неверные данные. В этих случаях вам следует предоставить пользователю соответствующее сообщение об ошибке на основе полученной вами конкретной ошибки API. Вы также можете проверить ввод пользователя на предмет распространенных ошибок перед вызовом API, что сделает ваше приложение более отзывчивым и более эффективным в использовании API. Для запросов от серверной части ваше приложение может добавить неудачную операцию в очередь для проверки человеком-оператором.
Ошибки, связанные с синхронизацией
Многие приложения Google Рекламы поддерживают локальную базу данных для хранения своих объектов Google Рекламы. Одна из проблем этого подхода заключается в том, что локальная база данных может не синхронизироваться с реальными объектами Google Рекламы. Например, пользователь может удалить группу объявлений непосредственно в Google Рекламе, но приложение и локальная база данных не знают об этом изменении и продолжают отправлять вызовы API, как если бы группа объявлений существовала. Эти проблемы с синхронизацией могут проявляться в виде различных ошибок, таких как DUPLICATE_CAMPAIGN_NAME , DUPLICATE_ADGROUP_NAME , AD_NOT_UNDER_ADGROUP , CANNOT_OPERATE_ON_REMOVED_ADGROUPAD и многих других.
Для запросов, инициируемых пользователем, одна из стратегий заключается в том, чтобы предупредить пользователя о возможной проблеме синхронизации, немедленно запустить задание, которое извлекает соответствующий класс объектов Google Ads и обновляет локальную базу данных, а затем предлагает пользователю обновить пользовательский интерфейс.
Для внутренних запросов некоторые ошибки предоставляют приложению достаточно информации для автоматического и постепенного исправления локальной базы данных. Например, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD должен заставить ваше приложение пометить это объявление как удаленное в вашей локальной базе данных. Ошибки, которые вы не можете обработать таким способом, могут привести к тому, что ваше приложение запустит более полное задание синхронизации или будет добавлено в очередь для проверки человеком-оператором.