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

‫Google Ads API Developer Assistant هي إضافة فعّالة لـ Gemini CLI مصمَّمة لتسريع سير عملك في Google Ads API. يتيح لك "المساعد" التفاعل مع Google Ads API باستخدام اللغة الطبيعية، ما يسهّل عليك طرح الأسئلة وإنشاء الرموز البرمجية واسترداد البيانات وتحديد المشاكل وحلّها مباشرةً من داخل نافذة الأوامر.

المزايا

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

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

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

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

  2. البرامج:

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

  3. المستودع:

    • نسخة محلية من مستودع google-ads-api-developer-assistant من GitHub:

البدء

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

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

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

    ./setup.sh

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

  3. ابدأ استخدام Gemini CLI:

    gemini

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

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

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

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

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

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

  • تنفيذ واجهة برمجة التطبيقات مباشرةً: يمكنك تشغيل نصوص Python البرمجية للقراءة فقط التي تم إنشاؤها مباشرةً من Gemini CLI وعرض النتائج المنسَّقة في نافذة الأوامر. بعد أن ينشئ &quot;مساعد Google&quot; الرمز، ستتلقّى طلبًا على الشاشة:

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، وسيتم تنفيذ النص البرمجي في سياق "مساعد Google".

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

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

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

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

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

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

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

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

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