Что делать, если токен обновления Google Ads API истек?

При работе с Google Ads API для автоматизации процессов управления рекламными кампаниями, аутентификация является критически важным этапом. Механизм OAuth 2.0 широко используется для предоставления вашему приложению доступа к данным аккаунта Google Ads от имени пользователя или сервиса. Ключевыми компонентами этого процесса являются токены доступа (access tokens) и токены обновления (refresh tokens).

Саммари статьи

ChatGPT

Google AI

Grok

Perplexity

Что такое токен обновления Google Ads API?

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

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

Токен обновления связывается с конкретным клиентом OAuth 2.0 (ваше приложение) и аккаунтом пользователя (владельцем аккаунта Google Ads, который предоставил разрешение). Он является конфиденциальной информацией и должен храниться безопасно.

Почему токен обновления истекает? Распространенные причины

Важно понимать, что токен обновления Google Ads API (выданный через пользовательский OAuth) обычно не имеет фиксированного срока истечения в том же смысле, что и токен доступа. Вместо этого он может стать недействительным или отозванным по ряду причин, что эквивалентно "истечению" в контексте его пригодности для использования. Наиболее частые причины:

Истечение срока действия из-за неактивности: Если токен обновления не использовался для получения нового токена доступа в течение 6 месяцев, он становится недействительным.

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

Изменение пароля пользователя: В некоторых сценариях (хотя и реже при использовании стандартного OAuth 2.0 flow) изменение пароля пользователем может аннулировать связанные токены.

Слишком много выданных токенов: Существует ограничение на количество выданных токенов обновления на пару "пользователь + клиент OAuth". При превышении лимита самые старые токены могут быть аннулированы.

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

Удаление/деактивация аккаунта Google: Если аккаунт пользователя, предоставившего доступ, удален или деактивирован.

Последствия истечения токена обновления

Истечение (или недействительность) токена обновления имеет прямые и серьезные последствия для вашего приложения и автоматизированных процессов:

Ошибки аутентификации: Все вызовы к Google Ads API, которые используют этот токен обновления (для получения токена доступа), начнут завершаться ошибками аутентификации.

Остановка автоматизации: Запланированные задачи, отчеты, синхронизации данных и другие автоматизированные операции, зависящие от доступа к API, прекратят работу.

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

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

Обнаружение истекшего токена обновления

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

Типичные ошибки и сообщения об ошибках при истечении токена

При попытке использовать недействительный токен обновления для получения нового токена доступа или при попытке сделать API-вызов с уже недействительным токеном доступа, полученным через этот токен обновления, Google Ads API или OAuth2 endpoint вернет ошибку. Наиболее характерные из них:

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

invalid_grant: Эта ошибка, возвращаемая OAuth 2.0 endpoint Google, прямо указывает на то, что предоставленный токен обновления (или код авторизации) недействителен, отозван или просрочен.

Сообщения от клиентских библиотек: Клиентские библиотеки Google Ads API (например, для Python, Java, PHP) обертывают низкоуровневые ошибки API и могут генерировать специфические исключения, такие как google.api_core.exceptions.Unauthenticated в Python, часто содержащие вложенные ошибки с деталями (invalid_grant).

Пример обработки ошибки в Python при попытке получить клиента Google Ads:

from google.ads.googleads.client import GoogleAdsClient
from google.api_core import exceptions as api_exceptions

def initialize_google_ads_client(config_path: str) -> GoogleAdsClient | None:
    """Инициализирует клиент Google Ads API, обрабатывая ошибки аутентификации."""
    try:
        # Попытка инициализации клиента. 
        # Если токен обновления недействителен, этот шаг или первый API-вызов выдаст ошибку.
        client = GoogleAdsClient.load_from_storage(config_path)
        
        # Опционально: сделать тестовый вызов для проверки валидности токена доступа/обновления
        # customer_service = client.get_service("CustomerService")
        # customer_service.list_accessible_customers()
        
        print("Клиент Google Ads API успешно инициализирован.")
        return client
    except api_exceptions.Unauthenticated as e:
        print(f"Ошибка аутентификации при инициализации клиента: {e}")
        # Проверяем детали ошибки на наличие 'invalid_grant'
        if "invalid_grant" in str(e):
            print("Токен обновления, вероятно, недействителен. Требуется повторная авторизация.")
            # Здесь может быть логика для уведомления или запуска процесса переавторизации
        return None
    except Exception as e:
        print(f"Произошла неожиданная ошибка: {e}")
        return None

# Пример использования:
# config_file = "google_ads_config.yaml"
# google_ads_client = initialize_google_ads_client(config_file)
# if google_ads_client is None:
#     print("Не удалось подключиться к Google Ads API из-за проблем с аутентификацией.")

Мониторинг API-вызовов и логов на предмет ошибок аутентификации

