التهيئة

توفّر مكتبة عملاء Perl في Google Ads API عدة إعدادات ضبط يمكنك استخدامها لتخصيص سلوك المكتبة.

ملف الإعداد

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

إذا لم تستخدم أي وسيطات عند إنشاء مثيل:

my $api_client = Google::Ads::GoogleAds::Client->new();

تبحث المكتبة في دليل HOME عن الملف، أو في المسار المحدّد في متغيّر البيئة GOOGLE_ADS_CONFIGURATION_FILE_PATH إذا تم ضبطه.

بدلاً من ذلك، يمكنك تحديد مسار بشكل صريح:

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file,
});

وفي هذه الحالة يبحث العميل عن الملف في هذا المسار.

أسهل طريقة لإنشاء هذا الملف هي نسخ googleads.properties من مستودع GitHub وتعديله ليتضمّن معرّف العميل وسر العميل والرمز المميز لإعادة التحميل.

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

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

my $api_client = Google::Ads::GoogleAds::Client->new({
  login_customer_id => "INSERT_LOGIN_CUSTOMER_ID_HERE",
});

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

$api_client->set_login_customer_id("INSERT_LOGIN_CUSTOMER_ID_HERE");

يمكنك أيضًا الحصول على عنصر OAuth2ApplicationsHandler من مثيل Client وتغيير معرّف العميل وسر العميل والرمز المميز لإعادة التحميل في وقت التشغيل:

my $oauth2_applications_handler =
  $api_client->get_oauth2_applications_handler();
$oauth2_applications_handler->set_client_id("INSERT_CLIENT_ID_HERE");
$oauth2_applications_handler->set_client_secret("INSERT_CLIENT_SECRET_HERE");
$oauth2_applications_handler->set_refresh_token("INSERT_REFRESH_TOKEN_HERE");

ملاحظة: لا يُنصح بتخزين الرموز السرية المضمّنة في الرمز المصدري. استخدِم متغيرات البيئة أو ملف خصائص آمن لبيئات التشغيل الفعلي.

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

يمكنك ضبط بعض إعدادات الضبط من متغيّرات البيئة عند إنشاء مثيل للعملاء (يُرجى الاطّلاع على متغيّرات البيئة العادية).

توفّر وحدة Client الدالة configure_from_environment_variables لتحميل القيم من متغيرات البيئة.

ملاحظة: لا يتم أخذ متغيّرات البيئة غير المحدّدة في الاعتبار.

# Get the Google Ads API Client. By default, any credentials are read from
# ~/googleads.properties, or, if set, from the file specified in the
# GOOGLE_ADS_CONFIGURATION_FILE_PATH environment variable.
my $api_client = Google::Ads::GoogleAds::Client->new();

# Load the configuration from any set environment variables.
$api_client->configure_from_environment_variables();

حقول الإعداد

يُرجى العِلم أنّ مفاتيح googleads.properties تستخدم camelCase (مثل loginCustomerId وlinkedCustomerId)، في حين أنّ وسيطات الدالة الإنشائية Client->new({...}) وطرق المعالِج تستخدم snake_case (مثل login_customer_id وlinked_customer_id).

الحقول التي تم الاحتفاظ بها في OAuth2ApplicationsHandler:

• ‫client_id (‫clientId في googleads.properties، GOOGLE_ADS_CLIENT_ID): معرّف عميل OAuth2
• ‫client_secret (clientSecret في googleads.properties، GOOGLE_ADS_CLIENT_SECRET): سر عميل OAuth2.
• ‫refresh_token (refreshToken في googleads.properties، GOOGLE_ADS_REFRESH_TOKEN): الرمز المميز لإعادة التحميل في OAuth2.
• ‫additional_scopes (‫additionalScopes في googleads.properties): نطاقات OAuth2 الإضافية المطلوب طلبها

الحقول التي تم الاحتفاظ بها في OAuth2ServiceAccountsHandler:

• ‫json_key_file_path (‫jsonKeyFilePath في googleads.properties، GOOGLE_ADS_JSON_KEY_FILE_PATH): مسار ملف مفتاح JSON لحساب الخدمة
• impersonated_email (impersonatedEmail في googleads.properties، GOOGLE_ADS_IMPERSONATED_EMAIL): عنوان البريد الإلكتروني الذي يتم انتحال هويته عند استخدام التفويض على مستوى نطاق Google Workspace.
• ‫additional_scopes (‫additionalScopes في googleads.properties): نطاقات OAuth2 الإضافية المطلوب طلبها

الحقول التي تم الاحتفاظ بها في Client:

• ‫login_customer_id (loginCustomerId في googleads.properties، GOOGLE_ADS_LOGIN_CUSTOMER_ID): رقم تعريف الحساب الإداري المستخدَم للوصول إلى حساب العميل يُرجى الاطّلاع على مستندات login-customer-id.
• ‫linked_customer_id (linkedCustomerId في googleads.properties، GOOGLE_ADS_LINKED_CUSTOMER_ID): رقم تعريف العميل المرتبط
• ‫service_address (‫serviceAddress في googleads.properties، GOOGLE_ADS_ENDPOINT): عنوان URL لخدمة Google Ads API (القيمة التلقائية هي "https://googleads.googleapis.com").
• ‫user_agent (userAgent في googleads.properties، GOOGLE_ADS_PERL_USER_AGENT): بادئة عنوان وكيل المستخدم المخصّصة المضمّنة في طلبات HTTP
• ‫proxy (proxy في googleads.properties، GOOGLE_ADS_PERL_PROXY): عنوان URL الخاص بالخادم الوكيل المستخدَم للاتصال بالإنترنت.
• version (Client->new أو set_version): وحدة إصدار Google Ads API المطلوب استخدامها (الإعداد التلقائي هو "V26").
• ‫die_on_faults (Client->new أو set_die_on_faults): يتم ضبطها على 1 لكي تطلب طرق الخدمة die() مع حمولة الاستجابة الأولية عند حدوث أخطاء في واجهة برمجة التطبيقات بدلاً من عرض عنصر Google::Ads::GoogleAds::GoogleAdsException (القيمة التلقائية هي 0).
• http_timeout (Client->new أو set_http_timeout): مهلة HTTP بالثواني (القيمة التلقائية هي 3600)
• ‫http_retry_timing (Client->new أو set_http_retry_timing): الفواصل الزمنية لإيقاف إعادة المحاولة بالثواني لأخطاء HTTP 503 و504 المؤقتة (القيمة التلقائية هي "5,10,15").