التهيئة

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

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

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

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

يتم عادةً تحديد متغيّرات البيئة في ملف إعداد 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)

حقول الإعدادات

تتيح مكتبة العميل حقول الإعدادات التالية.

المصادقة

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

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

سلوك المكتبة

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

• logging: يمكنك الاطّلاع على تفاصيل إعدادات التسجيل.
• http_proxy: يمكنك الاطّلاع على مستندات الخادم الوكيل.
• use_proto_plus: ما إذا كان يجب استخدام رسائل proto-plus أم لا يمكنك الاطّلاع على مستندات رسائل protobuf protobuf.

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

• developer_token: مطلوب الرمز المميز للمطوِّر للوصول إلى واجهة برمجة التطبيقات
• linked_customer_id: يمكنك الاطّلاع على مستندات linked-customer-id.
• login_customer_id: يمكنك الاطّلاع على مستندات login-customer-id.

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

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

• 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

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

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

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