التهيئة

تتم إدارة الإعدادات باستخدام الفئة 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). هذه السمة متاحة في google-ads-googleads الإصدار 36.1.0 والإصدارات الأحدث.
  • ‫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 Assistant ‏ (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.