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

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

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

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

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

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

  2. البرامج:

    • Python 3.10 أو إصدار أحدث مثبَّت على نظامك PATH. تُستخدَم 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"

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

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

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

    • "ما هي أنواع الحملات المتاحة؟"
    • "كيف يمكنني الفلترة حسب التاريخ في 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
    • لغة طبيعية: "أريد إنشاء فلاتر استبعاد صفحات الويب في حملة الأداء الأفضل"

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

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

إلغاء التثبيت

لإلغاء تثبيت المكوّن الإضافي لـ "مساعد Google"، اتّبِع الخطوات التالية:

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؟