تثبيت "أداة مساعدة المطوّرين في Google Ads API" واستخدامها

يوفّر "مساعد المطوّرين" في Google Ads API خبرة عميقة في مجال Google Ads API مباشرةً في بيئة الترميز المستندة إلى الذكاء الاصطناعي. استخدِم طلبات بلغة طبيعية وأوامر مدمجة تبدأ بشرطة مائلة لإنشاء طلبات بحث، وإنشاء رموز مكتبة برامج العميل، وتنفيذ طلبات بيانات من واجهة برمجة التطبيقات للقراءة فقط، وبث تقارير مخصّصة، وتحديد المشاكل في عمليات الدمج وحلّها.

تم تصميم Assistant لإطارَي عمل الوكيلَين Google Antigravity وClaude Code (الإصدار 4.0.0) كمكوّن إضافي معياري. ويستخدم عقود AGENTS.md وCLAUDE.md، وأوامر تبدأ بشرطة مائلة مدمجة، ومهارات متخصّصة في المجال للحفاظ على سياق مستمر، وحدود أمان قوية، ومسارات تحقّق مبرمَجة.

المتطلبات الأساسية

قبل البدء، تأكَّد من توفّر ما يلي:

  1. الوصول إلى Google Ads API:

  2. البرامج:

    • تثبيت الإصدار 3.10 أو إصدار أحدث من Python على جهازك وإضافته إلى مسار النظام يتم استخدام Python لتنفيذ الرموز البرمجية التي تم إنشاؤها وتشغيل أدوات التحقّق المحلية.
    • منصة وكلاء Google:
    • تثبيت Git في مسار النظام

البدء

اتّبِع الخطوات التالية لنسخ المستودع وتشغيل نص التثبيت البرمجي الخاص بالنظام الأساسي وضبط بيانات الاعتماد وتفعيل المكوّن الإضافي.

1. إنشاء نسخة طبق الأصل من المستودع

استنسِخ المستودع إلى جهازك المحلي وانتقِل إلى دليل المشروع:

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

2. تشغيل نص التثبيت البرمجي

شغِّل نص التثبيت البرمجي للمنصة المستهدفة. يتم تضمين مكتبة برامج 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

3- ضبط بيانات الاعتماد

تأكَّد من وضع ملف إعداد واجهة برمجة التطبيقات (على سبيل المثال، google-ads.yaml أو google_ads_php.ini أو google_ads_config.rb) في دليل $HOME.

(اختياري) لضبط رقم تعريف عميل تلقائي، أدخِل رقم تعريف العميل مباشرةً في config/customer_id.txt (على سبيل المثال، 1234567890). يمكنك أيضًا فحص إصدار واجهة برمجة التطبيقات النشط أو تثبيته في config/api_version.txt.

4. تفعيل المكوّن الإضافي

  • Antigravity: أعِد تشغيل جلسة Antigravity أو agy المضيف لتحميل المكوّن الإضافي.
  • ‫Claude Code: في جلسة Claude Code نشطة، شغِّل /reload-plugins أو أعِد تشغيل claude.

5- التفاعل مع "مساعد Google"

يمكنك التفاعل مع "المساعد" باستخدام طلبات باللغة الطبيعية أو أوامر تبدأ بشرطة مائلة مباشرةً في نافذة Terminal.

