التهيئة

يمكنك ضبط مكتبة برامج 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: معرّف اختياري لرأس Assistant في Google Ads API

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

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

  • 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: قواميس تحدّد أنواعًا مختلفة من أدوات التسجيل، بما في ذلك معالج ومستوى تسجيل.