الإعداد

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

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