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 programowania 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 API tylko do odczytu, przesyłać strumieniowo raporty ad hoc i rozwiązywać problemy z integracjami.

Asystent jest tworzony jako wtyczka modułowa dla platformy Google Antigravity i platformy Claude Code (wersja 4.0.0). Wykorzystuje umowy AGENTS.md i CLAUDE.md, wbudowane polecenia po ukośniku oraz specjalistyczne 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:

    • Token programisty interfejsu Google Ads API.
    • Plik konfiguracyjny Google Ads skonfigurowany za pomocą tokena programisty, danych logowania OAuth 2.0 i identyfikatora klienta, który znajduje się w katalogu domowym (np. google-ads.yaml w przypadku Pythona). Zapoznaj się z przewodnikiem konfiguracji biblioteki klienta.
    • Znajomość koncepcji i uwierzytelniania w interfejsie Google Ads API.

  2. Oprogramowanie:

Rozpocznij

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

1. Kopiowanie repozytorium

Skopiuj 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. Uruchom skrypt instalacyjny

Uruchom skrypt instalacyjny dla platformy docelowej. Domyślnie dołączona jest biblioteka klienta Python. Opcjonalnie możesz dołączyć dodatkowe biblioteki klienta (--php, --ruby, --java, --dotnet lub --all).

Antigravity

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

Możesz też dołączyć dodatkowe biblioteki klienta:

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

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

Możesz też dołączyć dodatkowe biblioteki klienta:

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

Claude Code

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

Możesz też dołączyć dodatkowe biblioteki klienta:

./install.sh claude --php --dotnet ```

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

Możesz też dołączyć dodatkowe biblioteki klienta:

.\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 jego numer 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ę, uruchom ponownie sesję hosta Antigravity / agy.
  • Claude Code: w aktywnej sesji Claude Code uruchom polecenie /reload-plugins lub ponownie uruchom claude.

5. Korzystanie z Asystenta

Z Asystenta możesz korzystać 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 koncepcyjne: zadawaj pytania dotyczące funkcji interfejsu Google Ads API, reguł architektury 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 na podstawie danych: generuj przetestowany, idiomatyczny kod za pomocą oficjalnych bibliotek klienta Google Ads (Python, Java, PHP, .NET i Ruby).

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

  • Programowe sprawdzanie zapytań GAQL: automatycznie przeprowadzaj testy 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 CSV: poproś o dane o skuteczności w języku polskim. 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.

    • Po prostu 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 kont MCK: pobieraj identyfikatory klientów subkont i mapuj hierarchie kont na koncie menedżera.

    • Claude Code: /get-cids <manager_cid>
    • Język naturalny: „Pobierz wszystkie identyfikatory klientów podrzędnych 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: 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

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łać 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 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 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: 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

Claude Code

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

Odinstalowanie

Aby odinstalować wtyczkę Asystenta:

Antigravity

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"

Następnie uruchom ponownie sesję hosta Antigravity.

Claude Code

W aktywnej sesji Claude Code: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Lub w terminalu: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(Opcjonalnie) Usuń lokalny rejestr marketplace: bash claude plugin marketplace remove google-ads-assistant-local

Społeczność i pomoc

Wytyczne dotyczące udziału

Zachęcamy do udziału! Wytyczne znajdziesz w pliku CONTRIBUTING.md w repozytorium GitHub.

Wstecz
Czym jest Asystent programisty interfejsu Google Ads API?