Работа с Google Ads на масштабе, автоматизация рутинных задач, интеграция данных с внешними системами – все это требует использования Google Ads API. Для PHP-разработчиков существует официальная библиотека, значительно упрощающая взаимодействие с API. В этой статье мы разберем, как эффективно использовать googleads/google-ads-php.
Введение в Google Ads API и PHP
Что такое Google Ads API и зачем он нужен?
Google Ads API – это программный интерфейс, который позволяет приложениям напрямую взаимодействовать с платформой Google Ads. Он предоставляет возможность программно управлять аккаунтами, кампаниями, группами объявлений, объявлениями, ключевыми словами, таргетингами, а также получать расширенную статистику и отчеты.
API необходим для реализации комплексных решений, таких как:
Автоматизированное создание и управление рекламными кампаниями на основе внешних данных (например, фидов товаров).
Интеграция данных Google Ads с CRM или аналитическими системами.
Построение собственных систем отчетности и BI-дашбордов.
Массовые операции, которые было бы сложно или невозможно выполнить вручную в веб-интерфейсе.
Преимущества использования PHP для работы с Google Ads API
PHP остается одним из наиболее популярных языков для веб-разработки. Его интеграция с Google Ads API особенно удобна, если ваша основная бизнес-логика или веб-приложение уже написаны на PHP. Использование PHP позволяет:
Интегрировать Google Ads функциональность непосредственно в ваши веб-приложения или бэкэнд-системы.
Использовать мощную экосистему PHP (Composer, фреймворки, библиотеки).
Развертывать решения на стандартных веб-серверах с поддержкой PHP.
Официальная клиентская библиотека для PHP существенно снижает порог входа, абстрагируя сложные детали взаимодействия с REST API, аутентификации и обработки данных.
Обзор googleads PHP lib: возможности и особенности
Библиотека googleads/google-ads-php является официальным SDK (Software Development Kit) от Google для работы с Google Ads API на языке PHP. Она предоставляет высокоуровневые классы и методы, которые соответствуют сервисам и ресурсам API.
Ключевые особенности библиотеки включают:
Поддержку всех основных операций API: получение данных (Search/SearchStream), создание, обновление, удаление объектов (Mutate).
Встроенную поддержку аутентификации через OAuth 2.0.
Обработку сериализации и десериализации данных (преобразование PHP-объектов в формат, понятный API, и наоборот).
Механизмы обработки ошибок и исключений API.
Поддержку асинхронных операций и потоковой передачи данных для отчетов.
Использование библиотеки избавляет разработчика от необходимости вручную формировать HTTP-запросы, управлять токенами доступа и парсить ответы API.
Подготовка к работе: Настройка окружения и аутентификация
Прежде чем приступить к написанию кода, необходимо выполнить ряд подготовительных шагов.
Получение учетных данных Google Ads API (clientId, clientSecret, refreshToken)
Для работы с Google Ads API требуются следующие учетные данные:
Developer Token: Уникальный идентификатор вашего центра клиентов (MCC), который позволяет API идентифицировать ваш аккаунт разработчика. Получается в аккаунте центра клиентов.
OAuth 2.0 Credentials: Учетные данные вашего приложения, использующего API. Получаются в Google Cloud Console при создании проекта типа ‘Web application’ или ‘Desktop app’. Вам потребуются client ID и client secret.
Refresh Token: Долгоживущий токен, который позволяет приложению получать новые Access Token’ы без повторного запроса разрешения у пользователя. Получается в процессе однократной OAuth 2.0 авторизации, когда пользователь аккаунта Google Ads дает вашему приложению разрешение на доступ к своим данным.
Процесс получения refreshToken обычно включает запуск скрипта авторизации, предоставленного библиотекой, или реализацию собственного OAuth 2.0 flow.
Установка и настройка googleads PHP lib через Composer
Библиотека распространяется через пакетный менеджер Composer. Установка проста:
composer require googleads/google-ads-phpЭта команда загрузит библиотеку и все ее зависимости в директорию vendor/ вашего проекта. Автозагрузка классов будет настроена через vendor/autoload.php.
Настройка файла конфигурации (googleads.ini) и параметров аутентификации
Библиотека может быть сконфигурирована различными способами, но наиболее распространенный – использование ini-файла. Создайте файл, например, googleads.ini, со следующим содержимым:
[GOOGLE_ADS]
DEVELOPER_TOKEN = "YOUR_DEVELOPER_TOKEN"
LOGIN_CUSTOMER_ID = "YOUR_LOGIN_CUSTOMER_ID" ; Обычно ID вашего MCC или аккаунта, от имени которого выполняются запросы
[OAUTH2]
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
REFRESH_TOKEN = "YOUR_REFRESH_TOKEN"DEVELOPER_TOKEN: Ваш токен разработчика.
LOGIN_CUSTOMER_ID: ID аккаунта клиента, через который выполняются запросы. В формате XXX-XXX-XXXX. Если вы используете MCC, это может быть ID MCC, а фактический аккаунт будет указан в заголовке customer_id каждого запроса (например, при получении данных или изменении объектов).
CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN: Ваши OAuth 2.0 учетные данные.
Этот файл конфигурации будет использоваться библиотекой для инициализации клиента API.
Основные операции с Google Ads API через PHP lib
Взаимодействие с API сводится к выполнению запросов на получение данных и запросов на изменение объектов.
Подключение к API и создание экземпляра сервиса
Первый шаг – инициализация клиента API с использованием файла конфигурации и получение экземпляра нужного сервиса (например, CampaignServiceClient, AdGroupServiceClient).
use Google\Ads\GoogleAds\Lib\V15\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V15\GoogleAdsClientBuilder;
/**
* Создает и возвращает экземпляр клиента Google Ads API.
*
* @param string $configFilePath Путь к файлу конфигурации googleads.ini.
* @return GoogleAdsClient
*/
function createGoogleAdsClient(string $configFilePath): GoogleAdsClient
{
return (new GoogleAdsClientBuilder())
->fromFile($configFilePath)
->build();
}
// Пример использования
$googleAdsClient = createGoogleAdsClient(__DIR__ . '/googleads.ini');Получение данных: примеры запросов (кампании, группы объявлений, ключевые слова)
Получение данных осуществляется с помощью Google Ads Query Language (GAQL). Это SQL-подобный язык для выборки данных из Google Ads. Запросы выполняются через сервис GoogleAdsServiceClient.
use Google\Ads\GoogleAds\Lib\V15\GoogleAdsClient;
use Google\Ads\GoogleAds\V15\Services\GoogleAdsServiceClient;
use Google\ApiCore\ApiException;
use Google\ApiCore\ValidationException;
/**
* Получает список кампаний для указанного клиента Google Ads.
*
* @param GoogleAdsClient $googleAdsClient Клиент Google Ads API.
* @param string $customerId ID клиента Google Ads (например, 'XXX-XXX-XXXX').
* @throws ApiException | ValidationException
*/
function listCampaigns(GoogleAdsClient $googleAdsClient, string $customerId): void
{
// Создаем сервис GoogleAdsServiceClient
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
// Формируем GAQL запрос для получения ID, имени и статуса кампаний
$query = 'SELECT campaign.id, campaign.name, campaign.status FROM campaign ORDER BY campaign.id';
try {
// Выполняем запрос и получаем потоковый ответ
$response = $googleAdsServiceClient->searchStream($customerId, $query);
printf("Список кампаний для клиента с ID %s:\n", $customerId);
// Обрабатываем строки результата
foreach ($response->iterateAllElements() as $googleAdsRow) {
$campaign = $googleAdsRow->getCampaign();
printf(
" Кампания с ID %d, именем '%s' и статусом '%s'.\n",
$campaign->getId(),
$campaign->getName(),
$campaign->getStatus()
);
}
} catch (ApiException $apiException) {
printf("Ошибка API: %s\n", $apiException->getMessage());
} catch (ValidationException $validationException) {
printf("Ошибка валидации: %s\n", $validationException->getMessage());
} catch (\Exception $exception) {
printf("Произошла ошибка: %s\n", $exception->getMessage());
}
}
// Пример использования (после инициализации $googleAdsClient)
// listCampaigns($googleAdsClient, 'YOUR_CUSTOMER_ID');Аналогично можно получать данные о группах объявлений (ad_group), ключевых словах (keyword_view), объявлениях (ad_group_ad) и других ресурсах, указывая соответствующие поля в GAQL запросе.
Создание и обновление объектов Google Ads (кампании, объявления, ключевые слова)
Для создания, обновления или удаления объектов используется операция mutate. Каждый сервис (например, CampaignService) имеет метод mutate, который принимает список операций (Add, Update, Remove).
use Google\Ads\GoogleAds\Lib\V15\GoogleAdsClient;
use Google\Ads\GoogleAds\V15\Services\CampaignOperation;
use Google\Ads\GoogleAds\V15\Enums\CampaignStatusEnum\CampaignStatus;
use Google\Ads\GoogleAds\V15\Enums\AdvertisingChannelTypeEnum\AdvertisingChannelType;
use Google\Ads\GoogleAds\V15\Enums\BudgetDeliveryMethodEnum\BudgetDeliveryMethod;
use Google\Ads\GoogleAds\V15\Resources\Campaign;
use Google\Ads\GoogleAds\V15\Resources\CampaignBudget;
use Google\Ads\GoogleAds\V15\Services\CampaignServiceClient;
use Google\Ads\GoogleAds\V15\Services\CampaignBudgetOperation;
use Google\Ads\GoogleAds\V15\Services\CampaignBudgetServiceClient;
use Google\Protobuf\Int64Value;
use Google\Protobuf\StringValue;
use Google\Protobuf\DoubleValue;
use Google\ApiCore\ApiException;
use Google\ApiCore\ValidationException;
/**
* Создает новую кампанию и бюджет для указанного клиента Google Ads.
*
* @param GoogleAdsClient $googleAdsClient Клиент Google Ads API.
* @param string $customerId ID клиента Google Ads.
* @param string $campaignName Имя новой кампании.
* @param float $budgetAmount Ежедневный бюджет в микроединицах (USD * 1e6).
* @throws ApiException | ValidationException
*/
function createCampaignWithBudget(
GoogleAdsClient $googleAdsClient,
string $customerId,
string $campaignName,
float $budgetAmount
): void
{
// Создаем бюджет кампании
$campaignBudget = new CampaignBudget([
'name' => new StringValue(['value' => 'Бюджет для ' . $campaignName . ' #' . uniqid()]),
'amount_micros' => new Int64Value(['value' => $budgetAmount]),
'delivery_method' => BudgetDeliveryMethod::STANDARD,
'explicitly_shared' => new BoolValue(['value' => false]) // Не общий бюджет
]);
// Создаем операцию добавления бюджета
$campaignBudgetOperation = new CampaignBudgetOperation();
$campaignBudgetOperation->setCreate($campaignBudget);
// Получаем сервис для бюджетов и выполняем операцию
$campaignBudgetServiceClient = $googleAdsClient->getCampaignBudgetServiceClient();
try {
$campaignBudgetResponse = $campaignBudgetServiceClient->mutateCampaignBudgets(
$customerId,
[$campaignBudgetOperation]
);
$newBudgetResourceName = $campaignBudgetResponse->getResults()[0]->getResourceName();
printf("Создан бюджет кампании с ResourceName: '%s'\n", $newBudgetResourceName);
} catch (ApiException $apiException) {
printf("Ошибка API при создании бюджета: %s\n", $apiException->getMessage());
return;
} catch (ValidationException $validationException) {
printf("Ошибка валидации при создании бюджета: %s\n", $validationException->getMessage());
return;
} catch (\Exception $exception) {
printf("Произошла ошибка при создании бюджета: %s\n", $exception->getMessage());
return;
}
// Создаем кампанию
$campaign = new Campaign([
'name' => new StringValue(['value' => $campaignName]),
'advertising_channel_type' => AdvertisingChannelType::SEARCH,
'status' => CampaignStatus::PAUSED, // Начинаем в паузе
'campaign_budget' => new StringValue(['value' => $newBudgetResourceName]),
// TODO: Добавить стратегию назначения ставок (bidding_strategy)
// 'manual_cpc' => new ManualCpc()
// 'maximize_conversions' => new MaximizeConversions()
]);
// Создаем операцию добавления кампании
$campaignOperation = new CampaignOperation();
$campaignOperation->setCreate($campaign);
// Получаем сервис для кампаний и выполняем операцию
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
try {
$campaignResponse = $campaignServiceClient->mutateCampaigns(
$customerId,
[$campaignOperation]
);
$newCampaignResourceName = $campaignResponse->getResults()[0]->getResourceName();
printf("Создана кампания с ResourceName: '%s'\n", $newCampaignResourceName);
} catch (ApiException $apiException) {
printf("Ошибка API при создании кампании: %s\n", $apiException->getMessage());
} catch (ValidationException $validationException) {
printf("Ошибка валидации при создании кампании: %s\n", $validationException->getMessage());
} catch (\Exception $exception) {
printf("Произошла ошибка при создании кампании: %s\n", $exception->getMessage());
}
}
// Пример использования (после инициализации $googleAdsClient)
// createCampaignWithBudget($googleAdsClient, 'YOUR_CUSTOMER_ID', 'Новая тестовая кампания', 10000000); // 10 USDОбновление объектов выполняется аналогично, но вместо setCreate() используется setUpdate(), и объект должен содержать resource_name и только те поля, которые нужно изменить, с установленной маской обновления (update_mask).
Обработка ошибок и исключений при работе с API
API может возвращать ошибки по различным причинам: неверные данные, превышение лимитов, проблемы с аутентификацией и т.д. Библиотека преобразует эти ошибки в исключения.
Основные типы исключений, которые следует отлавливать:
Google\ApiCore\ApiException: Общее исключение для ошибок API. Содержит информацию о статусе и деталях ошибки, включая список ошибок API.
Google\ApiCore\ValidationException: Исключение, связанное с проблемами валидации на стороне клиента или API.
Используйте блоки try...catch для корректной обработки потенциальных ошибок, как показано в примерах выше.
Примеры кода и практические советы
Пример: Получение списка всех кампаний аккаунта
Этот пример уже был представлен в разделе "Получение данных" и демонстрирует базовый процесс:
Инициализация клиента.
Получение сервиса GoogleAdsServiceClient.
Формирование GAQL запроса.
Выполнение запроса методом searchStream() (рекомендуется для больших объемов данных).
Итерация по результатам.
Пример: Создание новой кампании с бюджетом и таргетингом
Пример создания кампании с бюджетом также был показан ранее. Для добавления таргетинга (например, географического) или групп объявлений, необходимо создать соответствующие операции (GeoTargetConstant, AdGroup, AdGroupAd, Keyword) и использовать методы mutate соответствующих сервисов (GeoTargetConstantService, AdGroupService и т.д.).
Создание группы объявлений: Требует привязки к кампании (через campaign resource name).
Создание объявлений: Требует привязки к группе объявлений.
Создание ключевых слов: Требует привязки к группе объявлений.
Все эти операции могут быть объединены в один вызов mutate для повышения эффективности, если они относятся к одному сервису, или выполняться последовательно для разных сервисов.
Советы по оптимизации запросов и эффективному использованию googleads PHP lib
Используйте GAQL эффективно: Выбирайте только те поля, которые вам действительно нужны. Избегайте SELECT *. Используйте фильтрацию (WHERE) и сортировку (ORDER BY).
Пакетные операции (Batch operations): Для создания, обновления или удаления нескольких объектов одного типа (например, 1000 ключевых слов) объединяйте операции в один вызов mutate. Это значительно уменьшает количество обращений к API и ускоряет выполнение.
SearchStream: Используйте метод searchStream для получения больших наборов данных (отчеты, список всех объектов). Он позволяет обрабатывать данные по мере их поступления, не загружая весь результат в память.
Обработка лимитов: Учитывайте дневные лимиты API на количество операций. Планируйте выполнение задач так, чтобы не превышать их. Реализуйте логику повторных попыток с экспоненциальной задержкой (exponential backoff) при получении ошибок, связанных с лимитами или временной недоступностью.
Кэширование: Кэшируйте часто используемые данные (например, список кампаний или групп объявлений) локально, чтобы избежать избыточных запросов к API.
Расширенные возможности и полезные ресурсы
Библиотека googleads/google-ads-php предоставляет доступ ко всему спектру возможностей Google Ads API.
Работа с отчетами Google Ads API
GAQL является основным инструментом для построения отчетов. Вы можете запрашивать метрики (metrics) в сочетании с атрибутами ресурсов (resource.attribute) и сегментами (segments) для получения детализированной статистики. Результаты запросов search или searchStream по сути и являются отчетами.
Для получения очень больших отчетов рассмотрите использование Reporting API (доступно через тот же GoogleAdsServiceClient) или Google Ads API Reporting, которое позволяет асинхронно создавать и скачивать отчеты в CSV или других форматах.
Использование дополнительных функций googleads PHP lib (например, загрузка файлов)
Библиотека также поддерживает специализированные сервисы и функции. Например, сервис OfflineUserDataJobService используется для загрузки данных об офлайн-конверсиях или списках клиентов. Этот процесс обычно включает создание задания, добавление операций и запуск задания, что также реализуется через соответствующие классы и методы библиотеки.
Ресурсы для изучения Google Ads API и googleads PHP lib (документация, примеры, форумы)
Для углубленного изучения Google Ads API и работы с PHP-библиотекой наиболее полезны следующие ресурсы:
Официальная документация Google Ads API: Содержит полное описание API, GAQL, ресурсов и сервисов. [Поиск по ‘Google Ads API documentation’]
Документация googleads PHP lib на GitHub: Репозиторий библиотеки содержит README, примеры кода и документацию по использованию классов. [Поиск по ‘googleads/google-ads-php github’]
Примеры кода Google Ads API: Официальные примеры на различных языках, включая PHP. Отличный ресурс для понимания, как выполнять конкретные операции. [Поиск по ‘Google Ads API code examples’]
Форум разработчиков Google Ads: Площадка для вопросов и обсуждений с другими разработчиками и командой Google. [Поиск по ‘Google Ads API developer forum’]
Использование googleads/google-ads-php в сочетании с глубоким пониманием Google Ads API и GAQL позволяет создавать мощные и эффективные решения для автоматизации и управления вашей рекламой.