فعال‌سازی گزارش‌گیری

این کتابخانه گزارش‌گیری همه‌کاره‌ای برای تعاملات Google Ads API ارائه می‌دهد. می‌توانید این موارد را ضبط کنید:

  • اطلاعات دقیق: درخواست‌های کامل ارسال‌شده به API و پاسخ‌های دریافتی.
  • خلاصه‌های مختصر: نمای کلی سطح بالا از تعامل‌های API.

می‌توانید این تنظیمات گزارش‌گیری را به دو روش کنترل کنید:

  • پیکربندی کتابخانه کارخواه: از گزینه‌های پیکربندی ویژه کتابخانه در فایل google-ads.yaml یا متغیرهای محیطی استفاده کنید.
  • به‌صورت برنامه‌نویسی با Python: از چارچوب داخلی logging Python برای کنترل مستقیم استفاده کنید.
ثبت گزارش 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 در فایل پیکربندی‌تان استفاده می‌کنید، می‌توانید ثبت گزارش آن را به‌صورت برنامه‌نویسی‌شده با راه‌اندازی ثبت گزارش برنامه‌تان ادغام کنید. بااستفاده از addHandler، یک مدیریت‌کننده گزارش‌گیری به نمونه گزارش‌گیر کتابخانه (google.ads.googleads.client) پیوست کنید و سطح گزارش هدف را تنظیم کنید:

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 با منطق سفارشی، ثبت سفارشی خودتان را راه‌اندازی کنید. برای جزئیات بیشتر و نمونه‌ای از میان‌گیر ثبت گزارش سفارشی، به راهنمای ثبت گزارش مراجعه کنید.