پیکربندی

می‌توانید کتابخانه کارخواه Python را بااستفاده از فایل YAML، متغیرهای محیطی، رشته YAML، یا dict پیکربندی کنید.

پیکربندی اصالت‌سنجی

روش‌های متعددی برای مدیریت اطلاعات اعتباری OAuth موردنیاز برای دسترسی به Google Ads API وجود دارد. رویکردی که انتخاب می‌کنید بر فیلدهای پیکربندی‌ای که استفاده می‌کنید تأثیر می‌گذارد. برای اطلاعات بیشتر، راهنمای اصالت‌سنجی را ببینید.

پیکربندی بااستفاده از فایل YAML

می‌توانید فایل YAML را برای استفاده هنگام مقداردهی اولیه کارخواه مشخص کنید که حاوی اطلاعات لازم برای درخواست دادن به Google Ads API است. وقتی کارخواه بااستفاده از روش load_from_storage مقداردهی اولیه می‌شود، به این فایل دسترسی پیدا می‌شود. ساده‌ترین راه برای تولید این فایل، کپی کردن نمونه google-ads.yaml از مخزن GitHub و اصلاح آن برای گنجاندن اطلاعات کاربری شما، ازجمله ژتون بازآوری، شناسه کارخواه، و رمز کارخواه است.

اگر مسیری ارائه نکنید، کتابخانه در فهرست $HOME شما به‌دنبال فایل می‌گردد:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

برای مشخص کردن مکانی که فایل google-ads.yaml در آن قرار دارد، می‌توانید مسیر را به‌عنوان رشته‌ای به روش هنگام فراخوانی آن ارسال کنید:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

همچنین می‌توانید با تعریف متغیر محیطی خاصی، مسیر را مشخص کنید:

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

اگر هر دو مقدار ارائه شده باشد (مسیری به روش ارسال شده باشد و متغیر محیطی وجود داشته باشد)، کتابخانه مسیری را که به روش ارسال شده است در اولویت قرار می‌دهد.

پیکربندی بااستفاده از متغیرهای محیطی

می‌توانید همه پیکربندی کارخواه خود را به‌عنوان متغیرهای محیطی ذخیره کنید، که هنگام استفاده از روش load_from_env کارخواه خوانده می‌شوند. متغیرهای محیطی باید نامی مشابه با متغیرهای تعریف‌شده در فایل google-ads.yaml داشته باشند، اما باید کاملاً با حروف بزرگ باشند و پیشوند فضای نام GOOGLE_ADS_ داشته باشند. برای مثال، client_id باید به‌صورت GOOGLE_ADS_CLIENT_ID ذخیره شود.

متغیرهای محیطی معمولاً در فایل پیکربندی bash تعریف می‌شوند، مثل فایل .bashrc یا .bash_profile که در دایرکتوری $HOME قرار دارد. همچنین می‌توان آن‌ها را بااستفاده از خط فرمان تعریف کرد.

در اینجا چند مرحله اصلی برای تعریف متغیر محیطی بااستفاده از فایل .bashrc در پایانه آورده شده است:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

متغیرهای محیطی را می‌توان مستقیماً از خط فرمان در نمونه پایانه تنظیم کرد:

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

روش load_from_env داده‌های پیکربندی را از مشخصه environ در ماژول داخلی os Python بار می‌کند. برای مثال: os.environ["GOOGLE_ADS_CLIENT_ID"]

در اینجا مثالی از نحوه مقداردهی اولیه نمونه کارخواه با پیکربندی از متغیرهای محیطی آورده شده است:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

برای پیکربندی logging ازطریق متغیرهای محیطی، مقدار پیکربندی باید شیء JSON باشد که با ساختار کلیدهای YAML در فایل پیکربندی نمونه google-ads.yaml مطابقت داشته باشد.

در اینجا مثالی از نحوه تنظیم این مورد بااستفاده از فایل .bashrc آورده شده است:

export GOOGLE_ADS_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"
    }
  }
}'

