پیکربندی

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