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

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

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

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

• إعداد مكتبة العميل: استخدِم خيارات الإعداد الخاصة بالمكتبة في ملف google-ads.yaml أو متغيّرات البيئة.
• برمجيًا باستخدام Python: استخدِم إطار عمل logging المضمّن في Python للتحكّم المباشر.

تنبيه: يؤدي ضبط مستوى السجلّ على DEBUG إلى تسجيل حمولات طلبات بيانات من واجهة برمجة التطبيقات واستجاباتها الكاملة، والتي قد تحتوي على معلومات حساب حساسة أو بيانات شخصية. لا تترك تسجيل DEBUG مفعّلاً في بيئات الإنتاج.

ضبط الإعدادات من خلال google-ads.yaml

يتم ضبط عملية التسجيل تلقائيًا عند تهيئة مثيل GoogleAdsClient (على سبيل المثال، عند استدعاء load_from_storage). وعند التهيئة، تقوم المكتبة بما يلي:

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

على سبيل المثال، يمكنك إضافة قسم logging إلى ملف google-ads.yaml:

logging:
  version: 1
  disable_existing_loggers: false
  formatters:
    default_fmt:
      format: '[%(asctime)s - %(levelname)s] %(message).5000s'
      datefmt: '%Y-%m-%d %H:%M:%S'
  handlers:
    default_handler:
      class: logging.StreamHandler
      formatter: default_fmt
  loggers:
    '':
      handlers: [default_handler]
      level: INFO

الإعداد آليًا

عند استخدام المكتبة كحزمة مثبَّتة بدون قسم logging في ملف الإعدادات، يمكنك دمج تسجيل الدخول مع برنامج إعداد تسجيل الدخول في تطبيقك آليًا. أرفِق معالج تسجيل بمثيل مسجّل المكتبة (google.ads.googleads.client) باستخدام addHandler واضبط مستوى التسجيل المستهدَف:

import logging
import sys

# Retrieve the library's logger instance.
logger = logging.getLogger("google.ads.googleads.client")

# Direct logs to standard output (stdout).
logger.addHandler(logging.StreamHandler(sys.stdout))

# Set the log level to DEBUG to view detailed messages.
logger.setLevel(logging.DEBUG)

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

import logging
import sys

logger = logging.getLogger("google.ads.googleads.client")
logger.addHandler(logging.StreamHandler(sys.stderr))
logger.setLevel(logging.WARNING)

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

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

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

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

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

يمكنك كتابة السجلات في ملف إما بشكل آلي في Python أو عن طريق إعادة توجيه الإخراج من سطر الأوامر.

تسجيل الدخول إلى ملف في Python

لكتابة السجلات مباشرةً في ملف من Python، أرفِق logging.FileHandler بمسجّل العميل:

import logging

logger = logging.getLogger("google.ads.googleads.client")
file_handler = logging.FileHandler("google_ads.log")
logger.addHandler(file_handler)
logger.setLevel(logging.INFO)

إعادة توجيه الإخراج باستخدام shell

عند تشغيل نصوص برمجية نموذجية مثل get_campaigns.py من سطر الأوامر، يمكنك إعادة توجيه ناتج سجلّ وحدة التحكّم إلى ملف باستخدام واجهة سطر الأوامر لنظام التشغيل.

لحفظ الناتج القياسي في ملف (مع الكتابة فوق أي ملف حالي):

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

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

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

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

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

أو على Bash 4 والإصدارات الأحدث:

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

أدوات اعتراض gRPC المخصّصة

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