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

Google Ads API Developer Assistant – это инструмент, который позволяет использовать знания о 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 непосредственно в вашем аккаунте, передавая отформатированные таблицы в терминал.

    • "Покажи 5 ключевых слов с самыми высокими расходами за прошлый месяц для клиента 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?