Как установить и использовать Помощника разработчика Google Ads API

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

Ассистент создан для фреймворков агентов Google Antigravity и Claude Code (версия 4.0.0) в качестве модульного плагина. Он использует AGENTS.md и CLAUDE.mdконтракты, встроенные команды со слешем и специализированные навыки в определенной области, чтобы поддерживать постоянный контекст, надежные границы безопасности и автоматизированные конвейеры проверки.

Требования

Чтобы начать работу, требуется следующее:

  1. Доступ к Google Ads API:

  2. Программное обеспечение:

Начать

Чтобы клонировать репозиторий, запустить скрипт установки для определенной платформы, настроить учетные данные и активировать плагин, выполните следующие действия:

1. Клонируйте репозиторий

Клонируйте репозиторий на локальный компьютер и перейдите в каталог проекта:

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. Запустите скрипт установки

Запустите скрипт установки для целевой платформы. По умолчанию включена клиентская библиотека Python. Вы также можете добавить дополнительные клиентские библиотеки (--php, --ruby, --java, --dotnet или --all).

Antigravity

Linux / macOS:

./install.sh agy
# Or include additional client libraries:
./install.sh agy --java --dotnet

Windows (PowerShell)

.\install.ps1 -Type agy
# Or include additional client libraries:
.\install.ps1 -Type agy -Java -Dotnet

Claude Code

Linux / macOS:

./install.sh claude
# Or include additional client libraries:
./install.sh claude --php --dotnet

Windows (PowerShell)

.\install.ps1 -Type claude
# Or include additional client libraries:
.\install.ps1 -Type claude -Php -Dotnet

3. Как настроить учетные данные

Убедитесь, что файл конфигурации API (например, google-ads.yaml, google_ads_php.ini или google_ads_config.rb) находится в каталоге $HOME.

Необязательно. Чтобы настроить идентификатор клиента по умолчанию, введите его номер непосредственно в config/customer_id.txt (например, 1234567890). Вы также можете проверить или закрепить активную версию API в config/api_version.txt.

4. Активируйте плагин.

  • Antigravity. Перезапустите сеанс хоста Antigravity / agy, чтобы загрузить плагин.
  • Claude Code: в активном сеансе Claude Code выполните команду /reload-plugins или перезапустите claude.

5. Как взаимодействовать с Ассистентом

Вы можете взаимодействовать с Ассистентом, используя естественный язык или специальные команды со слешем непосредственно в терминале.

Основные функции

  • Вопросы и ответы на естественном языке и концептуальные рекомендации. Задавайте вопросы о функциях Google Ads API, правилах архитектуры, рекомендациях и конкретных ресурсах. Ассистент опирается на официальные определения API, а не только на общие знания, полученные в ходе обучения LLM.

    • Какие типы кампаний доступны?
    • Как отфильтровать данные по дате в GAQL?
    • Объясни разницу между click_view и impression_view.
    • Что такое общий набор и как им пользоваться?
    • Слеш-команды Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Создание кода клиентской библиотеки на основе фактов. Создавайте проверенный код, соответствующий стандартам, с помощью официальных клиентских библиотек Google Рекламы (Python, Java, PHP, .NET и Ruby).

    • Покажи мне кампании с наибольшим количеством конверсий за последние 30 дней.
    • "Получи названия всех включенных групп объявлений для клиента 123-456-7890".
    • Напишите код для создания кампании с максимальной эффективностью. Сгенерированный код сохраняется в каталоге saved/code/.

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

    • Claude Code: /validate-gaql
    • Натуральность: validate: SELECT campaign.id FROM campaign

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

    • Claude Code: /inspect-object <resource_or_enum>
    • Естественный язык: "Проверить ресурс кампании"

  • Специальные отчеты в реальном времени и экспорт в CSV. Запрашивайте данные об эффективности на английском языке. Ассистент создает, проверяет и выполняет запросы GAQL непосредственно в вашем аккаунте, передавая в терминал отформатированные таблицы в режиме реального времени.

    • Покажи пять самых дорогих ключевых слов за прошлый месяц для клиента 123-456-7890.
    • Сохраните результаты в виде CSV-файла. (Экспорт в saved/csv/).

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

    • Скажите Ассистенту Выполни код или Выполни скрипт.
    • Изменение безопасности. Для обеспечения безопасности операции по изменению (создание, обновление, удаление) генерируются в saved/code/, но никогда не выполняются непосредственно помощником. Проверьте их и выполните вручную вне помощника.

  • Расширенная диагностика и устранение неполадок с конверсиями. Выявляйте причины сбоев при загрузке офлайн-конверсий, проверяйте файлы перед загрузкой и создавайте подробные отчеты о диагностике.

    • Claude Code: /troubleshoot-conversions
    • Естественный язык: "Устрани неполадки с конверсиями для клиента 123-456-7890". (Отчеты сохраняются в аккаунте saved/data/.)

  • Сопоставление иерархии управляющего аккаунта. Получайте идентификаторы клиентов дочерних аккаунтов и сопоставляйте иерархии аккаунтов в управляющем аккаунте.

    • Claude Code: /get-cids <manager_cid>
    • Естественный язык: "Получить все идентификаторы клиентских аккаунтов под управлением аккаунта 123-456-7890"

  • Фильтры и исключения для информации о товарах в кампаниях с максимальной эффективностью. Создавайте деревья сегментов товаров и исключения URL веб-страниц для групп объектов.

    • Claude Code: /pmax-filter
    • Естественный язык: "Создай фильтры исключения страниц для моей кампании с максимальной эффективностью"

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

    • Linux / macOS:

      ./update.sh agy --context_dir /path/to/your/codebase