الميزات الأساسية

  • الأسئلة والأجوبة باللغة الطبيعية والإرشادات المفاهيمية: يمكنك طرح أسئلة حول ميزات Google Ads API أو قواعد البنية أو أفضل الممارسات أو مراجع محدّدة. يستند "مساعد Google" في ردوده إلى تعريفات واجهة برمجة التطبيقات الرسمية بدلاً من الاعتماد فقط على التدريب العام للنماذج اللغوية الكبيرة.

    • "ما هي أنواع الحملات المتاحة؟"
    • "كيف يمكنني الفلترة حسب التاريخ في GAQL؟"
    • "اشرح الفرق بين click_view وimpression_view".
    • "ما هي المجموعة المشتركة وكيف يمكنني استخدامها؟"
    • أوامر Claude Code التي تبدأ بشرطة مائلة: /explain و/step-by-step و/assistant-tutorial

  • إنشاء رمز مكتبة برامج مستند إلى المصادر: يمكنك إنشاء رمز اصطلاحي تم اختباره باستخدام مكتبات برامج "إعلانات Google" الرسمية (Python وJava وPHP و‎.NET وRuby).

    • "اعرِض لي الحملات التي حقّقت أكبر عدد من الإحالات الناجحة في آخر 30 يومًا".
    • "الحصول على جميع أسماء المجموعات الإعلانية المفعّلة للعميل 123-456-7890"
    • "اكتب رمزًا برمجيًا لإنشاء حملة أداء أفضل". يتم حفظ الرمز الذي تم إنشاؤه في دليل saved/code/.

  • التحقّق من صحة طلبات البحث الآلية في GAQL: يمكنك إجراء اختبارات تجريبية والتحقّق من صحة طلبات البحث المعقّدة تلقائيًا مقارنةً بالبيانات الوصفية لواجهة برمجة التطبيقات وتوافق الحقول وقواعد عدم تسجيل أي مرّات ظهور وتقسيم التاريخ قبل التنفيذ.

    • ‫Claude Code: /validate-gaql
    • اللغة الطبيعية: validate: SELECT campaign.id FROM campaign

  • فحص مخططات العناصر وProtobuf: يمكنك فحص هياكل الموارد والحقول المتداخلة وأنواع البيانات وقيم التعداد ديناميكيًا لأي إصدار نشط من واجهة برمجة التطبيقات بدون الحاجة إلى تحميل بيانات وصفية عن بُعد.

    • ‫Claude Code: /inspect-object <resource_or_enum>
    • اللغة الطبيعية: "فحص مصدر الحملة"

  • إعداد تقارير مباشرة مخصّصة وتصدير ملفات CSV: يمكنك طلب بيانات الأداء بلغة إنجليزية بسيطة. ينشئ "مساعد Google" طلبات بحث GAQL ويتحقّق من صحتها وينفّذها مباشرةً في حسابك، مع بث جداول منسَّقة مباشرةً إلى نافذة الأوامر.

    • "عرض أهم 5 كلمات رئيسية حسب التكلفة في الشهر الماضي للعميل 123-456-7890"
    • "احفظ النتائج كملف CSV". (يتم تصدير البيانات إلى saved/csv/).

  • تنفيذ واجهة برمجة التطبيقات مباشرةً وأمان التعديل: يمكنك تنفيذ نصوص برمجية للقراءة فقط يتم إنشاؤها مباشرةً ضمن بيئة افتراضية مُدارة.

    • اطلب من "مساعد Google" "تشغيل الرمز" أو "تنفيذ النص البرمجي".
    • أمان التعديل: لأسباب تتعلّق بالأمان، يتم إنشاء عمليات التعديل (إنشاء وتعديل وحذف) في saved/code/، ولكن لا يتم تنفيذها مباشرةً من قِبل "المساعد". مراجعتها وتنفيذها يدويًا خارج نطاق المساعد

  • بيانات التشخيص المتقدّمة وتحديد المشاكل وحلّها في ما يتعلّق بالإحالات الناجحة: يمكنك التحقيق في حالات تعذُّر تحميل الإحالات الناجحة غير الإلكترونية، والتحقّق مسبقًا من ملفات التحميل، وإنشاء تقارير تشخيصية مفصّلة.

    • ‫Claude Code: /troubleshoot-conversions
    • لغة طبيعية: "تحديد المشاكل وحلّها في الإحالات الناجحة للعميل ‎123-456-7890" (يتم حفظ التقارير في saved/data/).

  • ربط التسلسل الهرمي للحساب الإداري: استرداد أرقام تعريف العملاء للحسابات الفرعية وربط التسلسلات الهرمية للحسابات ضمن حساب إداري

    • ‫Claude Code: /get-cids <manager_cid>
    • اللغة الطبيعية: "الحصول على جميع معرّفات العملاء في حسابات العملاء ضِمن حساب المدير 123-456-7890"

  • فلاتر واستبعادات بيانات "حملات الأداء الأفضل": يمكنك إنشاء تدرّجات هرمية لتقسيم المنتجات واستبعادات عناوين URL لصفحات الويب لمجموعات مواد العرض.

    • ‫Claude Code: /pmax-filter
    • لغة طبيعية: "أريد إنشاء فلاتر استبعاد صفحات الويب في حملة الأداء الأفضل"

  • سياق إضافي لقاعدة الرموز: يمكنك تسجيل منطق تطبيقك وبنيته المخصّصة في عملية الاستدلال التي يجريها "مساعد Google".

    • ‫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

عند استخدام 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 يقدّم شرحًا منظّمًا من 4 أجزاء. /explain shared set
/step-by-step يضع خطة تنفيذ مهام متعددة المراحل. /step-by-step upload conversions
/assistant-tutorial يتم تشغيل جولة تفاعلية من 11 خطوة. /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

أو من خلال Terminal:

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؟