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

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

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

پیش‌نیازها

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

  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، قوانین معماری، روال‌های مطلوب، یا منابع خاص سؤال بپرسید. «دستیار» پاسخ‌ها را براساس تعاریف رسمی میانای برنامه‌سازی کاربردی ارائه می‌دهد و صرفاً به آموزش عمومی مدل زبانی بزرگ متکی نیست.

    • «انواع پویش‌های دردسترس چیست؟»
    • «چگونه در 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>
    • زبان طبیعی: «Inspect campaign resource»

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

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

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

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

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

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

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

    • کد Claude: /get-cids <manager_cid>
    • زبان طبیعی: «Get all client customer IDs under manager 123-456-7890»

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

    • کد 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"

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

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» چیست؟