دستیار توسعه‌دهنده API گوگل ادز را نصب و استفاده کنید

دستیار توسعه‌دهنده API گوگل ادز، تخصص عمیق در حوزه API گوگل ادز را مستقیماً به محیط کدنویسی هوش مصنوعی شما می‌آورد. از دستورات زبان طبیعی و دستورات اسلش داخلی برای ساخت کوئری‌ها، تولید کد کتابخانه کلاینت، اجرای فراخوانی‌های API فقط خواندنی، پخش گزارش‌های موردی و عیب‌یابی یکپارچه‌سازی‌ها استفاده کنید.

دستیار (Assistant) به عنوان یک افزونه ماژولار برای چارچوب‌های عامل Google Antigravity و Claude Code (نسخه ۴.۰.۰) ساخته شده است. این برنامه از قراردادهای AGENTS.md و CLAUDE.md ، دستورات اسلش داخلی و مهارت‌های تخصصی دامنه برای حفظ زمینه پایدار، مرزهای ایمنی قوی و خطوط لوله اعتبارسنجی خودکار استفاده می‌کند.

پیش‌نیازها

قبل از شروع، مطمئن شوید که موارد زیر را دارید:

  1. دسترسی به API تبلیغات گوگل:

  2. نرم‌افزار:

شروع کنید

برای کپی کردن مخزن، اجرای اسکریپت نصب مخصوص پلتفرم، پیکربندی اعتبارنامه‌ها و فعال کردن افزونه، این مراحل را دنبال کنید.

۱. مخزن را کلون کنید

مخزن را روی دستگاه محلی خود کلون کنید و به دایرکتوری پروژه بروید:

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

۲. اسکریپت نصب را اجرا کنید

اسکریپت نصب را برای پلتفرم مورد نظر خود اجرا کنید. به طور پیش‌فرض، کتابخانه کلاینت پایتون گنجانده شده است. می‌توانید به صورت اختیاری کتابخانه‌های کلاینت اضافی ( --php ، --ruby ، --java ، --dotnet یا --all ) را نیز اضافه کنید.

ضد جاذبه

لینوکس / macOS: ```bash ./install.sh agy

یا کتابخانه‌های کلاینت بیشتری را اضافه کنید:

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

ویندوز (پاورشل): ```powershell .\install.ps1 -Type agy

یا کتابخانه‌های کلاینت بیشتری را اضافه کنید:

.\install.ps1 -نوع agy -جاوا -دات‌نت ```

کلود کد

لینوکس / macOS: ```bash ./install.sh claude

یا کتابخانه‌های کلاینت بیشتری را اضافه کنید:

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

ویندوز (پاورشل): ```powershell .\install.ps1 -Type claude

یا کتابخانه‌های کلاینت بیشتری را اضافه کنید:

.\install.ps1 -نوع claude -Php -Dotnet ```

۳. پیکربندی اعتبارنامه‌ها

مطمئن شوید که فایل پیکربندی API شما (برای مثال، google-ads.yaml ، google_ads_php.ini یا google_ads_config.rb ) در دایرکتوری $HOME شما قرار دارد.

(اختیاری) برای پیکربندی شناسه مشتری پیش‌فرض، شماره شناسه مشتری خود را مستقیماً در config/customer_id.txt وارد کنید (برای مثال، 1234567890 ). همچنین می‌توانید نسخه فعال API خود را در config/api_version.txt بررسی یا پین کنید.

۴. افزونه را فعال کنید

  • Antigravity: برای بارگذاری افزونه، جلسه میزبان Antigravity / agy خود را مجدداً راه‌اندازی کنید.
  • کد کلود: در یک جلسه فعال کد کلود، دستور /reload-plugins را اجرا کنید یا claude مجدداً راه‌اندازی کنید.

۵. با دستیار تعامل داشته باشید

شما می‌توانید با استفاده از دستورات زبان طبیعی یا دستورات اسلش اختصاصی مستقیماً در ترمینال خود با دستیار (Assistant) تعامل داشته باشید.

