التهيئة

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

إعدادات المصادقة

تتوفّر عدة طرق لإدارة بيانات اعتماد OAuth اللازمة للوصول إلى واجهة برمجة التطبيقات مع "إعلانات Google". سيؤثر النهج الذي تختاره في حقول الإعدادات التي تستخدمها. لمزيد من المعلومات، يُرجى الاطّلاع على دليل المصادقة.

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

يمكنك تحديد ملف YAML لاستخدامه عند تهيئة العميل الذي يحتوي على المعلومات اللازمة لتقديم الطلبات إلى Google Ads API. يتم الوصول إلى هذا الملف عند إعداد عميل باستخدام الطريقة 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)

حقول الضبط

يتيح إعداد مكتبة البرامج للعميل استخدام الحقول التالية.

المصادقة

استخدِم مجموعة واحدة فقط من حقول المصادقة، وذلك حسب طريقة المصادقة التي تستخدمها:

  • مستخدم واحد مع بيانات الاعتماد التلقائية للتطبيق (المستندات)
    • ‫use_application_default_credentials: ما إذا كان يجب أن تستخدم المكتبة بيانات الاعتماد التلقائية للتطبيق (ADC) للمصادقة.
  • مستخدم واحد لديه رموز OAuth المميزة (المستندات)
    • client_id: معرّف عميل OAuth.
    • client_secret: سر عميل OAuth.
    • refresh_token: رمز إعادة تحميل OAuth المميز.
  • حساب الخدمة (المستندات)
    • json_key_file_path: مسار إلى ملف مفتاح خاص محلي يُستخدَم هذا الحقل للمصادقة باستخدام حساب خدمة.

سلوك المكتبة

تحدّد هذه الحقول سلوك المكتبة:

الإعداد على مستوى الطلب

متغيرات البيئة

لضبط المكتبة باستخدام متغيّرات البيئة، استخدِم ما يلي:

  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_DEVELOPER_TOKEN
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS

إعدادات التسجيل

يتم استخلاص حقول التسجيل، وهي الحقول التي تقع ضمن حقل الإعداد logging، مباشرةً من الوحدة المضمّنة logging.config، لأنّ المكتبة ستمرّر جميع الحقول ضمن مساحة الاسم logging مباشرةً إلى الطريقة logging.config.dictConfig. يمكنك الاطّلاع على دليل تسجيل البيانات للحصول على التفاصيل الكاملة.

  • version: قيمة عدد صحيح تمثّل إصدار المخطّط.
  • disable_existing_loggers: تحدّد ما إذا كان يجب إيقاف أدوات تسجيل البيانات التي تم ضبطها في مكان آخر في التطبيق.
  • formatters: قواميس تحدّد أنواعًا مختلفة من أدوات التنسيق.
  • handlers: قواميس تحدّد معالِجات مختلفة تتحكّم في مكان كتابة السجلات وفي أدوات التنسيق التي يجب استخدامها.
  • ‫loggers: قواميس تحدّد أنواعًا مختلفة من أدوات تسجيل البيانات، وتشمل معالجًا ومستوى سجلّ.