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, modüler bir eklenti olarak Google Antigravity ve Claude Code aracı çerçeveleri (v4.0.0) için geliştirilmiştir. Sürekli bağlam, güçlü güvenlik sınırları ve otomatik doğrulama işlem hatları sağlamak 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:

    • Python 3.10 veya daha yeni bir sürümün sisteminizde yüklü olması ve sisteminizin PATH'inde bulunması. Python, oluşturulan kodu yürütmek ve yerel doğrulama yardımcılarını çalıştırmak için kullanılır.
    • Ana makine aracısı platformu:
    • Sistem PATH'inize Git yüklenmiş olmalıdır.

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

Depoyu 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: ```bash ./install.sh agy

Veya ek istemci kitaplıkları ekleyin:

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

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

Veya ek istemci kitaplıkları ekleyin:

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

Claude Code

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

Veya ek istemci kitaplıkları ekleyin:

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

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

Veya ek istemci kitaplıkları ekleyin:

.\install.ps1 -Type claude -Php -Dotnet ```

3. Kimlik bilgilerini yapılandırma

API yapılandırma dosyanızın (örneğin, 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ştirme

  • Yerçekimsiz ortam: Eklentiyi yüklemek için yerçekimsiz ortam / agy 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 istemlerini veya 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 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.

    • "Mevcut kampanya türleri nelerdir?"
    • "GAQL'de tarihe göre nasıl filtreleme yaparım?"
    • "click_view ile impression_view 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 çok 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 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
    • Natural Language: validate: SELECT campaign.id FROM campaign

  • Nesne ve Protobuf şema incelemesi: Uzak meta veri ek yükü olmadan, etkin API sürümündeki 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"

  • 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 numaralı 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" demeniz yeterlidir.
    • Güvenliği Değiştirme: Güvenlik için, değiştirme işlemleri (oluşturma, güncelleme, silme) saved/code/ olarak oluşturulur ancak asla doğrudan asistan tarafından yürütülmez. Bunları inceleyip Asistan dışında manuel olarak uygulayı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 numaralı müşteri için dönüşümlerle ilgili sorunları gider." (Raporlar saved/data/ adresine 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 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: 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

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

Yüklemeyi kaldırma

Yardımcı eklentinin yüklemesini kaldırmak için:

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"

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

Claude Code

Etkin bir Claude Code oturumunda: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Alternatif olarak terminalinizden: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(İsteğe bağlı) Yerel pazar yeri kaydını kaldırın: bash claude plugin marketplace remove google-ads-assistant-local

Topluluk ve destek

Katkıda bulunma 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?