التهيئة

توفّر مكتبة عميل 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:

• developer_token (developerToken في googleads.properties, GOOGLE_ADS_DEVELOPER_TOKEN): (سيتم إيقافها نهائيًا في 9 سبتمبر 2026) هو الرمز المميز للمطوِّر في Google Ads API. اختياري، تتجاهله خوادم واجهة برمجة التطبيقات بغض النظر عن إصدار مكتبة البرامج، وسيتم رفضه في رقم إصدار رئيسي مستقبلي من Google Ads API.
  • الإصدار v35.0.0 والإصدارات الأحدث: لا يكون مطلوبًا عند بدء تشغيل العميل (تمت إزالة عملية التحقّق المحلية من جهة العميل باستخدام developerToken في الإصدار v35.0.0).
  • الإصدارات الأقدم من v35.0.0: مطلوبة لإثبات صحة الإعدادات المحلية من جهة العميل إذا لم تتم الترقية إلى الإصدار v35.0.0 أو إصدار أحدث.
• ‫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 التي سيتم استخدامها (القيمة التلقائية هي "V25").
• ‫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").