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

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

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

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

    • رمز مميّز للمطوّر من Google Ads API.
    • ملف إعداد Google Ads تم ضبطه باستخدام الرمز المميّز للمطوّر وبيانات اعتماد OAuth 2.0 ورقم تعريف العميل ، ويقع في دليل المستخدم الرئيسي راجِع دليل إعداد مكتبة العملاء.
    • الإلمام بمفاهيم Google Ads API والمصادقة

  2. البرامج:

    • Python 3.10 أو إصدار أحدث ‫Python هي اللغة التلقائية، لذا يجب أن تكون مثبَّتة ومتاحة في مسار النظام.
    • أداة سطر الأوامر Google Antigravity مثبَّتة
    • jq (معالج JSON لسطر الأوامر) سيحاول النص البرمجي للتثبيت تثبيت هذا المعالج إذا لم يكن مثبَّتًا.

  3. المستودع:

البدء

  1. الانتقال إلى دليل المشروع:

    cd <full path>/google-ads-api-developer-assistant

    (ملاحظة: إذا كانت ميزة دمج واجهة Antigravity مع سطر الأوامر مفعّلة، سيؤدي الدخول إلى هذا الدليل إلى تهيئة جلسة "مساعد المطوّر" تلقائيًا).

  2. تشغيل النص البرمجي للتثبيت: يُهيّئ هذا النص البرمجي بيئة التطوير ويستنسِخ مكتبات عملاء Google Ads المطلوبة (يتم تثبيت Python تلقائيًا).

    ./install.sh

    إذا كنت تستخدم نظام التشغيل Windows، شغِّل نص PowerShell البرمجي install.ps1.

  3. ضبط بيانات الاعتماد: تأكَّد من وضع ملف google-ads.yaml (أو الملف المكافئ بلغة أخرى) في دليل المستخدم الرئيسي.

  4. التفاعل مع "مساعد المطوّر": بعد تفعيل الجلسة، يمكنك التفاعل مع "مساعد المطوّر" باستخدام اللغة الطبيعية مباشرةً في سطر الأوامر.

الميزات الرئيسية

  • الأسئلة والأجوبة باللغة الطبيعية: اطرح أسئلة حول ميزات Google Ads API أو أفضل الممارسات أو موارد معيّنة.

    • "ما هي أنواع الحملات المتاحة؟"
    • "كيف يمكنني الفلترة حسب التاريخ في GAQL؟"
    • "اشرح الفرق بين click_view وimpression_view."

  • إنشاء الرموز البرمجية: يمكنك إنشاء طلبات بحث GAQL ومقاطع رموز Python البرمجية القابلة للتنفيذ.

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

  • تنفيذ واجهة برمجة التطبيقات مباشرةً: يمكنك تشغيل نصوص Python البرمجية للقراءة فقط التي تم إنشاؤها مباشرةً ضمن بيئة افتراضية معزولة (.venv) وعرض النتائج المنسّقة كجداول في سطر الأوامر.

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

  • تصدير إلى ملف CSV: يمكنك حفظ النتائج الجدولية من طلبات واجهة برمجة التطبيقات في ملف CSV.

    • "احفظ النتائج في ملف CSV." يتم حفظ الملفات في الدليل saved/csv/.

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

    • "لماذا لا تظهر لي أي نتائج لطلبي؟"
    • "حدِّد مشاكل إحالاتي الناجحة للعميل 123-456-7890 وحلّها." (يؤدي هذا إلى إنشاء تقرير تشخيص مفصّل في saved/data/).

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

    • استخدِم النص البرمجي update.sh مع الخيار --context_path لتسجيل ملفات مشروعك: none ./update.sh --context_path /path/to/your/codebase
    • يسمح هذا الإجراء لـ "مساعد المطوّر" بتضمين منطق تطبيقك في عملية الاستنتاج عند إنشاء الردود أو إنشاء الرموز البرمجية باللغة المفضّلة لديك.

أمثلة على حالات الاستخدام

  • إعداد التقارير:
    • "احصل على أهم 5 كلمات رئيسية حسب التكلفة للشهر الماضي للعميل 12345678."
  • بنية الحساب:
    • "اعرِض جميع أسماء الحملات وأرقام تعريفها."
  • تحديد المشاكل وحلّها:
    • "حمّلتُ 100 إحالة ناجحة، ولكن لا يظهر في واجهة المستخدم سوى 78 إحالة ناجحة. كيف يمكنني تحديد المشاكل وحلّها باستخدام واجهة برمجة التطبيقات؟"
  • قيد التعلّم:
    • "/اشرح ما هي المجموعة المشترَكة"
  • إنشاء الرموز البرمجية:
    • "اكتب رمزًا برمجيًا لإنشاء "حملة أداء أفضل" لـ company name."

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

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

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

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