التهيئة

يمكنك ضبط مكتبة برامج 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.

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