Instalowanie i używanie Asystenta programisty interfejsu Google Ads API

Asystent programisty interfejsu Google Ads API zapewnia dostęp do wiedzy specjalistycznej w zakresie interfejsu Google Ads API bezpośrednio w środowisku kodowania AI. Używaj promptów w języku naturalnym i wbudowanych poleceń po ukośniku, aby tworzyć zapytania, generować kod biblioteki klienta, wykonywać wywołania interfejsu API tylko do odczytu, przesyłać strumieniowo raporty ad hoc i rozwiązywać problemy z integracjami.

Asystent jest tworzony jako wtyczka modułowa dla platform agentów Google Antigravity i Claude Code (wersja 4.0.0). Używa kontraktów AGENTS.md i CLAUDE.md, wbudowanych poleceń po ukośniku oraz specjalistycznych umiejętności w danej dziedzinie, aby zachować trwały kontekst, solidne granice bezpieczeństwa i zautomatyzowane potoki weryfikacji.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że:

  1. Dostęp do interfejsu Google Ads API:

    • Projekt Google Cloud z poziomem dostępu Eksplorator, Podstawowy dostęp lub Standardowy. Aby sprawdzić poziomy dostępu do projektu lub poprosić o odpowiedni poziom dostępu, zapoznaj się z artykułem Poziomy dostępu do interfejsu API.
    • Plik konfiguracyjny Google Ads skonfigurowany za pomocą danych logowania OAuth 2.0 i identyfikatora klienta, który znajduje się w katalogu domowym. Zapoznaj się z przewodnikiem konfiguracji biblioteki klienta.
    • Znajomość pojęć i uwierzytelniania w interfejsie Google Ads API.

  2. Oprogramowanie:

Rozpocznij

Aby sklonować repozytorium, uruchomić skrypt instalacyjny specyficzny dla platformy, skonfigurować dane logowania i aktywować wtyczkę, wykonaj te czynności.

1. Klonowanie repozytorium

Sklonuj repozytorium na komputer lokalny i przejdź do katalogu projektu:

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

2. Uruchamianie skryptu instalacyjnego

