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

Google Ads API Geliştirici Asistanı, Google Ads API alanındaki derin uzmanlığı doğrudan yapay zeka kodlama ortamınıza getirir. Sorgu oluşturmak, istemci kitaplığı kodu oluşturmak, salt okunur API çağrılarını yürütmek, geçici raporları yayınlamak ve entegrasyonlarda sorun 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. Sürekli bağlam, güçlü güvenlik sınırları ve otomatik doğrulama işlem hatlarını korumak için AGENTS.md ve CLAUDE.md sözleşmelerini, yerleşik eğik çizgi komutlarını ve özel alan becerilerini 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 dizininize yerleştirildiğinden 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'ye girin (ör. 1234567890). Ayrıca config/api_version.txt'de etkin API sürümünüzü inceleyebilir veya sabitleyebilirsiniz.

4. Eklentiyi etkinleştirin

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

5. Asistan ile etkileşim kurma

Doğal dil istemlerini 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, yanıtları yalnızca genel LLM eğitimine dayandırmak yerine resmi API tanımlarına dayandırır.

    • "Hangi kampanya türleri kullanılabilir?"
    • "GAQL'de tarihe göre nasıl filtreleme yaparım?"
    • "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 kod oluşturun.

    • "Son 30 günde en fazla dönüşüm elde eden 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 sorgusu doğrulama: 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 şema incelemesi: Kaynak yapılarını, iç içe yerleştirilmiş alanları, veri türlerini ve numaralandırılmış değerleri, etkin API sürümü için uzaktan meta veri ek yükü olmadan 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. Ayrıca, biçimlendirilmiş tabloları canlı olarak 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ı yürüt" deyin.
    • Güvenliği Değiştirme: Güvenlik için değiştirme işlemleri (oluşturma, güncelleme, silme) saved/code/ için oluşturulur ancak asla doğrudan asistan tarafından yürütülmez. Bu işlemleri inceleyip asistanın dışında manuel olarak gerçekleştirin.

  • 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 numaralı müşteri için dönüşümlerle ilgili sorunları gider." (Raporlar saved/data/ hesabına kaydedilir.)

  • MM hesabı hiyerarşisi eşleme: Alt hesap müşteri kimliklerini alın ve bir 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 müşteri kimliklerini al"

  • 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 kullanılırken aşağıdaki yerleşik eğik çizgi komutları kullanılabilir. Google Antigravity'de, Temel özellikler bölümünde açıklandığı gibi, validate_gaql ve inspect_object gibi doğal dil istemlerini veya 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 numaralandırmalarını inceler. /inspect-object Campaign
/get-cids MM 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ümlük 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ık etkileşimli bir 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

Yardımcı eklentiyi 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 kaydını kaldırma:

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?