Подробное руководство по подключению к Google Ads API

В этом руководстве подробно описан весь процесс регистрации, аутентификации и первого обращения к API Google Ads.

1. Предварительные условия и иерархия учетных записей

Прежде чем взаимодействовать с API Google Ads, необходимо понимать иерархию аккаунтов и иметь правильную структуру аккаунтов верхнего уровня.

  • Управляющий аккаунт (MCC): Управляющий аккаунт Google Ads (ранее известный как «Мой клиентский центр») — это основной аккаунт, используемый для просмотра и управления несколькими клиентскими аккаунтами. Для получения токена разработчика Google Ads API необходимо иметь управляющий аккаунт.
  • Клиентский аккаунт: Стандартный аккаунт, в котором создаются кампании, группы объявлений и сами объявления, а также настраивается выставление счетов.

Пункт плана действий: Если у вас нет учетной записи администратора, создайте ее в разделе «Учетные записи администраторов Google Ads» .

2. Получите токен разработчика.

Токен разработчика однозначно идентифицирует ваше приложение для API Google Ads и управляет уровнем доступа к объему звонков.

Этапы подачи заявки

  1. Войдите в свой аккаунт Google Ads Manager .
  2. Перейдите в раздел Инструменты и настройки > Настройка > Центр API (или Администрирование > Центр API ).
  3. Заполните форму с данными разработчика и примите условия использования API.
  4. Подайте заявку.

Уровни доступа

  • Ожидает подтверждения: Вновь созданные токены немедленно получают статус «Ожидает подтверждения». Вы можете использовать токен со статусом «Ожидает подтверждения» для немедленного подключения к тестовым учетным записям , но он не будет работать с рабочими учетными записями.
  • Базовый доступ: после одобрения позволяет выполнять до 15 000 операций с API в день.
  • Стандартный доступ: Неограниченное количество ежедневных операций API для приложений, отвечающих требованиям минимально необходимой функциональности (RMF).

3. Создайте тестовые учетные записи.

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

Как создать учетную запись менеджера тестирования

  1. Перейдите на страницу создания аккаунта в Google Ads Test Manager .
  2. Войдите в систему, используя учетную запись Google, которая еще не связана с вашей рабочей учетной записью Google Ads Manager.
  3. Введите описательное название учетной записи (например, MyCompany Test MCC ).
  4. В качестве основного назначения выберите «Управление учетными записями других пользователей» .
  5. Выберите страну для выставления счетов, часовой пояс и валюту. Нажмите «Сохранить и продолжить» .

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

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

  1. Войдите в свою недавно созданную учетную запись менеджера тестирования .
  2. В левом навигационном меню щелкните «Учетные записи» , затем выберите «Настройки субсчетов» (или «Производительность »).
  3. Нажмите синюю кнопку «+» (плюс) и выберите «Создать новую учетную запись» .
  4. Выберите аккаунт Google Ads .
  5. Введите имя учетной записи (например, Test Client Account A ).
  6. Выберите часовой пояс и валюту, затем нажмите «Сохранить и продолжить» .
  7. Запишите 10-значный идентификатор клиента (например, 1234567890 без дефисов) для этой новой учетной записи клиента.

Важные правила для тестовых аккаунтов

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

4. Настройка проекта Google Cloud

Все запросы к API должны проходить аутентификацию с использованием проекта Google Cloud с включенным API Google Ads.

Шаги по включению API

  1. Перейдите в консоль Google Cloud .
  2. Создайте новый проект или выберите существующий.
  3. Перейдите в раздел API и сервисы > Библиотека .
  4. Найдите Google Ads API и нажмите «Включить» .

Примечание о ценах и выставлении счетов

  • Никаких комиссий за использование API: создание проекта Google Cloud, включение API Google Ads и генерация учетных данных OAuth 2.0 абсолютно бесплатны . Google не взимает никаких комиссий за вызов или использование самого API Google Ads.
  • Другие облачные ресурсы: Плата за использование Google Cloud будет взиматься только в том случае, если вы активно используете другие платные сервисы Google Cloud (такие как Compute Engine, Cloud Run или BigQuery) сверх лимитов бесплатного уровня для размещения вашего приложения или хранения рекламных данных.

5. Настройка аутентификации OAuth 2.0

API Google Ads использует OAuth 2.0 для аутентификации и авторизации запросов.

