الإعدادات

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

الإعداد باستخدام ملف 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_namespace. على سبيل المثال، يجب تخزين السمة 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 أو إملاء):

  • refresh_token: الرمز المميّز لإعادة تحميل OAuth
  • client_id: معرِّف عميل OAuth
  • client_secret: سر عميل OAuth.
  • developer_token: الرمز المميز للمطوِّر للدخول إلى واجهة برمجة التطبيقات.
  • login_customer_id: اطّلِع على مستندات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: القواميس التي تحدد أنواعًا مختلفة من أدوات التسجيل، بما في ذلك معالج ومستوى السجل.