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 dibuat untuk framework agen Google Antigravity dan Claude Code (v4.0.0) sebagai plugin modular. 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 secara opsional menyertakan library klien tambahan (--php, --ruby, --java, --dotnet, atau --all).

Antigravity

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

Atau sertakan library klien tambahan:

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

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

Atau sertakan library klien tambahan:

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

Claude Code

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

Atau sertakan library klien tambahan:

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

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

Atau sertakan library klien tambahan:

.\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. Aktifkan 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

  • Tanya jawab bahasa alami: Ajukan pertanyaan tentang fitur Google Ads API, praktik terbaik, atau resource tertentu.

  • Panduan konseptual dan tanya jawab bahasa alami: Ajukan pertanyaan tentang fitur Google Ads API, aturan arsitektur, 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 idiomatik 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.

    • Kode Claude: /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.

    • Kode Claude: /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 berdasarkan biaya bulan lalu untuk pelanggan 123-456-7890."
    • "Simpan hasil sebagai file CSV." (Mengekspor ke saved/csv/).

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

    • Cukup beri tahu Asisten: "Run the code" atau "Execute the script".
    • Keamanan Mutasi: Untuk keamanan, operasi mutasi (buat, update, hapus) dibuat ke saved/code/, tetapi tidak pernah dieksekusi 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.

    • Kode Claude: /troubleshoot-conversions
    • Bahasa Natural: "Troubleshoot konversi untuk pelanggan 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.

    • Kode Claude: /get-cids <manager_cid>
    • Bahasa Alami: "Get all client customer IDs under manager 123-456-7890" (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.

    • Kode Claude: /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: 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

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

Uninstal

Untuk meng-uninstal plugin asisten:

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"

Kemudian, mulai ulang sesi host Antigravity Anda.

Claude Code

Dalam sesi Claude Code yang aktif: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Atau dari terminal Anda: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(Opsional) Hapus pendaftaran marketplace lokal: bash 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?