نکته کلیدی: اگر متغیر محیطی GOOGLE_ADS_CONFIGURATION_FILE_PATH هنگام فراخوانی روش load_from_env تنظیم شده باشد، مقادیر پیکربندی از فایل google-ads.yaml واقع در مسیر مشخص‌شده بازیابی می‌شوند، نه از متغیرهای محیطی که قبلاً شرح داده شد.

پیکربندی بااستفاده از رشته YAML

اگر فایل YAML را در حافظه خوانده‌اید، می‌توانید آن را مستقیماً در زمان مقداردهی اولیه به کارخواه ارائه دهید. برای انجام این کار، از روش load_from_string استفاده کنید:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

پیکربندی بااستفاده از dict

می‌توانید dict را مستقیماً به روش load_from_dict ارسال کنید. برای مثال:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

فیلدهای پیکربندی

پیکربندی کتابخانه کارخواه از فیلدهای زیر پشتیبانی می‌کند.

اصالت‌سنجی

فقط از یکی از این گروه‌های فیلد استفاده کنید، بسته به اینکه از کدام رویکرد اصالت‌سنجی استفاده می‌کنید:

  • تک‌کاربر با اعتبارنامه پیش‌فرض برنامه (مستندات)
    • use_application_default_credentials: اینکه آیا کتابخانه باید از اعتبارنامه‌های پیش‌فرض برنامه (ADC) برای اصالت‌سنجی استفاده کند (در google-ads v28.3.0 و نسخه‌های جدیدتر پشتیبانی می‌شود).
  • تک‌کاربر با کدهای OAuth (اسناد)
    • client_id: شناسه کارخواه OAuth شما.
    • client_secret: رمز کارخواه OAuth شما.
    • refresh_token: کد بازآوری OAuth شما.
  • حساب سرویس (مستندات)
    • json_key_file_path: مسیر فایل کلید خصوصی محلی. این برای اصالت‌سنجی بااستفاده از حساب سرویس استفاده می‌شود.
    • impersonated_email: نشانی ایمیل اختیاری حساب برای جعل هویت هنگام استفاده از واگذاری در سطح دامنه Google Workspace.

رفتار کتابخانه

این فیلدها رفتار کتابخانه را تعیین می‌کنند:

پیکربندی سطح درخواست

  • linked_customer_id: سند linked-customer-id را ببینید.
  • ‫login_customer_id: سند login-customer-id را ببینید.
  • endpoint: نشانی نقطه پایانی Google Ads API جایگزین اختیاری.
  • ads_assistant: شناسه اختیاری برای سرصفحه «دستیار Google Ads API».

متغیرهای محیطی

برای پیکربندی کتابخانه بااستفاده از متغیرهای محیطی، از موارد زیر استفاده کنید:

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (در v28.3.0 و نسخه‌های جدیدتر پشتیبانی می‌شود)

پیکربندی گزارش

فیلدهای گزارش، که فیلدهای زیر فیلد پیکربندی logging هستند، مستقیماً از ماژول داخلی logging.config مشتق می‌شوند زیرا کتابخانه همه فیلدهای زیر فضای نام logging را مستقیماً به روش logging.config.dictConfig ارسال می‌کند. برای جزئیات کامل، راهنمای ثبت گزارش را ببینید.

  • ‫version: مقدار عدد صحیحی که نسخه طرح‌واره را نشان می‌دهد.
  • ‫disable_existing_loggers: اینکه آیا ثبت‌کننده‌های پیکربندی‌شده در جای دیگری از برنامه باید غیرفعال شوند یا نه.
  • ‫formatters: واژه‌نامه‌هایی که انواع مختلف قالب‌بندی را تعریف می‌کنند.
  • handlers: واژه‌نامه‌هایی که گرداننده‌های مختلف را تعریف می‌کنند، که کنترل می‌کنند گزارش‌ها کجا نوشته شوند و از کدام قالب‌بندی‌ها باید استفاده شود.
  • loggers: واژه‌نامه‌هایی که انواع مختلف ثبت‌کننده‌ها را تعریف می‌کنند، که شامل یک گرداننده و یک سطح ثبت است.