# Or for Claude Code:
./update.sh claude --context_dir /path/to/your/codebase

    • Windows (PowerShell)

      .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Справочник по слеш-командам Claude Code

При использовании Claude Code доступны следующие встроенные слеш-команды: В Google Antigravity эти же возможности можно использовать с помощью запросов на естественном языке или названий инструментов, например validate_gaql и inspect_object, как описано в разделе Основные функции.

Слеш-команда Цель Пример
/validate-gaql Проверяет синтаксис, совместимость и правила GAQL. /validate-gaql
/inspect-object Проверяет поля, типы и перечисления Protobuf. /inspect-object Campaign
/get-cids Разрешает иерархии управляющих аккаунтов и идентификаторы клиентов. /get-cids 1234567890
/troubleshoot-conversions Выполняет диагностику загрузки офлайн-конверсий. /troubleshoot-conversions
/pmax-filter Создает фильтры и исключения для информации о товарах в кампаниях с максимальной эффективностью. /pmax-filter
/explain Предоставляет структурированное объяснение из четырех частей. /explain shared set
/step-by-step Составляет многоэтапный план выполнения задачи. /step-by-step upload conversions
/assistant-tutorial Запускает интерактивное пошаговое руководство из 11 шагов. /assistant-tutorial

Обслуживание и обновления

Чтобы обновить репозиторий, плагин и клиентские библиотеки:

Antigravity

Linux / macOS:

./update.sh agy          # Update Antigravity plugin
./update.sh agy --all    # Include all client libraries

Windows (PowerShell)

.\update.ps1 -Type agy
.\update.ps1 -Type agy -All

Claude Code

Linux / macOS:

./update.sh claude       # Update Claude Code plugin
./update.sh claude --all # Include all client libraries

Windows (PowerShell)

.\update.ps1 -Type claude
.\update.ps1 -Type claude -All

Удаление

Чтобы удалить плагин Ассистента:

Antigravity

Linux / macOS:

rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell)

Remove-Item -Recurse -Force `
  "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

Затем перезапустите сеанс Antigravity.

Claude Code

Во время активного сеанса Claude Code:

/plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Или в терминале:

claude plugin uninstall \
  google-ads-api-developer-assistant@google-ads-assistant-local

(Необязательно.) Удалите запись о местном магазине приложений:

claude plugin marketplace remove google-ads-assistant-local

Сообщество и поддержка

Правила участия

Мы будем рады вашему участию! Ознакомьтесь с файлом CONTRIBUTING.md в репозитории GitHub.

Назад
Что такое Помощник разработчика Google Ads API?