ویژگی‌های کلیدی

  • پرسش و پاسخ به زبان طبیعی و راهنمایی مفهومی: در مورد ویژگی‌های API گوگل ادز، قوانین معماری یا منابع خاص سوال بپرسید. دستیار به جای تکیه صرف بر آموزش‌های عمومی LLM، پاسخ‌ها را بر اساس تعاریف رسمی API ارائه می‌دهد.

    • «انواع کمپین‌های موجود کدامند؟»
    • "چگونه می‌توانم در GAQL بر اساس تاریخ فیلتر کنم؟"
    • «تفاوت بین click_view و impression_view را توضیح دهید.»
    • «مجموعه اشتراکی چیست و چگونه می‌توانم از آن استفاده کنم؟»
    • دستورات اسلش کلود کد: /explain ، /step-by-step ، /assistant-tutorial

  • تولید کد کتابخانه کلاینت مبتنی بر شواهد: با استفاده از کتابخانه‌های رسمی کلاینت گوگل ادز (پایتون، جاوا، PHP، دات‌نت و روبی)، کد تست‌شده و اصطلاحی تولید کنید.

    • «کمپین‌هایی را که بیشترین تبدیل را در ۳۰ روز گذشته داشته‌اند، به من نشان بده.»
    • «تمام نام‌های گروه‌های تبلیغاتی فعال‌شده برای مشتری ‎123-456-7890‎ را دریافت کنید.»
    • «برای ایجاد یک کمپین Performance Max کد بنویسید.» کد تولید شده در دایرکتوری saved/code/ ذخیره می‌شود.

  • اعتبارسنجی پرس‌وجوی GAQL برنامه‌ریزی‌شده: پرس‌وجوهای پیچیده را به‌طور خودکار قبل از اجرا، در برابر فراداده‌های API، سازگاری فیلد، قوانین عدم نمایش و تقسیم‌بندی تاریخ، اجرا و اعتبارسنجی کنید.

    • کد کلود: /validate-gaql
    • زبان طبیعی: validate: SELECT campaign.id FROM campaign

  • بازرسی طرحواره اشیاء و Protobuf: به صورت پویا ساختارهای منابع، فیلدهای تو در تو، انواع داده‌ها و مقادیر شمارشی را برای هر نسخه فعال API بدون سربار فراداده از راه دور بررسی کنید.

    • کد کلود: /inspect-object <resource_or_enum>
    • زبان طبیعی: "بازرسی منابع کمپین"

  • گزارش زنده موردی و خروجی CSV: داده‌های عملکرد را به زبان ساده درخواست کنید. دستیار، پرس‌وجوهای GAQL را مستقیماً در حساب شما ایجاد، اعتبارسنجی و اجرا می‌کند و جداول قالب‌بندی شده زنده را به ترمینال ارسال می‌کند.

    • «۵ کلمه کلیدی برتر بر اساس هزینه ماه گذشته برای مشتری ۱۲۳-۴۵۶-۷۸۹۰ را نمایش بده.»
    • «نتایج را به عنوان فایل CSV ذخیره کنید.» (به saved/csv/ منتقل می‌شود).

  • اجرای مستقیم API و ایمنی در برابر جهش: اسکریپت‌های فقط خواندنی تولید شده را مستقیماً در یک محیط مجازی مدیریت‌شده اجرا کنید.

    • به سادگی به دستیار بگویید: «کد را اجرا کن» یا «اسکریپت را اجرا کن» .
    • ایمنی در برابر جهش: برای ایمنی، عملیات جهش (ایجاد، به‌روزرسانی، حذف) در مسیر saved/code/ ایجاد می‌شوند اما هرگز مستقیماً توسط دستیار اجرا نمی‌شوند. آن‌ها را به صورت دستی در خارج از دستیار بررسی و اجرا کنید.

  • تشخیص پیشرفته و عیب‌یابی تبدیل: بررسی خطاهای آپلود تبدیل آفلاین، اعتبارسنجی اولیه فایل‌های آپلود و تولید گزارش‌های تشخیصی دقیق.

    • کد کلود: /troubleshoot-conversions
    • زبان طبیعی: "عیب‌یابی تبدیل‌ها برای مشتری ۱۲۳-۴۵۶-۷۸۹۰." (گزارش‌ها در saved/data/ ذخیره شدند).

  • نگاشت سلسله مراتب حساب MCC: بازیابی شناسه‌های مشتری زیرحساب‌ها و نگاشت سلسله مراتب حساب‌ها تحت یک حساب مدیر.

    • کد کلود: /get-cids <manager_cid>
    • زبان طبیعی: "شناسه‌های همه مشتریان تحت مدیریت ۱۲۳-۴۵۶-۷۸۹۰ را دریافت کنید"

  • فیلترها و استثنائات فهرست‌بندی با حداکثر کارایی: درخت‌های پارتیشن محصول و استثنائات URL صفحه وب را برای گروه‌های دارایی ایجاد کنید.

    • کد کلود: /pmax-filter
    • زبان طبیعی: "برای کمپین PMax من فیلترهای حذف صفحه وب ایجاد کنید"

  • زمینه کدبیس اضافی: منطق برنامه و معماری سفارشی خود را در استدلال دستیار ثبت کنید.

    • لینوکس / macOS: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • ویندوز (PowerShell): powershell .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

