Menginstal dan menggunakan Asisten Developer Google Ads API

Asisten Developer Google Ads API menghadirkan keahlian domain Google Ads API yang mendalam langsung ke lingkungan coding AI Anda. Gunakan perintah bahasa alami dan perintah garis miring bawaan untuk membuat kueri, membuat kode library klien, menjalankan panggilan API hanya baca, menstreaming laporan ad hoc, dan memecahkan masalah integrasi.

Asisten ini dibuat untuk framework agen Google Antigravity dan Claude Code (v4.0.0) sebagai plugin modular. Agen ini menggunakan kontrak AGENTS.md dan CLAUDE.md, perintah garis miring bawaan, dan keterampilan domain khusus untuk mempertahankan konteks persisten, batas keamanan yang kuat, dan pipeline validasi otomatis. Lihat Apa yang dimaksud dengan Asisten Developer Google Ads API? untuk mengetahui ringkasan arsitektur dan desainnya.

Prasyarat

Sebelum memulai, pastikan Anda memiliki hal-hal berikut:

  1. Akses Google Ads API:

  2. Software:

Mulai

Ikuti langkah-langkah berikut untuk meng-clone repositori, menjalankan skrip penginstalan khusus platform, mengonfigurasi kredensial, dan mengaktifkan plugin.

1. Melakukan cloning repositori

Buat clone repositori ke komputer lokal Anda dan buka direktori project:

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

2. Menjalankan skrip penginstalan

Jalankan skrip penginstalan untuk platform target Anda. Secara default, library klien Python disertakan. Anda dapat menyertakan library klien tambahan (--php, --ruby, --java, --dotnet, atau --all) jika perlu.

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. Mengonfigurasi kredensial

Pastikan file konfigurasi API Anda (misalnya, google-ads.yaml, google_ads_php.ini, atau google_ads_config.rb) ditempatkan di direktori $HOME.

(Opsional) Untuk mengonfigurasi ID pelanggan default, masukkan nomor ID pelanggan Anda langsung ke config/customer_id.txt (misalnya, 1234567890). Anda juga dapat memeriksa atau menyematkan versi API aktif di config/api_version.txt.

4. Mengaktifkan plugin

  • Antigravity: Mulai ulang sesi host Antigravity / agy Anda untuk memuat plugin.
  • Claude Code: Dalam sesi Claude Code yang aktif, jalankan /reload-plugins atau mulai ulang claude.

5. Berinteraksi dengan Asisten

Anda dapat berinteraksi dengan Asisten menggunakan perintah bahasa alami atau perintah garis miring khusus langsung di terminal.

