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

Google Ads API Geliştirici Asistanı, Google Ads API alanıyla ilgili kapsamlı uzmanlık bilgisini doğrudan yapay zeka kodlama ortamınıza getirir. Sorgu oluşturmak, istemci kitaplığı kodu oluşturmak, salt okunur API çağrıları yürütmek, özel 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 temsilci çerçeveleri (v4.0.0) için modüler bir eklenti olarak tasarlanmıştır. 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. Mimarisine ve tasarımına genel bir bakış için Google Ads API Geliştirici Asistanı nedir? başlıklı makaleyi inceleyin.

Ö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 yeniden başlatın.

5. Asistan ile etkileşim kurma

Doğal dildeki istemleri veya özel eğik çizgi komutlarını doğrudan terminalinizde 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.

    • "Kullanılabilir kampanya türleri nelerdir?"
    • "GAQL'de tarihe göre nasıl filtreleme yapabilirim?"
    • "click_view ile impression_view arasındaki farkı açıklayın."
    • "Paylaşılan kitaplık 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ı getir."
    • "Maksimum Performans kampanyası oluşturmak için kod yaz." Oluşturulan kod saved/code/ dizinine kaydedilir.

  • Programatik GAQL sorgusu doğrulama: Karmaşık sorguları yürütmeden önce API meta verileri, alan uyumluluğu, sıfır gösterim kuralları ve tarih segmentasyonuna göre otomatik olarak deneme amaçlı çalıştırın 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 herhangi bir etkin API sürümü için kaynak yapılarını, iç içe yerleştirilmiş alanları, veri türlerini ve enum değerlerini dinamik olarak inceleyin.

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

  • Özel canlı raporlama ve CSV olarak dışa aktarma: Performans verilerini basit İngilizce ile 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 numaralı müşteri için geçen ay maliyete göre en iyi 5 anahtar kelimeyi göster."
    • "Sonuçları CSV dosyası olarak kaydedin." (saved/csv/ hedefine 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 adımları asistanın dışında manuel olarak inceleyip uygulayın.

  • Gelişmiş teşhis ve dönüşüm sorunlarını giderme: Çevrimdışı dönüşüm yükleme hatalarını inceleyin, 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/ konumuna kaydedildi).

  • Yönetici hesabı hiyerarşi eşlemesi: Alt hesap müşteri kimliklerini alın ve yönetici hesabı altındaki hesap hiyerarşilerini 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ümleme 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 akıl yürütme 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 dil istemlerini veya validate_gaql ve inspect_object gibi beceri aracı adlarını kullanarak aynı özellikleri çağırabilirsiniz:

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 işlemi

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ına bakın.

Sonraki adımlar

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