التهيئة

يمكنك ضبط مكتبة برامج Python باستخدام ملف YAML أو متغيّرات البيئة أو سلسلة YAML أو dict.

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

تتوفّر عدة طرق لإدارة بيانات اعتماد 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
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

إذا تم توفير كلتا القيمتَين، أي تم تمرير مسار إلى الطريقة وكان متوفّرًا متغير بيئة، ستعطي المكتبة الأولوية للمسار الذي تم تمريره إلى الطريقة.

الإعداد باستخدام متغيّرات البيئة

يمكنك تخزين جميع إعدادات العميل كمتغيّرات بيئية، والتي تتم قراءتها عند استخدام طريقة load_from_env الخاصة بالعميل. يجب أن تحمل متغيرات البيئة الاسم نفسه المحدّد في ملف google-ads.yaml، ولكن يجب أن تكون جميعها بأحرف كبيرة ومسبوقة بمساحة الاسم GOOGLE_ADS_. على سبيل المثال، يجب تخزين client_id على النحو GOOGLE_ADS_CLIENT_ID.

يتم عادةً تحديد متغيّرات البيئة في ملف إعداد باش، مثل ملف .bashrc أو .bash_profile، والموجود في الدليل $HOME. ويمكن أيضًا تحديدها باستخدام سطر الأوامر.

في ما يلي بعض الخطوات الأساسية لتحديد متغير بيئة باستخدام ملف .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.
source ~/.bashrc

يمكن أيضًا ضبط متغيرات البيئة في مثيل الطرفية مباشرةً من سطر الأوامر:

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

تحمّل طريقة 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"
    }
  }
}'

نقطة أساسية: إذا تم ضبط متغيّر البيئة GOOGLE_ADS_CONFIGURATION_FILE_PATH عند استدعاء الطريقة load_from_env، سيتم استرداد قيم الإعدادات من الملف google-ads.yaml الموجود في المسار المحدّد، وليس من متغيّرات البيئة الموضّحة سابقًا.

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

إذا كنت قد قرأت ملف YAML في الذاكرة، يمكنك تقديمه مباشرةً إلى العميل عند بدء التشغيل. لإجراء ذلك، استخدِم طريقة load_from_string:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

الإعداد باستخدام dict

يمكنك تمرير dict مباشرةً إلى الطريقة load_from_dict. على سبيل المثال:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

حقول الإعداد

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

المصادقة

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

  • مستخدم واحد مع بيانات الاعتماد التلقائية للتطبيق (المستندات)
    • ‫use_application_default_credentials: ما إذا كان يجب أن تستخدم المكتبة بيانات الاعتماد التلقائية للتطبيق (ADC) للمصادقة (متاحة في الإصدار google-ads v28.3.0 والإصدارات الأحدث).
  • مستخدم واحد مع رموز OAuth المميزة (المستندات)
    • استبدِل client_id بمعرّف عميل OAuth.
    • استبدِل client_secret بسر عميل OAuth.
    • refresh_token: الرمز المميز لإعادة تحميل OAuth.
  • حساب الخدمة (المستندات)
    • json_key_file_path: مسار إلى ملف مفتاح خاص محلي يُستخدم هذا المعرّف للمصادقة باستخدام حساب خدمة.
    • impersonated_email: عنوان البريد الإلكتروني الاختياري للحساب الذي سيتم انتحال هويته عند استخدام التفويض على مستوى النطاق في Google Workspace.

سلوك المكتبة

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

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

  • linked_customer_id: اطّلِع على مستندات linked-customer-id.
  • login_customer_id: يُرجى الاطّلاع على مستندات login-customer-id.
  • ‫endpoint: عنوان نقطة نهاية بديل اختياري لواجهة Google Ads API.
  • ‫ads_assistant: معرّف اختياري لعنوان Google Ads API Assistant.

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

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

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • 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 (يتوفّر في الإصدار v28.3.0 والإصدارات الأحدث)

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

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

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