Instalowanie i używanie Asystenta programisty interfejsu Google Ads API

Asystent dewelopera interfejsu Google Ads API zapewnia specjalistyczną wiedzę na temat 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 integracją.

Asystent został stworzony dla platform agentów Google Antigravity i Claude Code (wersja 4.0.0) jako wtyczka modułowa. Wykorzystuje umowy AGENTS.md i CLAUDE.md, wbudowane polecenia po ukośniku i specjalistyczne umiejętności związane z domeną, aby utrzymywać stały kontekst, solidne granice bezpieczeństwa i automatyczne potoki weryfikacji. Aby zapoznać się z omówieniem architektury i projektu asystenta, przeczytaj artykuł Czym jest asystent dewelopera interfejsu Google Ads API?.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że:

  1. Dostęp do interfejsu Google Ads API:

  2. Oprogramowanie:

Rozpocznij

Wykonaj te czynności, aby sklonować repozytorium, uruchomić skrypt instalacyjny dla konkretnej platformy, skonfigurować dane logowania i aktywować wtyczkę.

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 dołączona jest biblioteka klienta Pythona. Możesz też opcjonalnie 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 konfiguracji 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 go 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: uruchom ponownie sesję hosta Antigravity / agy, aby wczytać wtyczkę.
  • Claude Code: w aktywnej sesji Claude Code uruchom /reload-plugins lub uruchom ponownie claude.

5. Interakcja z Asystentem

Możesz wchodzić w interakcje z Asystentem, używając promptów w języku naturalnym lub specjalnych poleceń po ukośniku bezpośrednio w terminalu.

Najważniejsze funkcje

  • Pytania i odpowiedzi oraz wskazówki dotyczące pojęć w języku naturalnym: zadawaj pytania dotyczące funkcji interfejsu Google Ads API, reguł architektury, sprawdzonych metod lub konkretnych zasobów. Asystent opiera odpowiedzi na oficjalnych definicjach interfejsów API, a nie tylko na ogólnym trenowaniu 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”.
    • „Czym jest zestaw udostępniony i jak go używać?”
    • Polecenia po ukośniku w Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Generowanie kodu biblioteki klienta na podstawie danych: 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 nazwy wszystkich włączonych grup reklam klienta 123-456-7890”.
    • „Napisz kod, który utworzy kampanię Performance Max”. Wygenerowany kod jest zapisywany w katalogu saved/code/.

  • Walidator zapytań GAQL: automatyczne uruchamianie próbne i weryfikowanie złożonych zapytań pod kątem metadanych interfejsu API, zgodności pól, reguł dotyczących braku wyświetleń i segmentacji dat przed wykonaniem.

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

  • Inspekcja schematów obiektów i Protobuf: dynamicznie sprawdzaj struktury zasobów, zagnieżdżone pola, typy danych i wartości wyliczeniowe dla dowolnej aktywnej wersji interfejsu API bez narzutu związanego ze zdalnymi metadanymi.

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

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

    • „Pokaż 5 słów kluczowych o najwyższym koszcie 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: wygenerowane skrypty tylko do odczytu możesz wykonywać bezpośrednio w zarządzanym środowisku wirtualnym.

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

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

    • Claude Code: /troubleshoot-conversions
    • Język naturalny: „Rozwiąż problemy z konwersjami u klienta 123-456-7890”. (raporty są zapisywane w saved/data/).

  • Mapowanie hierarchii kont menedżera: pobieranie identyfikatorów klientów subkont i mapowanie hierarchii kont na koncie menedżera.

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

  • Filtry i wykluczenia informacji o produktach w kampaniach Performance Max: generowanie drzew podziału produktów i wykluczeń adresów URL stron internetowych w przypadku grup plików.

    • Claude Code: /pmax-filter
    • Język naturalny: „Utwórz filtry wykluczające strony internetowe w 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 w 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 umiejętności, 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 typy wyliczeniowe Protobuf. /inspect-object Campaign
/get-cids Rozpoznaje 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 Przedstawia 4-częściowe ustrukturyzowane wyjaśnienie. /explain shared set
/step-by-step tworzy wieloetapowy plan wykonania zadania; /step-by-step upload conversions
/assistant-tutorial Uruchamia interaktywny 11-etapowy przewodnik. /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

Odinstalowanie

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

Możesz też użyć terminala:

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 publikowania treści

Zachęcamy do współpracy. Wskazówki znajdziesz w pliku CONTRIBUTING.md w repozytorium GitHub.

Dalsze kroki

Wstecz
Czym jest Asystent programisty interfejsu Google Ads API?