Активное логирование всех исходящих запросов к Google Ads API и ответов на них является лучшей практикой. Настройте систему мониторинга, которая анализирует эти логи на наличие HTTP-статусов 401 (Unauthorized) или специфических кодов ошибок API (UNAUTHENTICATED) и сообщений (invalid_grant).

Интеграция с централизованными системами логирования (например, Stackdriver/Operations Suite в Google Cloud, ELK Stack, Datadog) и системами оповещения (Slack, email, PagerDuty) позволит оперативно получать уведомления при возникновении ошибок аутентификации, указывающих на проблему с токеном обновления.

Решение проблемы: Получение нового токена обновления

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

Ручной процесс получения нового токена обновления через OAuth2

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

Формирование URL авторизации: Ваше приложение должно сгенерировать URL для перенаправления пользователя на страницу согласия Google. Этот URL включает client_id, redirect_uri, scope (список запрашиваемых разрешений, например, https://www.googleapis.com/auth/adwords), response_type=code и, опционально, access_type=offline (чтобы явно запросить токен обновления) и prompt=consent (чтобы принудительно показать экран согласия).

Перенаправление пользователя: Пользователь перенаправляется на этот URL в браузере.

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

Получение кода авторизации: После согласия пользователя Google перенаправляет его обратно на ваш redirect_uri. В параметрах URL будет присутствовать одноразовый code (код авторизации).

Обмен кода на токены: Ваше приложение на своем сервере (т.к. это чувствительная операция, использующая client_secret) выполняет POST-запрос к OAuth2 endpoint Google (https://oauth2.googleapis.com/token), передавая полученный code, ваш client_id, client_secret, redirect_uri и grant_type=authorization_code.

Получение нового токена обновления и доступа: В ответ на этот запрос Google выдает JSON-объект, содержащий новый токен доступа, срок его действия, новый токен обновления и, возможно, другие параметры. Именно этот новый токен обновления нужно безопасно сохранить, заменив им старый.

Автоматизация процесса получения нового токена обновления (если применимо)

В случае пользовательских аккаунтов (аутентификация через OAuth 2.0 flow с участием пользователя), получение нового токена обновления всегда требует первичного ручного шага – пользователь должен снова пройти процедуру согласия. Автоматизация здесь может касаться только:

Автоматического обнаружения ошибки invalid_grant.

Автоматической отправки уведомления ответственному лицу о необходимости повторной авторизации.

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

Полностью автоматизированное получение нового токена обновления без участия пользователя возможно только при использовании сервисных аккаунтов (Service Accounts), что является альтернативным методом аутентификации, применимым для сценариев "сервер-сервер" (подробнее об этом в последнем разделе).

Валидация нового токена обновления

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

Используйте полученный новый токен обновления, чтобы запросить новый токен доступа у Google OAuth2 endpoint.

С использованием полученного нового токена доступа, выполните простой и безопасный вызов к Google Ads API. Например, получение списка доступных клиенту Customer ID (CustomerService.list_accessible_customers).

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

Превентивные меры: Как предотвратить истечение токена обновления

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

Реализация автоматического обновления токена (refresh token rotation) и поддержание активности

Как упоминалось, пользовательский токен обновления может стать недействительным из-за 6 месяцев неактивности. Чтобы этого избежать, необходимо регулярно использовать токен обновления для получения нового токена доступа. Даже если текущий токен доступа еще действителен, периодическое выполнение операции "обновления" (refresh) с использованием токена обновления сбрасывает таймер неактивности в 6 месяцев.

Некоторые реализации OAuth 2.0, включая Google, могут выдавать новый токен обновления при каждом запросе на обновление токена доступа (refresh token rotation). Это рекомендуемая практика безопасности: при получении новой пары access/refresh token, необходимо начать использовать новую пару и безопасно удалить старую пару. Это повышает безопасность, но также требует аккуратного управления токенами.

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

Пример концептуального кода (Python) для регулярного обновления:

# Предполагается, что у вас есть функция get_stored_refresh_token() 
# и save_new_tokens(access_token, refresh_token)

import time
# from your_oauth_library import OAuth2Client

# Имитация клиента OAuth
class MockOAuth2Client:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self._last_refresh_use = time.time() # Имитация таймера неактивности

    def refresh_access_token(self, refresh_token: str) -> tuple[str, str | None]:
        """Имитация запроса на обновление токена доступа."""
        if time.time() - self._last_refresh_use > 6*30*24*3600: # Имитация 6 месяцев
             raise Exception("invalid_grant: Token inactive") # Имитация ошибки
             
        print("Используем токен обновления для получения нового токена доступа.")
        # В реальном коде здесь был бы HTTP запрос к https://oauth2.googleapis.com/token
        # с grant_type=refresh_token, refresh_token, client_id, client_secret

        new_access_token = f"new_access_token_{int(time.time())}" # Выдаем новый access token
        
        # Имитация выдачи нового refresh token (token rotation)
        # В реальном API это опционально и зависит от конфигурации клиента OAuth
        issue_new_refresh_token = True # Настройте согласно поведению API
        new_refresh_token = f"new_refresh_token_{int(time.time())}" if issue_new_refresh_token else None
        
        self._last_refresh_use = time.time() # Сбрасываем таймер неактивности
        print(f"Получен новый access token. Новый refresh token выдан: {new_refresh_token is not None}")
        return new_access_token, new_refresh_token

# Функция для поддержания активности токена
def keep_refresh_token_active(oauth_client: MockOAuth2Client, current_refresh_token: str):
    """Периодически обновляет токен доступа, чтобы токен обновления оставался активным."""
    print("Проверяем необходимость обновления токена доступа...")
    try:
        # Попытка обновить токен доступа
        new_access_token, new_refresh_token = oauth_client.refresh_access_token(current_refresh_token)
        
        # Если выдан новый refresh token (rotation)
        if new_refresh_token:
            print("Выполняется ротация токена обновления.")
            # Необходимо сохранить new_refresh_token вместо current_refresh_token
            # и использовать его для будущих обновлений
            # save_new_tokens(new_access_token, new_refresh_token)
            print("Новый токен обновления сохранен.")
            # В реальной системе здесь нужно обновить текущий токен обновления в вашей системе хранения
            current_refresh_token = new_refresh_token # Обновляем ссылку для демонстрации
        else:
             # Сохраняем только новый access token, refresh token не изменился
             # save_new_tokens(new_access_token, current_refresh_token)
             print("Токен обновления не изменился.")
        
        print("Токен обновления успешно подтвержден как активный.")
        return True, current_refresh_token # Возвращаем статус и (возможно) обновленный токен
        
    except Exception as e:
        if "invalid_grant" in str(e):
            print(f"Ошибка: Токен обновления недействителен. Требуется повторная авторизация: {e}")
            return False, current_refresh_token # Токен недействителен
        else:
            print(f"Неожиданная ошибка при обновлении токена: {e}")
            return False, current_refresh_token # Другая ошибка

# Пример использования в цикле или по расписанию
# oauth_client = MockOAuth2Client("your_client_id", "your_client_secret")
# stored_refresh_token = "your_initially_stored_refresh_token"

# Успешное обновление
# is_valid, updated_token = keep_refresh_token_active(oauth_client, stored_refresh_token)
# stored_refresh_token = updated_token if is_valid else stored_refresh_token # Обновить, если валидно и ротировано

# Имитация неактивности (прошло > 6 месяцев)
# oauth_client._last_refresh_use = time.time() - 7*30*24*3600 
# is_valid, updated_token = keep_refresh_token_active(oauth_client, stored_refresh_token)
# if not is_valid:
#     print("Нужна повторная авторизация пользователя.")

Управление сроком действия токена обновления (если это возможно)

Для стандартных пользовательских OAuth 2.0 токенов обновления, основным управляемым аспектом "срока действия" является предотвращение истечения по неактивности (те самые 6 месяцев). Других механизмов "управления сроком действия" со стороны клиента обычно нет – токен либо активен, либо отозван/недействителен.

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

Безопасное хранение и управление токенами обновления

Токен обновления является эквивалентом логина/пароля для доступа к аккаунту пользователя через ваше приложение. Его компрометация может привести к несанкционированному доступу к аккаунту Google Ads. Поэтому крайне важно хранить токены обновления безопасно:

Не храните токены обновления в открытом виде в коде, файлах конфигурации на файловой системе или в открытых базах данных.

Используйте системы управления секретами (например, Google Secret Manager, HashiCorp Vault, AWS Secrets Manager) или зашифрованные базы данных.

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

Регулярно проводите аудит безопасности мест хранения учетных данных.

Альтернативные методы аутентификации (если применимо)

Пользовательский OAuth 2.0 flow с токенами обновления идеален, когда ваше приложение работает от имени конкретного пользователя и ему требуется доступ к его аккаунту Google Ads (например, десктопное приложение, веб-приложение, где пользователь вручную подключает свой аккаунт).

Однако для сценариев, где требуется полностью автоматизированный доступ без привязки к сессии конкретного пользователя (например, бэкенд-сервис, который обрабатывает данные всех ваших клиентов, или CRON-задание), предпочтительным методом аутентификации являются Сервисные аккаунты (Service Accounts).

Использование сервисных аккаунтов (Service Accounts) для автоматизации

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

Аутентификация с использованием сервисного аккаунта обычно происходит путем подписи запроса (или создания JWT — JSON Web Token) вашим закрытым ключом и обмена его на токен доступа. Этот процесс не требует участия пользователя и может быть полностью автоматизирован.

Ключевое отличие: Сервисный аккаунт имеет доступ к Google Ads напрямую, как если бы это был отдельный пользователь, а не от имени другого пользователя через делегирование.

Преимущества и недостатки различных методов аутентификации

Пользовательский OAuth 2.0:

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

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

Сервисные аккаунты:

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

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

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