التهيئة

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

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

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