تثبيت "أداة مساعدة المطوّرين في 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 على مسار النظام PATH

البدء

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

‫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: ```bash ./install.sh agy

أو تضمين مكتبات برامج إضافية للعملاء:

./install.sh agy --java --dotnet ```

نظام التشغيل Windows (PowerShell): ```powershell .\install.ps1 -Type agy

أو تضمين مكتبات برامج إضافية للعملاء:

.\install.ps1 -Type agy -Java -Dotnet ```

Claude Code

نظام التشغيل Linux أو macOS: ```bash ./install.sh claude

أو تضمين مكتبات برامج إضافية للعملاء:

./install.sh claude --php --dotnet ```

‫Windows (PowerShell): ```powershell .\install.ps1 -Type claude

أو تضمين مكتبات برامج إضافية للعملاء:

‎.\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 أو أفضل الممارسات أو مراجع معيّنة.

  • أسئلة وأجوبة باللغة الطبيعية وإرشادات مفاهيمية: يمكنك طرح أسئلة حول ميزات Google Ads API أو قواعد التصميم أو موارد محدّدة. يستند "مساعد Google" في ردوده إلى تعريفات 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: يمكنك طلب بيانات الأداء باللغة الإنجليزية العادية. ينشئ &quot;مساعد GAQL&quot; طلبات بحث GAQL ويتحقّق من صحتها وينفّذها مباشرةً في حسابك، ويبث جداول منسَّقة مباشرةً إلى نافذة الأوامر.

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

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

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

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

    • 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: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • Windows (PowerShell): 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: bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Claude Code

نظام التشغيل Linux أو macOS: bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

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

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

Antigravity

نظام التشغيل Linux أو macOS: bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell): powershell Remove-Item -Recurse -Force "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

بعد ذلك، أعِد تشغيل جلسة الاستضافة في Antigravity.

Claude Code

في جلسة نشطة من Claude Code: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

أو من نافذة "الوحدة الطرفية": bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(اختياري) أزِل سجلّ السوق المحلي: bash claude plugin marketplace remove google-ads-assistant-local

المنتدى والدعم

إرشادات المساهمة

نرحّب بمساهماتك. اطّلِع على ملف CONTRIBUTING.md في مستودع GitHub للاطّلاع على الإرشادات.

السابق
ما هي أداة "مساعد المطوّر" في Google Ads API؟