Google Ads API Geliştirici Asistanı'nı yükleme ve kullanma

Google Ads API Geliştirici Asistanı, Google Ads API alanındaki kapsamlı uzmanlığını doğrudan yapay zeka kodlama ortamınıza taşır. Sorgu oluşturmak, istemci kitaplığı kodu oluşturmak, salt okunur API çağrıları yürütmek, geçici raporlar yayınlamak ve entegrasyon sorunlarını gidermek için doğal dil istemlerini ve yerleşik eğik çizgi komutlarını kullanın.

Asistan, Google Antigravity ve Claude Code ajan çerçeveleri (v4.0.0) için modüler bir eklenti olarak oluşturulmuştur. Kalıcı bağlam, güçlü güvenlik sınırları ve otomatik doğrulama ardışık düzenleri sağlamak için AGENTS.md ve CLAUDE.md sözleşmeleri, yerleşik eğik çizgi komutları ve özel alan becerileri kullanır.

Ön koşullar

Başlamadan önce, aşağıdakilere sahip olduğunuzdan emin olun:

  1. Google Ads API erişimi:

  2. Yazılım:

Başlayın

Depoyu klonlamak, platforma özel yükleme komut dosyasını çalıştırmak, kimlik bilgilerinizi yapılandırmak ve eklentiyi etkinleştirmek için aşağıdaki adımları uygulayın.

1. Depoyu klonlama

Kod deposunu yerel makinenize klonlayın ve proje dizinine gidin:

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

2. Yükleme komut dosyasını çalıştırma

Hedef platformunuz için yükleme komut dosyasını çalıştırın. Varsayılan olarak Python istemci kitaplığı dahil edilir. İsteğe bağlı olarak ek istemci kitaplıkları (--php, --ruby, --java, --dotnet veya --all) ekleyebilirsiniz.

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. Kimlik bilgilerini yapılandırma

API yapılandırma dosyanızın (ör. google-ads.yaml, google_ads_php.ini veya google_ads_config.rb) $HOME dizininizde bulunduğundan emin olun.

(İsteğe bağlı) Varsayılan bir müşteri kimliği yapılandırmak için müşteri kimliği numaranızı doğrudan config/customer_id.txt içine girin (ör. 1234567890). Ayrıca config/api_version.txt içinde etkin API sürümünüzü inceleyebilir veya sabitleyebilirsiniz.

4. Eklentiyi etkinleştirme

  • Antigravity: Eklentiyi yüklemek için Antigravity / agy ana makine oturumunuzu yeniden başlatın.
  • Claude Code: Etkin bir Claude Code oturumunda /reload-plugins komutunu çalıştırın veya claude komutunu kullanarak yeniden başlatın.

5. Asistan ile etkileşim kurma

Doğal dil istemleri veya doğrudan terminalinizdeki özel eğik çizgi komutlarını kullanarak Asistan ile etkileşim kurabilirsiniz.

