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

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

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

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

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

  1. إمكانية الوصول إلى Google Ads API:

    • رمز مميّز للمطوّرين في Google Ads API.
    • ملف إعدادات "إعلانات Google" تم ضبطه باستخدام الرمز المميّز للمطوّر وبيانات اعتماد OAuth 2.0 ورقم تعريف العميل، ويقع في دليل المستخدم الرئيسي (على سبيل المثال، google-ads.yaml في Python) راجِع دليل إعداد مكتبة العميل .
    • الإلمام بمفاهيم Google Ads API والمصادقة

  2. البرامج:

    • Python الإصدار 3.10 أو الإصدارات الأحدث مثبّتة ومدرَجة في PATH على نظامك. يتم استخدام 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 Ads API أو قواعد البنية الأساسية أو موارد معيّنة. يستند "مساعد المطوّرين" في ردوده إلى تعريفات واجهة برمجة التطبيقات الرسمية بدلاً من الاعتماد فقط على التدريب العام للنماذج اللغوية الكبيرة.

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

  • إنشاء رمز مكتبة العميل المستند إلى البيانات: يمكنك إنشاء رمز تم اختباره ومناسبًا للغة باستخدام مكتبات عملاء Google Ads الرسمية (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>
    • اللغة الطبيعية: "Inspect campaign resource"

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

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

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

    • ما عليك سوى إخبار "مساعد المطوّرين": "Run the code" أو "Execute the script".
    • الحفاظ على أمان عمليات التعديل: للحفاظ على الأمان، يتم إنشاء عمليات التعديل (الإنشاء والتعديل والحذف) في saved/code/، ولكن لا ينفّذها "مساعد المطوّرين" مباشرةً أبدًا. عليك مراجعتها وتنفيذها يدويًا خارج "مساعد المطوّرين".

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

    • Claude Code: /troubleshoot-conversions
    • اللغة الطبيعية: " Troubleshoot conversions for customer 123-456-7890." (يتم حفظ التقارير في saved/data/).

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

    • Claude Code: /get-cids <manager_cid>
    • اللغة الطبيعية: "Get all client customer IDs under manager 123-456-7890"

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

    • Claude Code: /pmax-filter
    • اللغة الطبيعية: "Create webpage exclusion filters for my PMax campaign"

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

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