Instalowanie i używanie Asystenta programisty interfejsu Google Ads API

Asystent dewelopera interfejsu Google Ads API udostępnia w środowisku programowania AI specjalistyczną wiedzę na temat interfejsu Google Ads API. Używaj promptów w języku naturalnym i wbudowanych poleceń z ukośnikiem, 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 przeznaczony do platform agentów Google Antigravity i Claude Code (wersja 4.0.0) jako wtyczka modułowa. Korzysta z AGENTS.md i CLAUDE.md kontraktów, wbudowanych poleceń ukośnika i 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:

  2. Oprogramowanie:

Rozpocznij

Aby sklonować repozytorium, uruchomić skrypt instalacyjny dla danej 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 uwzględniona jest biblioteka klienta Python. 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 polu config/customer_id.txt (np. 1234567890). Możesz też sprawdzić lub przypiąć aktywną wersję interfejsu API w polu config/api_version.txt.

4. Aktywowanie wtyczki

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

5. Interakcja z Asystentem

Możesz korzystać z Asystenta, używając w terminalu poleceń w języku naturalnym lub specjalnych poleceń z ukośnikiem.

Najważniejsze funkcje

  • Pytania i odpowiedzi w języku naturalnym oraz wskazówki koncepcyjne: 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 kliknięciem a wyświetleniem”.
    • „Czym jest udostępniony zestaw i jak go używać?”
    • Polecenia po ukośniku w Claude Code: /explain, /step-by-step, /assistant-tutorial

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

  • Programowe sprawdzanie zapytań GAQL: automatyczne testowanie i sprawdzanie złożonych zapytań 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
    • Naturalny język: validate: SELECT campaign.id FROM campaign

  • Sprawdzanie schematu obiektu i Protobuf: dynamiczne sprawdzanie struktur zasobów, zagnieżdżonych pól, typów danych i wartości wyliczeniowych w dowolnej aktywnej wersji interfejsu API bez obciążenia związanego z metadanymi zdalnymi.

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

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

    • „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 zmian: wykonuj wygenerowane skrypty tylko do odczytu bezpośrednio w zarządzanym środowisku wirtualnym.

    • Powiedz Asystentowi: „Uruchom kod” lub „Wykonaj skrypt”.
    • Mutate Safety: w przypadku bezpieczeństwa operacje modyfikujące (tworzenie, aktualizowanie, usuwanie) są generowane w 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 nieudane przesyłania konwersji offline, wstępnie sprawdzaj pliki przesyłania i generuj szczegółowe raporty diagnostyczne.

    • Claude Code: /troubleshoot-conversions
    • Język naturalny: „Rozwiąż problemy z konwersjami klienta 123-456-7890”. (Raporty zostały zapisane na koncie saved/data/).

  • Mapowanie hierarchii kont MCK: pobieranie identyfikatorów klientów podrzędnych kont i mapowanie hierarchii kont na koncie menedżera.

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

  • Filtry i wykluczenia dotyczące informacji o produktach w kampaniach Performance Max: generuj drzewa podziału produktów i wykluczenia adresów URL stron internetowych dla grup plikó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 procesie rozumowania 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 MCK i identyfikatory klientów. /get-cids 1234567890
/troubleshoot-conversions Uruchamia diagnostykę przesyłania konwersji offline. /troubleshoot-conversions
/pmax-filter Generuje filtry i wykluczenia dotyczące informacji o produktach w kampaniach Performance Max. /pmax-filter
/explain Zawiera 4-częściowe wyjaśnienie strukturalne. /explain shared set
/step-by-step Opracowuje 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

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 Cloud Code:

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

Możesz też wykonać te czynności w terminalu:

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

(Opcjonalnie) Usuń rejestrację na lokalnym rynku:

claude plugin marketplace remove google-ads-assistant-local

Społeczność i pomoc

Wytyczne dotyczące udostępniania

Wszelkie uwagi są mile widziane. Wytyczne znajdziesz w pliku CONTRIBUTING.md w repozytorium GitHub.

Wstecz
Czym jest Asystent programisty interfejsu Google Ads API?