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

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

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

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

  2. البرامج:

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

  3. المستودع:

البدء

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

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

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

    ./install.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، وسيتم تنفيذ النص البرمجي في سياق &quot;مساعد Google&quot; إذا كانت لغتك التلقائية هي Python أو Ruby أو PHP. لن يتم تشغيل لغات البرمجة المجمَّعة بسبب السياسات الأمنية.

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

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

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

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

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

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

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

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

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