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

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

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

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

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

  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. Запустите скрипт установки.

Запустите скрипт установки для вашей целевой платформы. По умолчанию включена клиентская библиотека Python. При желании вы можете добавить дополнительные клиентские библиотеки ( --php , --ruby , --java , --dotnet или --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 .

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

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

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

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

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

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

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

    • «Какие типы кампаний доступны?»
    • «Как выполнить фильтрацию по дате в 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>
    • Естественный язык: "Проверить ресурс кампании"

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

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

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

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

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

    • Код Клода: /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

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

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

Команда слэша Цель Пример
/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?