پیکربندی

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

پیکربندی احراز هویت

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

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

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

اگر مسیری ارائه ندهید، کتابخانه در دایرکتوری $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

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

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

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

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

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

در اینجا چند مرحله اساسی برای تعریف یک متغیر محیطی با استفاده از فایل .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.
$ src ~/.bashrc

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

$ export GOOGLE_ADS_CLIENT_ID=1234567890
$ echo $GOOGLE_ADS_CLIENT_ID
1234567890

متد load_from_env داده‌های پیکربندی را از ویژگی environ در ماژول os داخلی پایتون بارگذاری می‌کند. برای مثال: 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"
    }
  }
}'

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

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

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "rb") as handle:
    yaml = handle.read()

client = GoogleAdsClient.load_from_string(yaml)

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

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

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "developer_token": "abcdef123456",
    "refresh_token": "1//0abcdefghijklABCDEF",
    "client_id": "123456-abcdef.apps.googleusercontent.com",
    "client_secret": "aBcDeFgHiJkL"}

client = GoogleAdsClient.load_from_dict(credentials)

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

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

احراز هویت

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

  • تک کاربره با اعتبارنامه‌های پیش‌فرض برنامه ( مستندات )
    • use_application_default_credentials : مشخص می‌کند که آیا کتابخانه باید از اعتبارنامه‌های پیش‌فرض برنامه (ADC) برای احراز هویت استفاده کند یا خیر.
  • تک کاربره با توکن‌های OAuth ( مستندات )
    • client_id : شناسه کلاینت OAuth شما.
    • client_secret : رمز کلاینت OAuth شما.
    • refresh_token : توکن به‌روزرسانی OAuth شما.
  • حساب کاربری سرویس ( مستندات )
    • json_key_file_path : مسیری به فایل کلید خصوصی محلی. این مسیر برای احراز هویت با استفاده از یک حساب کاربری سرویس استفاده می‌شود.

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

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

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

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

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

  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_DEVELOPER_TOKEN
  • GOOGLE_ADS_HTTP_PROXY
  • 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

پیکربندی ثبت وقایع

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

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