Temel özellikler

  • Doğal dilde soru-cevap ve kavramsal rehberlik: Google Ads API özellikleri, mimari kurallar, en iyi uygulamalar veya belirli kaynaklar hakkında sorular sorun. Asistan, yalnızca genel LLM eğitimine güvenmek yerine yanıtları resmi API tanımlarına dayandırır.

    • "Hangi kampanya türleri kullanılabilir?"
    • "GAQL'de tarihe göre nasıl filtreleme yapabilirim?"
    • "Tıklama_görüntüleme ile gösterim_görüntüleme arasındaki farkı açıkla."
    • "Paylaşılan küme nedir ve nasıl kullanılır?"
    • Claude Code eğik çizgi komutları: /explain, /step-by-step, /assistant-tutorial

  • Temellendirilmiş istemci kitaplığı kodu oluşturma: Resmi Google Ads istemci kitaplıklarını (Python, Java, PHP, .NET ve Ruby) kullanarak test edilmiş, deyimsel kodlar oluşturun.

    • "Son 30 günde en çok dönüşüm sağlayan kampanyaları göster."
    • "123-456-7890 numaralı müşteri için etkinleştirilmiş tüm reklam grubu adlarını al."
    • "Maksimum Performans kampanyası oluşturmak için kod yaz." Oluşturulan kod, saved/code/ dizinine kaydedilir.

  • Programatik GAQL sorgu doğrulaması: Karmaşık sorguları yürütmeden önce API meta verilerine, alan uyumluluğuna, sıfır gösterim kurallarına ve tarih segmentasyonuna göre otomatik olarak test edin ve doğrulayın.

    • Claude Code: /validate-gaql
    • Doğal Dil: validate: SELECT campaign.id FROM campaign

  • Nesne ve Protobuf şeması inceleme: Uzak meta veri ek yükü olmadan etkin API sürümlerinin kaynak yapılarını, iç içe yerleştirilmiş alanlarını, veri türlerini ve enum değerlerini dinamik olarak inceleyin.

    • Claude Code: /inspect-object <resource_or_enum>
    • Doğal Dil: "Kampanya kaynağını incele"

  • Anlık canlı raporlama ve CSV dışa aktarma: Performans verilerini basit İngilizce olarak isteyin. Asistan, GAQL sorgularını doğrudan hesabınızda oluşturur, doğrular ve çalıştırır. Canlı biçimlendirilmiş tabloları terminale aktarır.

    • "123-456-7890 kimlikli müşteri için geçen ay maliyete göre ilk 5 anahtar kelimeyi göster."
    • "Sonuçları CSV dosyası olarak kaydedin." (saved/csv/ biçimine aktarılır.)

  • Doğrudan API yürütme ve mutasyon güvenliği: Oluşturulan salt okunur komut dosyalarını doğrudan yönetilen bir sanal ortamda yürütün.

    • Asistan'a "Kodu çalıştır" veya "Komut dosyasını çalıştır" deyin.
    • Değişiklik Güvenliği: Güvenlik için, değişiklik işlemleri (oluşturma, güncelleme, silme) saved/code/ için oluşturulur ancak asistan tarafından asla doğrudan yürütülmez. Bu komutları asistanın dışında manuel olarak inceleyip yürütün.

  • Gelişmiş teşhis ve dönüşüm sorunlarını giderme: Çevrimdışı dönüşüm yükleme hatalarını araştırın, yükleme dosyalarını önceden doğrulayın ve ayrıntılı teşhis raporları oluşturun.

    • Claude Code: /troubleshoot-conversions
    • Doğal dil: "123-456-7890 kimlikli müşterinin dönüşümleriyle ilgili sorunları gider." (Raporlar saved/data/ adresine kaydedilir).

  • Yönetici hesabı hiyerarşi eşlemesi: Alt hesap müşteri kimliklerini alın ve hesap hiyerarşilerini bir yönetici hesabı altında eşleyin.

    • Claude Code: /get-cids <manager_cid>
    • Doğal dil: "123-456-7890 kimlikli yönetici altındaki tüm müşteri kimliklerini getir"

  • Maksimum Performans listeleme filtreleri ve hariç tutmaları: Öğe grupları için ürün bölümü ağaçları ve web sayfası URL'si hariç tutmaları oluşturun.

    • Claude Code: /pmax-filter
    • Doğal dil: "Maksimum Performans kampanyam için web sayfası hariç tutma filtreleri oluştur"

  • Ek kod tabanı bağlamı: Uygulama mantığınızı ve özel mimarinizi Asistan'ın muhakeme sürecine kaydedin.

    • 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

Claude Code eğik çizgi komutları referansı

Claude Code'u kullanırken aşağıdaki yerleşik eğik çizgi komutları kullanılabilir. Google Antigravity'de, Temel özellikler bölümünde açıklandığı gibi doğal dilde istemler veya validate_gaql ve inspect_object gibi beceri aracı adlarını kullanarak aynı özellikleri çağırın:

Eğik çizgi komutu Amaç Örnek
/validate-gaql GAQL söz dizimini, uyumluluğunu ve kurallarını doğrular. /validate-gaql
/inspect-object Protobuf alanlarını, türlerini ve enum'larını inceler. /inspect-object Campaign
/get-cids Yönetici hesabı hiyerarşilerini ve müşteri kimliklerini çözer. /get-cids 1234567890
/troubleshoot-conversions Çevrimdışı dönüşüm yükleme teşhislerini çalıştırır. /troubleshoot-conversions
/pmax-filter Maksimum Performans listeleme filtreleri ve hariç tutmaları oluşturur. /pmax-filter
/explain 4 bölümden oluşan yapılandırılmış bir açıklama sunar. /explain shared set
/step-by-step Çok aşamalı bir görev yürütme planı oluşturur. /step-by-step upload conversions
/assistant-tutorial 11 adımlı etkileşimli bir adım adım açıklamalı kılavuz çalıştırır. /assistant-tutorial

Bakım ve güncellemeler

Depoyu, eklenti yüklemesini ve istemci kitaplıklarını güncellemek için:

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

Kaldırma

Asistan eklentisini kaldırmak için:

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"

Ardından Antigravity ana makine oturumunuzu yeniden başlatın.

Claude Code

Etkin bir Claude Code oturumunda:

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

Alternatif olarak terminalinizden:

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

(İsteğe bağlı) Yerel pazar yeri kayıt defterini kaldırın:

claude plugin marketplace remove google-ads-assistant-local

Topluluk ve destek

Katkı yönergeleri

Katkılarınızı bekliyoruz. Yönergeler için GitHub deposundaki CONTRIBUTING.md dosyasını inceleyin.

Önceki
Google Ads API Geliştirici Asistanı nedir?