نصب و استفاده از «دستیار توسعه‌دهنده Google Ads API»

«دستیار توسعه‌دهنده Google Ads API» تخصص عمیق در دامنه Google Ads API را مستقیماً به محیط کدنویسی هوش مصنوعی شما می‌آورد. از پیام‌واره‌های زبان طبیعی و فرمان‌های خط مورب داخلی برای ساختن پُرسمان، تولید کد کتابخانه مشتری، اجرای تماس‌های API فقط خواندنی، جاری‌سازی گزارش‌های موردی، و عیب‌یابی ادغام‌ها استفاده کنید.

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

پیش‌نیازها

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

  1. دسترسی به Google Ads API:

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

    • ‫Python نسخه ۳.۱۰ یا جدیدتر نصب شده باشد و در سیستم PATH شما باشد. از Python برای اجرای کد تولیدشده و اجرای سایدکارهای اعتبارسنجی محلی استفاده می‌شود.
    • پلاتفرم عامل میزبان:
    • Git در PATH سیستم شما نصب شده باشد.

شروع کنید

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

۱. همسانه‌سازی مخزن

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

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

۲. اجرای دستورگان نصب

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

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

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

مطمئن شوید فایل پیکربندی میانای برنامه‌سازی کاربردی (برای مثال، 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 را بازراه‌اندازی کنید تا افزونه بار شود.
  • کد Claude: در جلسه فعال «کد Claude»، /reload-plugins را اجرا کنید یا claude را بازراه‌اندازی کنید.

۵. تعامل با «دستیار»

می‌توانید بااستفاده از پیام‌واره‌های زبان طبیعی یا فرمان‌های اختصاصی خط مورب مستقیماً در پایانه با «دستیار» تعامل داشته باشید.

ویژگی‌های مهم

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

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

  • تولید کد کتابخانه مشتری مستدل: کد اصطلاحی آزمایش‌شده را بااستفاده از کتابخانه‌های مشتری رسمی Google Ads (Python،‏ Java،‏ PHP،‏ NET.، و Ruby) تولید کنید.

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

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

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

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

    • کد Claude: /inspect-object <resource_or_enum>
    • زبان طبیعی: «بازرسی منبع پویش»

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

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

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

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

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

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

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

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

  • فیلترها و مستثنی کردن‌های فهرستگان «عملکرد بیشینه»: درخت‌های بخش محصول و مستثنی کردن‌های نشانی وب صفحه وب را برای گروه‌های دارایی تولید کنید.

    • کد Claude: /pmax-filter
    • زبان طبیعی: «فیلترهای کنارگذاری صفحه وب برای پویش PMax من بساز»

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

    • 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

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

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

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

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

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

حذف نصب

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

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"

سپس جلسه میزبان «ضدجاذبه» را بازراه‌اندازی کنید.

Claude Code

در جلسه فعال Claude Code:

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

یا از پایانه:

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

(اختیاری) ثبت بازار محلی را بردارید:

claude plugin marketplace remove google-ads-assistant-local

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

رهنمودهای همیاری

از همیاری‌ها استقبال می‌شود! برای رهنمودها، فایل CONTRIBUTING.md را در مخزن GitHub ببینید.

قبلی
«دستیار توسعه‌دهنده Google Ads API» چیست؟