مرجع دستورات اسلش کلود کد

هنگام استفاده از Claude Code، دستورات اسلش داخلی زیر در دسترس هستند. در Google Antigravity، همین قابلیت‌ها را با استفاده از دستورات زبان طبیعی یا نام‌های ابزار مهارت مانند validate_gaql و inspect_object ، همانطور که در ویژگی‌های کلیدی توضیح داده شده است، فراخوانی کنید:

دستور اسلش هدف مثال
/validate-gaql سینتکس، سازگاری و قوانین GAQL را اعتبارسنجی می‌کند. /validate-gaql
/inspect-object فیلدها، نوع‌ها و enumهای Protobuf را بررسی می‌کند. /inspect-object Campaign
/get-cids سلسله مراتب MCC و CID های کلاینت را برطرف می کند. /get-cids 1234567890
/troubleshoot-conversions تشخیص آپلود تبدیل آفلاین را اجرا می‌کند. /troubleshoot-conversions
/pmax-filter فیلترها و استثنائات فهرست PMax را ایجاد می‌کند. /pmax-filter
/explain یک توضیح ساختاریافته ۴ قسمتی ارائه می‌دهد. /explain shared set
/step-by-step یک برنامه اجرای وظیفه چند مرحله‌ای تدوین می‌کند. /step-by-step upload conversions
/assistant-tutorial یک راهنمای تعاملی ۱۱ مرحله‌ای را اجرا می‌کند. /assistant-tutorial

نگهداری و به‌روزرسانی‌ها

برای به‌روزرسانی مخزن، نصب افزونه و کتابخانه‌های کلاینت:

ضد جاذبه

لینوکس / macOS: bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

ویندوز (پاورشل): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

کلود کد

لینوکس / macOS: bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

ویندوز (پاورشل): powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

حذف نصب

برای حذف افزونه دستیار:

ضد جاذبه

لینوکس / مک‌او‌اس: bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

ویندوز (PowerShell): powershell Remove-Item -Recurse -Force "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

سپس جلسه میزبان Antigravity خود را مجدداً راه اندازی کنید.

کلود کد

در یک جلسه فعال Claude Code: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

یا از ترمینال خود: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(اختیاری) حذف رجیستری بازار محلی: bash claude plugin marketplace remove google-ads-assistant-local

جامعه و پشتیبانی

دستورالعمل‌های مشارکت

از مشارکت‌ها استقبال می‌شود! برای راهنمایی بیشتر به فایل CONTRIBUTING.md در مخزن گیت‌هاب مراجعه کنید.

قبلی
دستیار توسعه‌دهنده API گوگل ادز چیست؟