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. Wykorzystuje AGENTS.md i CLAUDE.md kontrakty, wbudowane polecenia ukośnika i 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:

  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: ```bash ./install.sh agy

Możesz też uwzględnić dodatkowe biblioteki klienta:

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

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

Możesz też uwzględnić dodatkowe biblioteki klienta:

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

Claude Code

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

Możesz też uwzględnić dodatkowe biblioteki klienta:

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

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

Możesz też uwzględnić 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 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 załadować wtyczkę.
  • Claude Code: w aktywnej sesji Claude Code uruchom /reload-plugins lub ponownie uruchom claude.

5. Interakcja z Asystentem

Możesz wchodzić w interakcje z Asystentem, 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: zadawaj pytania o funkcje interfejsu Google Ads API, sprawdzone metody lub konkretne zasoby.

  • 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 trenowaniu LLM.

    • „Wskaż dostępne typy kampanii”.
    • „Jak filtrować według daty w GAQL?”
    • „Wyjaśnij różnicę między click_view a impression_view”.
    • „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 poprawności zapytań GAQL: automatyczne testowanie i sprawdzanie poprawności złożonych zapytań w odniesieniu do 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 eksport 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: bezpośrednie wykonywanie wygenerowanych skryptów tylko do odczytu w zarządzanym środowisku wirtualnym.

    • Po prostu powiedz Asystentowi: „Uruchom kod” lub „Wykonaj skrypt”.
    • Bezpieczeństwo zmian: ze względów bezpieczeństwa operacje zmieniają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 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 pod kontem 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 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: 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

W przypadku Claude Code dostępne są te wbudowane polecenia ukośnikowe: 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 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: 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 ponownie uruchom sesję hosta Antigravity.

Claude Code

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

Możesz też to zrobić w terminalu:bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

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

Społeczność i pomoc

Wskazówki dotyczące udostępniania

Udostępniane przez Was informacje są mile widziane. Wytyczne znajdziesz w pliku CONTRIBUTING.md w repozytorium GitHub.

Wstecz
Czym jest Asystent programisty interfejsu Google Ads API?