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

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