Uruchom skrypt instalacyjny dla platformy docelowej. Domyślnie biblioteka klienta Python jest dołączona. Opcjonalnie możesz dołączyć dodatkowe biblioteki klienta (--php, --ruby, --java, --dotnet lub --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. Konfigurowanie danych logowania

Upewnij się, że plik konfiguracyjny interfejsu API (np. google-ads.yaml, google_ads_php.ini lub google_ads_config.rb) znajduje się w katalogu $HOME.

(Opcjonalnie) Aby skonfigurować domyślny identyfikator klienta, wpisz numer identyfikatora klienta bezpośrednio w pliku config/customer_id.txt (np. 1234567890). Możesz też sprawdzić lub przypiąć aktywną wersję interfejsu API w pliku config/api_version.txt.

4. Aktywowanie wtyczki

  • Antigravity: aby wczytać wtyczkę, ponownie uruchom sesję hosta Antigravity / agy.
  • Claude Code: w aktywnej sesji Claude Code uruchom polecenie /reload-plugins lub ponownie uruchom claude.

5. Interakcja z Asystentem

Możesz korzystać z Asystenta za pomocą promptów w języku naturalnym lub specjalnych poleceń po ukośniku bezpośrednio w terminalu.

Najważniejsze funkcje

  • Pytania i odpowiedzi w języku naturalnym oraz wskazówki: zadawaj pytania dotyczące funkcji interfejsu Google Ads API, reguł architektury, sprawdzonych metod lub konkretnych zasobów. Asystent opiera odpowiedzi na oficjalnych definicjach interfejsu API, a nie tylko na ogólnym szkoleniu LLM.

    • „Jakie są dostępne typy kampanii?”
    • „Jak filtrować według daty w GAQL?”
    • „Wyjaśnij różnicę między click_view a impression_view”.
    • „Co to jest zestaw wspólny i jak go używać?”
    • Polecenia po ukośniku Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Generowanie kodu biblioteki klienta: generuj przetestowany, idiomatyczny kod za pomocą oficjalnych bibliotek klienta Google Ads (Python, Java, PHP, .NET i Ruby).

    • „Pokaż mi kampanie z największą liczbą konwersji w ciągu ostatnich 30 dni”
    • „Pobierz wszystkie włączone nazwy grup reklam dla klienta 123-456-7890”
    • „Napisz kod, aby utworzyć kampanię Performance Max” Wygenerowany kod jest zapisywany w katalogu saved/code/.

  • Walidacja zapytań GAQL: automatycznie przeprowadzaj uruchomienie próbne i sprawdzaj złożone zapytania na podstawie metadanych interfejsu API, zgodności pól, reguł dotyczących zerowej liczby wyświetleń i segmentacji według daty przed wykonaniem.

    • Claude Code: /validate-gaql
    • Język naturalny: validate: SELECT campaign.id FROM campaign

  • Sprawdzanie schematu obiektu i Protobuf: dynamicznie sprawdzaj struktury zasobów, pola zagnieżdżone, typy danych i wartości wyliczeniowe dla dowolnej aktywnej wersji interfejsu API bez obciążenia metadanymi zdalnymi.

    • Claude Code: /inspect-object <resource_or_enum>
    • Język naturalny: „Sprawdź zasób kampanii”

  • Raportowanie na żywo ad hoc i eksport do pliku CSV: poproś o dane o skuteczności w języku naturalnym. Asystent tworzy, weryfikuje i uruchamia zapytania GAQL bezpośrednio na Twoim koncie, przesyłając strumieniowo sformatowane tabele do terminala.

    • „Pokaż 5 najpopularniejszych słów kluczowych według kosztu w zeszłym miesiącu dla klienta 123-456-7890”
    • „Zapisz wyniki jako plik CSV” (Eksport do saved/csv/).

  • Bezpośrednie wykonywanie interfejsu API i bezpieczeństwo mutacji: wykonuj wygenerowane skrypty tylko do odczytu bezpośrednio w zarządzanym środowisku wirtualnym.

    • Powiedz Asystentowi: „Uruchom kod” lub „Wykonaj skrypt”.
    • Bezpieczeństwo mutacji: ze względów bezpieczeństwa operacje mutacji (tworzenie, aktualizowanie, usuwanie) są generowane w katalogu saved/code/, ale nigdy nie są wykonywane bezpośrednio przez Asystenta. Sprawdź je i wykonaj ręcznie poza Asystentem.

  • Zaawansowana diagnostyka i rozwiązywanie problemów z konwersjami: badaj błędy przesyłania konwersji offline, wstępnie sprawdzaj pliki przesyłane i generuj szczegółowe raporty diagnostyczne.

    • Claude Code: /troubleshoot-conversions
    • Język naturalny: „Rozwiąż problemy z konwersjami dla klienta 123-456-7890” (Raporty zapisane w katalogu saved/data/).

  • Mapowanie hierarchii konta menedżera: pobieraj identyfikatory klientów kont podrzędnych i mapuj hierarchie kont na koncie menedżera.

    • Claude Code: /get-cids <manager_cid>
    • Język naturalny: „Pobierz wszystkie identyfikatory klientów w relacji klient-klient na koncie menedżera 123-456-7890”

  • Filtry i wykluczenia informacji o produktach w kampaniach Performance Max: generuj drzewa podziału produktów i wykluczenia adresów URL stron internetowych dla grup komponentów.

    • Claude Code: /pmax-filter
    • Język naturalny: "Utwórz filtry wykluczeń stron internetowych dla mojej kampanii Performance Max"

  • Dodatkowy kontekst bazy kodu: zarejestruj logikę aplikacji i niestandardową architekturę w rozumowaniu Asystenta.

    • 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

Dokumentacja poleceń po ukośniku Claude Code

Podczas korzystania z Claude Code dostępne są te wbudowane polecenia po ukośniku. W Google Antigravity możesz wywoływać te same funkcje za pomocą promptów w języku naturalnym lub nazw narzędzi, takich jak validate_gaql i inspect_object, zgodnie z opisem w sekcji Najważniejsze funkcje:

Polecenie po ukośniku Cel Przykład
/validate-gaql Sprawdza składnię, zgodność i reguły GAQL. /validate-gaql
/inspect-object Sprawdza pola, typy i wyliczenia Protobuf. /inspect-object Campaign
/get-cids Rozwiązuje hierarchie kont menedżera i identyfikatory klientów. /get-cids 1234567890
/troubleshoot-conversions Uruchamia diagnostykę przesyłania konwersji offline. /troubleshoot-conversions
/pmax-filter Generuje filtry i wykluczenia informacji o produktach w kampaniach Performance Max. /pmax-filter
/explain Wyjaśnia w 4 częściach. /explain shared set
/step-by-step Formułuje wieloetapowy plan wykonania zadania. /step-by-step upload conversions
/assistant-tutorial Uruchamia interaktywny samouczek składający się z 11 kroków. /assistant-tutorial

Konserwacja i aktualizacje

Aby zaktualizować repozytorium, instalację wtyczki i biblioteki klienta:

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

Odinstalowywanie

Aby odinstalować wtyczkę Asystenta:

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"

Następnie ponownie uruchom sesję hosta Antigravity.

Claude Code

W aktywnej sesji Claude Code:

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

Lub w terminalu:

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

(Opcjonalnie) Usuń lokalny rejestr Marketplace:

claude plugin marketplace remove google-ads-assistant-local

Społeczność i pomoc

Wytyczne dotyczące udostępniania

Zachęcamy do udostępniania! Wytyczne znajdziesz w pliku CONTRIBUTING.md w repozytorium GitHub.

Wstecz
Czym jest Asystent programisty interfejsu Google Ads API?