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

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