Этапы работы настольного или веб-приложения

  1. В вашем проекте Google Cloud перейдите в раздел API и сервисы > Экран согласия OAuth и настройте экран согласия.
  2. Перейдите в раздел API и сервисы > Учетные данные .
  3. Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
  4. Выберите тип приложения (например, настольное приложение или веб-приложение ).
  5. Нажмите «Создать» . Загрузите или скопируйте свой Client ID ) и Client Secret ).

Сгенерируйте токен обновления

Получив идентификатор клиента (Client ID) и секретный ключ клиента (Client Secret), необходимо сгенерировать токен обновления (Refresh Token). Это можно сделать либо с помощью Google OAuth 2.0 Playground, либо с помощью скрипта клиентской библиотеки.

Метод А: Использование Google OAuth 2.0 Playground (веб-платформа).

  1. Перейдите на страницу Google OAuth 2.0 Playground .
  2. Нажмите на значок шестеренки (настройка OAuth 2.0) в правом верхнем углу.
  3. Установите флажок «Использовать собственные учетные данные OAuth» .
  4. Введите свой Client ID OAuth2 и Client Secret , затем нажмите «Закрыть» .
  5. На шаге 1 (Выбор и авторизация API) слева введите область действия Google Ads API в поле «Введите свои собственные области действия»: https://www.googleapis.com/auth/adwords
  6. Нажмите «Авторизовать API» . Когда появится запрос, войдите в систему с помощью учетной записи Google, которая имеет доступ к вашей учетной записи Google Ads Manager (или тестовой учетной записи).
  7. На экране подтверждения нажмите «Продолжить» .
  8. На шаге 2 (Код авторизации обмена токенов) нажмите синюю кнопку «Код авторизации обмена токенов» .
  9. Ваш Refresh token и Access token будут отображены на панели ответа. Скопируйте и сохраните Refresh token .

Метод B: Использование скрипта клиентской библиотеки (пример на Python)

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

  1. Установите необходимую библиотеку OAuth: 
pip install google-auth-oauthlib
  1. Создайте скрипт с именем generate_refresh_token.py и запустите его: 
from google_auth_oauthlib.flow import InstalledAppFlow

# Set your Client ID and Secret
CLIENT_ID = "INSERT_YOUR_CLIENT_ID_HERE"
CLIENT_SECRET = "INSERT_YOUR_CLIENT_SECRET_HERE"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    client_config = {
        "installed": {
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
            "token_uri": "https://oauth2.googleapis.com/token",
        }
    }
    
    # Initialize the flow
    flow = InstalledAppFlow.from_client_config(client_config, SCOPES)
    
    # Run the local server flow to prompt the user to log in
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. Настройка клиентской библиотеки и учетных данных.

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

Поддерживаемые языки

  • Python: pip install google-ads
  • Java: доступна через Maven или Gradle.
  • PHP: composer require googleads/google-ads-php
  • .NET: Install-Package Google.Ads.GoogleAds
  • Ruby: gem install google-ads-googleads

Файл конфигурации ( google-ads.yaml )

Создайте конфигурационный файл, содержащий ваши учетные данные. По умолчанию метод инициализации клиентской библиотеки (например, GoogleAdsClient.load_from_storage() ) автоматически будет искать файл google-ads.yaml в двух местах:

  1. Текущий рабочий каталог, из которого запускается ваш скрипт.
  2. Ваш домашний каталог пользователя ( ~ в Linux/macOS или %HOMEPATH% в Windows).

Если вы храните файл в пользовательском месте, вы можете явно передать путь методу инициализации (например, load_from_storage("path/to/google-ads.yaml") ).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. Выполните свой первый вызов API.

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

Пример скрипта на Python ( quickstart.py ) 

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(f"Campaign with ID {row.campaign.id} and name '{row.campaign.name}' was found.")

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the current working directory
    # or the user's home directory (~). You can also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens)
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(f"Request failed with status {ex.error.code().name} and includes the following errors:")
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. Передовые методы и ресурсы

  • Ведение журналов: Включите подробное ведение журналов в библиотеке клиента, чтобы фиксировать идентификаторы запросов/ответов ( request-id ), которые необходимы при обращении в службу поддержки Google.
  • Обработка ошибок: Реализуйте надежную обработку ошибок для GoogleAdsException , в частности, управление ограничениями скорости ( RESOURCE_TEMPORARILY_EXHAUSTED ).
  • Официальная документация: Документация для разработчиков Google Ads API
  • Клиентские библиотеки и примеры кода: репозитории Google Ads на GitHub