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

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

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

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

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

ضبط الإعدادات من خلال 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)

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

عند تشغيل نصوص برمجية نموذجية مثل 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 تتضمّن منطقًا مخصّصًا. يمكنك الاطّلاع على دليل التسجيل لمزيد من التفاصيل ومثال على أداة اعتراض تسجيل مخصّصة.