Menginstal dan menggunakan Asisten Developer Google Ads API

Asisten Developer Google Ads API menghadirkan keahlian mendalam di domain Google Ads API 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, melakukan streaming laporan ad-hoc, dan memecahkan masalah integrasi.

Asisten ini dibuat untuk framework agen Google Antigravity dan Claude Code (v4.0.0) sebagai plugin modular. Fitur 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.

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

Clone repositori ke komputer lokal Anda, lalu buka direktori project:

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

2. Jalankan skrip penginstalan

Jalankan skrip penginstalan untuk platform target Anda. Secara default, library klien Python disertakan. Anda dapat menyertakan library klien tambahan secara opsional (--php, --ruby, --java, --dotnet, atau --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. Mengonfigurasi kredensial

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

(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 untuk memuat plugin.
  • Kode Claude: Dalam sesi Kode Claude yang aktif, jalankan /reload-plugins atau mulai ulang claude.

5. Berinteraksi dengan Asisten

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

Fitur utama

  • Panduan konseptual dan tanya jawab bahasa natural: Ajukan pertanyaan tentang fitur Google Ads API, aturan arsitektur, praktik terbaik, atau resource 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 itu set bersama dan bagaimana cara menggunakannya?"
    • Perintah garis miring Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Pembuatan kode library klien yang memiliki alasan: 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: Secara otomatis melakukan uji coba dan memvalidasi kueri kompleks terhadap metadata API, kompatibilitas kolom, aturan tayangan nol, dan segmentasi tanggal sebelum dieksekusi.

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

  • Pemeriksaan skema Objek dan Protobuf: Periksa struktur resource, kolom bertingkat, jenis data, dan nilai enum secara dinamis untuk versi API aktif 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 biasa. Asisten membuat, memvalidasi, dan menjalankan kueri GAQL langsung terhadap akun Anda, dengan melakukan streaming tabel yang diformat secara 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: Eksekusi skrip hanya baca yang dihasilkan langsung dalam lingkungan virtual terkelola.

    • Beri tahu Asisten: "Run the code" atau "Execute the script".
    • Keamanan Mutasi: Untuk keamanan, operasi mutasi (buat, update, hapus) dibuat untuk saved/code/, tetapi tidak pernah dieksekusi secara 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 Natural: "Troubleshoot conversions for customer 123-456-7890." (Pecahkan masalah konversi untuk pelanggan 123-456-7890.) (Laporan disimpan ke saved/data/).

  • Pemetaan hierarki akun MCC: Ambil ID pelanggan sub-akun dan petakan hierarki akun dalam 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 pohon partisi produk dan pengecualian URL halaman web untuk grup aset.

    • Claude Code: /pmax-filter
    • Bahasa Natural: "Buat filter pengecualian halaman web untuk kampanye PMax 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 MCC dan CID klien. /get-cids 1234567890
/troubleshoot-conversions Menjalankan diagnostik upload konversi offline. /troubleshoot-conversions
/pmax-filter Membuat filter dan pengecualian listingan PMax. /pmax-filter
/explain Memberikan penjelasan terstruktur 4 bagian. /explain shared set
/step-by-step Merumuskan rencana eksekusi tugas multi-fase. /step-by-step upload conversions
/assistant-tutorial Menjalankan panduan interaktif 11 langkah. /assistant-tutorial

Pemeliharaan dan update

Untuk memperbarui 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

Uninstalasi

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 pendaftaran 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.

Sebelumnya
Apa itu Asisten Developer Google Ads API?