الإعدادات

هناك العديد من الطرق المختلفة لضبط البرنامج.

الإعداد باستخدام ملف YAML

يمكنك تحديد ملف YAML لاستخدامه عند إعداد العميل الذي يحتوي على معلومات المصادقة الضرورية اللازمة لتقديم الطلبات. يتم الوصول إلى هذا الملف عند إعداد برنامج باستخدام طريقة load_from_storage. أسهل طريقة لإنشاء هذا الملف هي نسخ مثال google-ads.yaml من مستودع GitHub وتعديله لتضمين بيانات الاعتماد، بما في ذلك الرمز المميز للمطوِّر والرمز المميز لإعادة التحميل ومعرّف العميل وسر العميل.

لتحديد موقع ملف 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()

إذا تم توفير القيمتَين، وتم تمرير مسار إلى الطريقة وكان متغيّر البيئة أعلاه متوفّرًا، ستعطي المكتبة الأولوية للمسار الذي تم تمريره إلى الطريقة.

إذا لم توفّر مسارًا، ستبحث المكتبة في دليل $HOME عن الملف:

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)

حقول الإعداد

تتوافق إعدادات مكتبة البرامج مع الحقول التالية.

الحقول العامة (هذه الأسماء هي نفسها سواء كنت تستخدم تهيئة YAML أو dict):

  • refresh_token: الرمز المميز لتحديث OAuth.
  • client_id: معرِّف عميل OAuth الخاص بك
  • client_secret: سر عميل OAuth
  • developer_token: الرمز المميز للمطوِّر للدخول إلى واجهة برمجة التطبيقات
  • login_customer_id: اطّلِع على مستندات تسجيل الدخول للعميل.
  • linked_customer_id: اطّلِع على مستندات linked-customer-id.
  • json_key_file_path (path_to_private_key_file سابقًا): مسار إلى ملف مفتاح خاص محلي. يُستخدم هذا للمصادقة باستخدام حساب الخدمة. راجِع مستندات حساب خدمة OAuth2.
  • impersonated_email (delegate_account سابقًا): بريد إلكتروني لحساب يتم استخدامه كمفوض. يستخدم هذا للمصادقة باستخدام حساب الخدمة. يمكنك الاطِّلاع على مستندات حساب خدمة OAuth2.
  • logging: إعدادات التسجيل. يتم توضيح حقول التسجيل أدناه.
  • http_proxy: يمكنك الاطّلاع على مستندات الخادم الوكيل.
  • use_proto_plus: تحديد ما إذا كان سيتم استخدام رسائل Proto-plus أم لا اطّلِع على مستندات رسائل Protobuf.

الحقول العامة كمتغيرات للبيئة:

  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_DEVELOPER_TOKEN
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_JSON_KEY_FILE_PATH (GOOGLE_ADS_PATH_TO_PRIVATE_KEY_FILE سابقًا)
  • GOOGLE_ADS_IMPERSONATED_EMAIL (GOOGLE_ADS_DELEGATE_ACCOUNT سابقًا)
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_USE_PROTO_PLUS

إنّ حقول التسجيل، وهي حقول أسفل حقل الإعداد logging، يتم استنباطها مباشرةً من الوحدة logging.config المدمجة لأن المكتبة ستمرر جميع الحقول ضمن مساحة الاسم logging مباشرةً إلى الطريقة logging.config.dictConfig. راجِع دليل التسجيل للحصول على التفاصيل الكاملة.

  • version: قيمة عددية تمثّل إصدار المخطط
  • disable_existing_loggers: ما إذا كان يجب إيقاف أدوات التسجيل التي تم ضبطها في مكان آخر في التطبيق.
  • formatters: قواميس تحدِّد أنواعًا مختلفة من أدوات التنسيق
  • handlers: قواميس تحدِّد معالِجات مختلفة تتحكّم في مكان كتابة السجلّات وأدوات التنسيق التي يجب استخدامها
  • loggers: قواميس تحدِّد أنواعًا مختلفة من أدوات التسجيل، بما في ذلك المعالج ومستوى السجلّ.