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

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

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

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

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

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

  2. البرامج:

    • تثبيت الإصدار 3.10 أو إصدار أحدث من Python على جهازك وإضافته إلى مسار النظام يتم استخدام Python لتنفيذ الرموز البرمجية التي تم إنشاؤها وتشغيل أدوات التحقّق المحلية.
    • منصة وكيل المضيف:
    • يجب أن يكون 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: /validate-gaql
    • اللغة الطبيعية: validate: SELECT campaign.id FROM campaign

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

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

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

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

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

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

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

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

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

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

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

    • رمز Claude: /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؟