التهيئة

تتوفّر عدة طرق مختلفة لإعداد العميل.

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

يمكنك تحديد ملف YAML لاستخدامه عند بدء تشغيل العميل، على أن يتضمّن معلومات المصادقة اللازمة لإجراء الطلبات. يتم الوصول إلى هذا الملف عند إعداد عميل باستخدام الطريقة 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

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.

يتم عادةً تحديد متغيّرات البيئة في ملف إعداد باش، مثل ملف .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 المضمّنة في 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"
    }
  }
}'

الإعداد باستخدام سلسلة 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: اطّلِع على مستندات 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: قواميس تحدّد أنواعًا مختلفة من أدوات تسجيل البيانات، وتشمل معالجًا ومستوى سجلّ.