التهيئة

تتم إدارة الإعدادات باستخدام فئة Config. يمكنك ضبط العميل باستخدام ملف إعداد، أو تحديد القيم ديناميكيًا عند الإنشاء، أو تحميل القيم من متغيّرات البيئة.

ملف الإعداد

يمكنك تحديد ملف google_ads_config.rb لاستخدامه عند إنشاء مثيل للعميل.

إذا لم يتم تمرير أي وسيطات عند إنشاء مثيل لكائن GoogleAdsClient، تبحث المكتبة عن ملف إعداد بالترتيب التالي:

  1. المسار المحدّد في متغيّر البيئة GOOGLE_ADS_CONFIGURATION_FILE_PATH
  2. ملف باسم google_ads_config.rb في دليل HOME (~/google_ads_config.rb).

بدلاً من ذلك، يمكنك تمرير مسار صريح عند إنشاء مثيل للعنصر GoogleAdsClient:

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/file.rb')

لإنشاء هذا الملف، انسخ google_ads_config.rb من مستودع GitHub وعدِّله ليتضمّن الرمز المميز لإعادة التحميل ومعرّف العميل وسر العميل.

الإعدادات الديناميكية

يمكنك ضبط الإعدادات ديناميكيًا عند إنشاء مثيل للمكتبة:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  # ... additional configuration
end

يمكنك أيضًا تعديل الإعدادات بعد إنشاء مثيل (ما يؤدي إلى إلغاء الإعدادات التي تم تحميلها أثناء الإعداد):

client.configure do |config|
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  # ... additional configuration
end

حقول الإعداد

يتيح عنصر Config استخدام الحقول التالية.

الحقول العامة:

  • ‫refresh_token: الرمز المميز لإعادة التحميل في OAuth ‏ (GOOGLE_ADS_REFRESH_TOKEN).
  • ‫client_id: معرّف عميل OAuth ‏ (GOOGLE_ADS_CLIENT_ID)
  • ‫client_secret: سر عميل OAuth ‏ (GOOGLE_ADS_CLIENT_SECRET)
  • ‫keyfile: المسار إلى ملف مفتاح JSON لحساب الخدمة (GOOGLE_ADS_JSON_KEY_FILE_PATH).
  • ‫impersonate: عنوان البريد الإلكتروني الذي يجب انتحال هويته عند استخدام حساب خدمة مع تفويض على مستوى النطاق (GOOGLE_ADS_IMPERSONATED_EMAIL).
  • use_application_default_credentials: يجب ضبط هذه السمة على true للمصادقة باستخدام "بيانات الاعتماد التلقائية للتطبيق" (GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS). تتوفّر هذه السمة في الإصدار 36.1.0 من google-ads-googleads والإصدارات الأحدث.
  • ‫authentication: عنصر مصادقة مخصّص، مثل Proc (updater_proc) أو مسار ملف مفتاح أو Hash أو GRPC::Core::Channel / GRPC::Core::ChannelCredentials. يتم إلغاء client_id وclient_secret وrefresh_token وkeyfile.
  • ‫login_customer_id: يُرجى الاطّلاع على مستندات login-customer-id (GOOGLE_ADS_LOGIN_CUSTOMER_ID).
  • ‫linked_customer_id: الرقم التعريفي للعميل المرتبط (GOOGLE_ADS_LINKED_CUSTOMER_ID).
  • ‫ads_assistant: معرّف اختياري لرأس مساعد Google Ads API (GOOGLE_ADS_ASSISTANT، تمت إضافته باسم gaada في الإصدار 37.0.0 وتمت إعادة تسميته إلى ads_assistant في الإصدار 39.0.0).
  • ‫http_proxy: معرّف موارد منتظم (URI) اختياري للخادم الوكيل لبروتوكول HTTP أو HTTPS (GOOGLE_ADS_RUBY_HTTP_PROXY).
  • api_endpoint: نقطة نهاية اختيارية لتجاوز واجهة برمجة التطبيقات (GOOGLE_ADS_ENDPOINT).
  • treat_deprecation_warnings_as_errors: يمكنك رفع استثناء بدلاً من استدعاء Warning#warn عند استدعاء رمز المكتبة المتوقّف نهائيًا (false تلقائيًا).
  • warn_on_all_deprecations: إصدار تحذير بشأن الإيقاف النهائي في كل مكالمة بدلاً من مرة واحدة لكل موقع مكالمة (false تلقائيًا).

حقول السجلّ (يُرجى الاطّلاع على دليل التسجيل للحصول على التفاصيل الكاملة):

  • ‫log_level: الحد الأدنى لمستوى رسائل السجلّ التي تريد تسجيلها. على سبيل المثال، يؤدي تحديد 'DEBUG' إلى تسجيل جميع الرسائل، ويؤدي تحديد 'INFO' إلى استبعاد رسائل DEBUG مع عرض جميع الرسائل الأخرى.
  • log_target: المكان الذي تريد التسجيل فيه، مثل STDERR أو مسار.
  • ‫logger: حدِّد أداة التسجيل المخصّصة. يؤدي تحديد هذه السمة إلى إلغاء كل من log_level وlog_target.

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

يمكنك ضبط مكتبة العميل باستخدام متغيّرات البيئة. ولا يتم تحميلها تلقائيًا، وتتطلّب استدعاءً صريحًا بعد إنشاء مثيل للعميل من أجل تحميلها. يمكنك الاطّلاع على القائمة الكاملة لمتغيّرات البيئة العادية.

لتحميل متغيّرات البيئة في Config، يمكنك استدعاء load_environment_config:

client = Google::Ads::GoogleAds::GoogleAdsClient.new
client.load_environment_config

في كل مرة يتم فيها استدعاء load_environment_config، يتم استبدال أي متغيرات بيئة محددة بالقيم المقابلة الموجودة في Config (متغيرات البيئة غير المحددة تترك قيم الإعدادات الحالية بدون تغيير). باستخدام هذه الآلية، يمكنك الاحتفاظ بملف إعداد تلقائي وإلغاء قيم معيّنة باستخدام متغيّرات البيئة، أو ضبط العميل بالكامل باستخدام متغيّرات البيئة.

بالإضافة إلى متغيرات البيئة العادية، تتيح مكتبة Ruby استخدام متغيرَين إضافيَين:

  • ‫GOOGLE_ADS_RUBY_LOG_LEVEL: تعادل log_level كما هو موضّح سابقًا.
  • ‫GOOGLE_ADS_RUBY_HTTP_PROXY: حدِّد عنوان URL لخادم وكيل HTTP.