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

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

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

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

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

  2. البرامج:

  3. المستودع:

البدء

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

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

  2. تشغيل نص الإعداد: يضبط هذا النص gemini-cli لاستخدام ملفات السياق GEMINI.md الخاصة بالمساعد والأدوات اللازمة.

    ./install.sh

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

  3. بدء gemini-cli:

    gemini

  4. التفاعل مع "المساعد": يمكنك الآن طرح الأسئلة أو تقديم الأوامر باللغة الطبيعية.

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

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

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

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

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

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

To run this script, you will need to replace YOUR_CUSTOMER_ID with your actual
Google Ads customer ID and execute the following command in
your shell: <command>

أدخِل run، وسيتم تنفيذ النص البرمجي في سياق "المساعد" إذا كانت لغتك التلقائية هي Python أو Ruby أو PHP. لن يتم تشغيل اللغات المجمَّعة بسبب السياسات الأمنية.

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

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

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

    • "ظهر لي الخطأ 'AuthenticationError.OAUTH_TOKEN_INVALID'، ماذا أفعل؟"
    • "لماذا لا تظهر لي أي نتائج لطلبي؟"

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

    • اعتبارًا من الإصدار 2.3.0، استخدِم العلامة context_dir لتضمين ملفات مشروعك: ./update.sh --context_dir /path/to/your/codebase يتيح ذلك لـ "المساعد" تضمين منطق تطبيقك في عملية الاستنتاج عند إنشاء الردود.
    • تتيح هذه الميزة لـ "المساعد" إنشاء أمثلة للرموز المحفوظة باللغة التي تختارها، ما يوفّر الدعم حتى عندما لا تتوفّر مكتبة برامج رسمية.
    • قبل طلب عرض الرمز، أخبِر "المساعد": write saved code examples in <language of your application>

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

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

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

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

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

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