الإعداد

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

الإعدادات باستخدام ملف 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.

يتم تحديد متغيّرات البيئة عادةً في ملف إعداد أساسي، مثل ملف .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 أو إعداد الإملاء):

  • refresh_token: الرمز المميز لإعادة تحميل OAuth.
  • client_id: معرِّف عميل OAuth.
  • client_secret: سر عميل بروتوكول OAuth.
  • developer_token: الرمز المميز للمطوِّر للوصول إلى واجهة برمجة التطبيقات
  • login_customer_id: يُرجى الاطّلاع على وثائق تسجيل دخول العميل.
  • linked_customer_id: يُرجى الاطّلاع على مستندات id-customer-id.
  • json_key_file_path (المعروفة سابقًا باسم path_to_private_key_file): مسار إلى ملف مفتاح خاص محلي. تُستخدم هذه الخطوة للمصادقة باستخدام حساب خدمة. اطّلِع على مستندات حساب خدمة OAuth2.
  • impersonated_email (المعروف سابقًا باسم delegate_account): بريد إلكتروني للحساب يُستخدم كمفوَّض. تُستخدم هذه المصادقة للمصادقة باستخدام حساب خدمة. راجِع مستندات حساب خدمة OAuth2.
  • logging: ضبط التسجيل. يتم وصف حقول التسجيل أدناه.
  • http_proxy: يُرجى الاطّلاع على مستندات الخادم الوكيل.
  • use_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: قواميس تحدد أنواعًا مختلفة من أدوات التسجيل، والتي تتضمن معالجًا ومستوى سجل.