Fitur utama

  • Tanya Jawab bahasa alami dan panduan konseptual: Ajukan pertanyaan tentang fitur Google Ads API, aturan arsitektur, praktik terbaik, atau referensi tertentu. Asisten mendasarkan respons pada definisi API resmi, bukan hanya mengandalkan pelatihan LLM umum.

    • "Apa saja jenis kampanye yang tersedia?"
    • "Bagaimana cara memfilter menurut tanggal di GAQL?"
    • "Jelaskan perbedaan antara click_view dan impression_view."
    • "Apa yang dimaksud dengan set bersama dan bagaimana cara menggunakannya?"
    • Perintah garis miring Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Pembuatan kode library klien yang di-grounding: Buat kode idiomatis yang telah diuji menggunakan library klien Google Ads resmi (Python, Java, PHP, .NET, dan Ruby).

    • "Tampilkan kampanye dengan konversi terbanyak dalam 30 hari terakhir."
    • "Dapatkan semua nama grup iklan yang diaktifkan untuk pelanggan 123-456-7890."
    • "Tulis kode untuk membuat kampanye Performa Maksimal." Kode yang dihasilkan disimpan di direktori saved/code/.

  • Validasi kueri GAQL terprogram: Otomatis melakukan uji coba dan memvalidasi kueri kompleks terhadap metadata API, kompatibilitas kolom, aturan tayangan nol, dan segmentasi tanggal sebelum eksekusi.

    • Claude Code: /validate-gaql
    • Bahasa Alami: validate: SELECT campaign.id FROM campaign

  • Pemeriksaan skema Objek dan Protobuf: Memeriksa struktur resource, kolom bertingkat, jenis data, dan nilai enum secara dinamis untuk versi API aktif apa pun tanpa overhead metadata jarak jauh.

    • Claude Code: /inspect-object <resource_or_enum>
    • Bahasa Alami: "Periksa resource kampanye"

  • Pelaporan langsung ad hoc dan ekspor CSV: Minta data performa dalam bahasa Inggris yang sederhana. Asisten membuat, memvalidasi, dan menjalankan kueri GAQL secara langsung pada akun Anda, serta menstreaming tabel berformat langsung ke terminal.

    • "Tampilkan 5 kata kunci teratas menurut biaya bulan lalu untuk pelanggan 123-456-7890."
    • "Simpan hasil sebagai file CSV." (Ekspor ke saved/csv/).

  • Eksekusi API langsung dan keamanan mutasi: Jalankan skrip hanya baca yang dihasilkan langsung dalam lingkungan virtual terkelola.

    • Beri tahu Asisten: "Jalankan kode" atau "Jalankan skrip".
    • Keamanan Mutasi: Untuk keamanan, operasi mutasi (buat, update, hapus) dibuat ke saved/code/, tetapi tidak pernah dijalankan langsung oleh asisten. Tinjau dan jalankan secara manual di luar asisten.

  • Diagnostik lanjutan dan pemecahan masalah konversi: Selidiki kegagalan upload konversi offline, lakukan pra-validasi file upload, dan buat laporan diagnostik mendetail.

    • Claude Code: /troubleshoot-conversions
    • Bahasa Alami: "Troubleshoot conversions for customer 123-456-7890." (Laporan disimpan ke saved/data/).

  • Pemetaan hierarki akun pengelola: Ambil ID pelanggan sub-akun dan petakan hierarki akun di akun pengelola.

    • Claude Code: /get-cids <manager_cid>
    • Bahasa Alami: "Dapatkan semua ID pelanggan klien di bawah pengelola 123-456-7890"

  • Filter dan pengecualian listingan Performa Maksimal: Buat hierarki partisi produk dan pengecualian URL halaman web untuk grup aset.

    • Claude Code: /pmax-filter
    • Bahasa Alami: "Buat filter pengecualian halaman web untuk kampanye Performa Maksimal saya"

  • Konteks codebase tambahan: Daftarkan logika aplikasi dan arsitektur kustom Anda ke dalam penalaran Asisten.

    • 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

Referensi perintah garis miring Claude Code

Saat menggunakan Claude Code, perintah garis miring bawaan berikut tersedia. Di Google Antigravity, panggil kemampuan yang sama ini menggunakan perintah bahasa alami atau nama alat keterampilan seperti validate_gaql dan inspect_object, seperti yang dijelaskan dalam Fitur utama:

Perintah garis miring Tujuan Contoh
/validate-gaql Memvalidasi sintaksis, kompatibilitas, dan aturan GAQL. /validate-gaql
/inspect-object Memeriksa kolom, jenis, dan enum Protobuf. /inspect-object Campaign
/get-cids Menyelesaikan hierarki akun pengelola dan CID klien. /get-cids 1234567890
/troubleshoot-conversions Menjalankan diagnostik upload konversi offline. /troubleshoot-conversions
/pmax-filter Membuat filter dan pengecualian listingan Performa Maksimal. /pmax-filter
/explain Memberikan penjelasan terstruktur dalam 4 bagian. /explain shared set
/step-by-step Merumuskan rencana eksekusi tugas multifase. /step-by-step upload conversions
/assistant-tutorial Menjalankan panduan interaktif 11 langkah. /assistant-tutorial

Pemeliharaan dan update

Untuk mengupdate repositori, penginstalan plugin, dan library klien:

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

Uninstal

Untuk meng-uninstal plugin asisten:

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"

Kemudian, mulai ulang sesi host Antigravity Anda.

Claude Code

Dalam sesi Claude Code yang aktif:

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

Atau dari terminal Anda:

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

(Opsional) Hapus registry marketplace lokal:

claude plugin marketplace remove google-ads-assistant-local

Komunitas dan dukungan

Panduan kontribusi

Kami menerima kontribusi. Lihat file CONTRIBUTING.md di repositori GitHub untuk mengetahui panduannya.

Langkah berikutnya

Sebelumnya
Apa itu Asisten Developer Google Ads API?