تفعيل التسجيل

توفّر المكتبة تسجيلًا متعدد الاستخدامات للتفاعلات مع Google Ads API. يمكنك تسجيل ما يلي:

• معلومات تفصيلية: الطلبات الكاملة المُرسَلة إلى واجهة برمجة التطبيقات والردود التي تم تلقّيها
• ملخّصات موجزة: نظرة عامة شاملة على التفاعلات

ويمكنك التحكّم في إعدادات التسجيل هذه بطريقتَين:

• إعدادات مكتبة البرامج: استخدِم خيارات الإعدادات الخاصة بالمكتبة.
• برمجيًا باستخدام Python: استخدِم إطار عمل تسجيل البيانات المضمّن في Python للتحكّم بشكل مباشر أكثر.

يتم ضبط إعدادات التسجيل تلقائيًا عند تهيئة مثيل GoogleAdsClient. تحدث خطوة الإعداد هذه، على سبيل المثال، عند استخدام طريقة load_from_storage. في هذه المرحلة، ستنفّذ المكتبة ما يلي:

• قراءة إعدادات التسجيل المحدّدة من الإعداد
• مرِّر هذه الإعدادات إلى الدالة المضمّنة في Python logging.config.dictConfig لتفعيلها.

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

import logging

logger = logging.getLogger('google.ads.googleads.client')

بعد استرداد أداة تسجيل الأحداث في المكتبة، يمكنك تحديد المكان الذي تريد عرض رسائل السجلّ فيه.

• إرسال السجلات إلى وحدة التحكّم: لعرض رسائل السجلّ على وحدة التحكّم، عليك إضافة معالج أساسي. في ما يلي كيفية توجيه السجلات إلى الناتج العادي (stdout):

  في ما يلي كيفية ضبط معالج أساسي يطلب من أداة تسجيل الأحداث الطباعة إلى stdout:

  import sys
  
  # Assuming 'logger' was retrieved as per previous instructions
  logger.addHandler(logging.StreamHandler(sys.stdout))
  

  إذا كنت تفضّل إرسال السجلات إلى الخطأ المعياري (stderr)، والذي يُستخدم غالبًا لرسائل الخطأ والتحذيرات:

  import sys
  
  # Assuming 'logger' was retrieved as per previous instructions
  logger.addHandler(logging.StreamHandler(sys.stderr))
  

• ضبط إعدادات التسجيل الأخرى آليًا: بعد الحصول على عنصر المسجّل، يمكنك أيضًا تغيير إعدادات التسجيل الأخرى آليًا باستخدام وحدة التسجيل المضمّنة في Python. على سبيل المثال، لتغيير مستوى التسجيل إلى DEBUG (الذي سيعرض رسائل أكثر تفصيلاً):

  logger.setLevel(logging.DEBUG)
  

مستويات السجلّ

ينشئ العميل سجلّات على مستويات مختلفة، ويمكنك ضبط الإعدادات لعرض بعض أو كل ما يلي:

المستوى	طلب ناجح	تعذّر تنفيذ الطلب
DEBUG	سجلّ تفصيلي يتضمّن عناصر الطلب والاستجابة الكاملة بتنسيق JSON	سجلّ تفصيلي يتضمّن طلبات كاملة وكائنات استثناء بتنسيق JSON
INFO	ملخّص موجز يتضمّن حقول الطلب والاستجابة المحدّدة	سجلّ تفصيلي يتضمّن طلبات كاملة وكائنات استثناء بتنسيق JSON
WARNING	بدون	ملخّص موجز يتضمّن معلومات الطلب المحدّد وحالة الاستثناء ورسالته

بما أنّ إطار تسجيل البيانات في Python يتجاهل رسائل السجلّ الأقل خطورة من المستوى الذي تم ضبطه، يعني الضبط على WARNING أنّك سترى فقط رسائل موجزة تتعلّق بالطلبات التي تعذّر تنفيذها، ولكن الضبط على DEBUG يعني أنّك سترى جميع أنواع السجلّات الممكنة في الجدول أعلاه.

تسجيل البيانات في ملف

عند تشغيل نصوص برمجية نموذجية مثل get_campaigns.py من سطر الأوامر، يمكن إعادة توجيه أي رسائل سجلّ يتم عرضها عادةً في وحدة التحكّم (أو "نقلها") إلى ملف. هذه ميزة في واجهة سطر الأوامر لنظام التشغيل، وليست في مكتبة Python نفسها. يُرجى اتّباع الخطوات التالية:

لحفظ الناتج العادي (معظم السجلات) في ملف (مع استبداله):

python get_campaigns.py -c $CLIENT_ID > campaign_logs.txt

لإلحاق الإخراج العادي بملف، اتّبِع الخطوات التالية:

python get_campaigns.py -c $CLIENT_ID >> campaign_logs.txt

لحفظ كلّ من الإخراج العادي والخطأ العادي (للأخطاء/التحذيرات) في الملف نفسه، اتّبِع الخطوات التالية:

python get_campaigns.py -c $CLIENT_ID > all_logs.txt 2>&1

(أو في بعض الأصداف الحديثة، مثل Bash 4+):

python get_campaigns.py -c $CLIENT_ID &> all_logs.txt

أدوات اعتراض التسجيل

تستخدم مكتبة عميل Python معترِضات gRPC للوصول إلى تفاصيل الطلبات والردود وتسجيلها. يمكنك إعداد تسجيل مخصّص من خلال إنشاء أداة اعتراض gRPC تتضمّن منطقًا مخصّصًا. راجِع دليل تسجيل البيانات لمعرفة المزيد من التفاصيل ومثال على أداة اعتراض مخصّصة لتسجيل البيانات.