Установите и используйте Google Ads API Developer Assistant.

The Google Ads API Developer Assistant brings deep Google Ads API domain expertise directly into your AI coding environment. Use natural language prompts and built-in slash commands to construct queries, generate client library code, execute read-only API calls, stream ad hoc reports, and troubleshoot integrations.

The Assistant is built for the Google Antigravity and Claude Code agent frameworks (v4.0.0) as a modular plugin. It uses AGENTS.md and CLAUDE.md contracts, built-in slash commands, and specialized domain skills to maintain persistent context, robust safety boundaries, and automated validation pipelines.

Предварительные требования

Прежде чем начать, убедитесь, что у вас есть следующее:

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

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

    • Для корректной работы требуется установленный Python 3.10 или более поздней версии, который должен быть добавлен в системный PATH. Python используется для выполнения сгенерированного кода и запуска локальных вспомогательных процессов проверки.
    • Платформа хост-агента:
    • Git установлен в системной переменной PATH.

Начните

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

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

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

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

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

Run the installation script for your target platform. By default, the Python client library is included. You can optionally include additional client libraries ( --php , --ruby , --java , --dotnet , or --all ).

Антигравитация

Linux / macOS: ```bash ./install.sh agy

Или же можно добавить дополнительные клиентские библиотеки:

./install.sh agy --java --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type agy

Или же можно добавить дополнительные клиентские библиотеки:

.\install.ps1 -Type agy -Java -Dotnet ```

Кодекс Клода

Linux / macOS: ```bash ./install.sh claude

Или же можно добавить дополнительные клиентские библиотеки:

./install.sh клод --php --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type claude

Или же можно добавить дополнительные клиентские библиотеки:

.\install.ps1 -Type claude -Php -Dotnet ```

3. Настройка учетных данных

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

(Optional) To configure a default customer ID, enter your customer ID number directly into config/customer_id.txt (for example, 1234567890 ). You can also inspect or pin your active API version in config/api_version.txt .

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

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

5. Взаимодействуйте с ассистентом.

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

Основные характеристики

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

  • Natural language Q&A and conceptual guidance: Ask questions about Google Ads API features, architectural rules, or specific resources. The Assistant grounds responses in official API definitions rather than relying solely on general LLM training.

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

  • Генерация кода клиентской библиотеки на основе проверенных методов: создание протестированного, идиоматического кода с использованием официальных клиентских библиотек Google Ads (Python, Java, PHP, .NET и Ruby).

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

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

    • Код Клода: /validate-gaql
    • Проверка на естественном языке: validate: SELECT campaign.id FROM campaign

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

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

  • Ad hoc live reporting and CSV export: Ask for performance data in plain English. The Assistant constructs, validates, and runs GAQL queries directly against your account, streaming live formatted tables into the terminal.

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

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

    • Просто скажите Ассистенту: «Запустить код» или «Выполнить скрипт» .
    • Mutate Safety: For safety, mutating operations (create, update, delete) are generated to saved/code/ but never executed directly by the assistant. Review and execute them manually outside the assistant.

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

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

  • Сопоставление иерархии учетных записей MCC: Получение идентификаторов клиентов суб-аккаунтов и сопоставление иерархий учетных записей в рамках учетной записи менеджера.

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

  • Фильтры и исключения в списке Performance Max: Создание деревьев разделов товаров и исключений URL-адресов веб-страниц для групп активов.

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

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

    • Linux / macOS: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • Windows (PowerShell): powershell .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Справочник команд слэша в коде Клода

When using Claude Code, the following built-in slash commands are available. In Google Antigravity, invoke these same capabilities using natural language prompts or skill tool names like validate_gaql and inspect_object , as described in Key features :

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

Техническое обслуживание и обновления

Для обновления репозитория, установки плагина и клиентских библиотек:

Антигравитация

Linux / macOS: bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Кодекс Клода

Linux / macOS: bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

Удаление

Чтобы удалить плагин помощника:

Антигравитация

Linux / macOS: bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell): powershell Remove-Item -Recurse -Force "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

Затем перезапустите сессию хоста Antigravity.

Кодекс Клода

В активной сессии Claude Code: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Или из терминала: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(Необязательно) Удалите локальный реестр маркетплейса: bash claude plugin marketplace remove google-ads-assistant-local

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

Правила внесения пожертвований

Вклад приветствуется! Инструкции по внесению изменений см. в файле CONTRIBUTING.md в репозитории GitHub .

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