التهيئة

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

ملف الإعداد

يمكنك تخزين معظم إعدادات الضبط هذه فيملفات ini واستخدامها عند إنشاء مثيلات للعملاء، على سبيل المثال، google_ads_php.ini.

يقدّم كلّ من أداة إنشاء بيانات الاعتماد وأداة إنشاء العملاء fromFile طريقة لتحميل الإعدادات من هذه الملفات:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

إذا لم يتم تقديم مسار إعدادات كوسيطة، يتم تحميل fromFile الطرق من مسار الإعدادات التلقائي الذي يكون:

1. قيمة متغيّر البيئة المُسمّى GOOGLE_ADS_CONFIGURATION_FILE_PATH في حال ضبطه
2. بخلاف ذلك، ملف google_ads_php.ini في دليل HOME.

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

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

يمكنك ضبط إعدادات الضبط هذه ديناميكيًا عند إنشاء مثيلات للعملاء.

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID')
    // ...
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withDeveloperToken('INSERT_DEVELOPER_TOKEN_HERE')
    // ...
    ->build();

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

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

يقدّم كلّ من أداة إنشاء بيانات الاعتماد وأداة إنشاء العملاء fromEnvironmentVariables طُرقًا لتحميل الإعدادات من متغيّرات البيئة:

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

$oAuth2Credential = (new OAuth2TokenBuilder())
    // ...
    ->fromEnvironmentVariables()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    // ...
    ->fromEnvironmentVariables()
    ->build();

حقول الضبط

ملاحظة: لا يمكن ضبط الحقول grpcChannelCredential وunaryMiddlewares streamingMiddlewares وgrpcInterceptors من ملف أو سلسلة ملفّات الضبط، بل يمكن ضبطها ديناميكيًا فقط.

تتيح إعدادات الضبط العديد من الحقول المنظَّمة في فئات.

1. الحقول المستخدَمة من قِبل OAuth2TokenBuilder:
   • وضع التطبيق
     • [OAUTH2] clientId: معرّف عميل OAuth2.
     • [OAUTH2] clientSecret: سر عميل OAuth2.
     • [OAUTH2] refreshToken: الرمز المميّز لإعادة تحميل OAuth2
   • وضع حساب الخدمة
     • [OAUTH2] jsonKeyFilePath: مسار ملف مفتاح Json.
     • [OAUTH2] scopes: النطاقات
     • ‫[OAUTH2] impersonatedEmail: عنوان البريد الإلكتروني الذي تريد انتحال هويته.
2. الحقول المستخدَمة من قِبل GoogleAdsClientBuilder:
   • [GOOGLE_ADS] developerToken: الرمز المميّز للمطوّر للوصول إلى واجهة برمجة التطبيقات
   • ‫[GOOGLE_ADS] loginCustomerId: معرّف العميل المفوَّض المطلوب استخدامه في الطلب.
   • ‫[GOOGLE_ADS] linkedCustomerId: رقم تعريف العميل المرتبط.
   • [LOGGING] logFilePath: مسار الملف الذي يتم فيه تسجيل البيانات
   • [LOGGING] logLevel: مستوى التسجيل
   • ‫[CONNECTION] proxy: عنوان URL للخادم الوكيل المستخدَم للاتصال بالإنترنت
   • [CONNECTION] transport: وسيلة النقل
   • [CONNECTION] grpcChannelIsSecure: ما إذا كانت قناة gRPC آمنة أم لا
   • ‫[CONNECTION] grpcChannelCredential: بيانات اعتماد قناة gRPC
   • [CONNECTION] unaryMiddlewares: برامج وسيطة أحادية
   • ‫[CONNECTION] streamingMiddlewares: برامج وسيطة لبث الوسائط
   • [CONNECTION] grpcInterceptors: أدوات اعتراض gRPC

التحقّق من الإعدادات

يتم التحقّق من إعدادات الضبط عند إنشاء مثيلات للعملاء ويتم طرح استثناءات في حال عدم صلاحيتها. في ما يلي القواعد:

1. يجب عدم ضبط حقول [OAUTH2] لكلّ من "وضع التطبيق" و"وضع حساب الخدمة" في الوقت نفسه.
2. يجب ضبط [OAUTH2] jsonKeyFilePath و[OAUTH2] scopes عند استخدام وضع "حساب الخدمة".
3. يجب ضبط [OAUTH2] clientId و[OAUTH2] clientSecret و[OAUTH2] refreshToken عند استخدام "وضع التطبيق".
4. يجب ضبط [GOOGLE_ADS] developerToken دائمًا.
5. في حال ضبطهما، يجب أن يكون [GOOGLE_ADS] loginCustomerId و[GOOGLE_ADS] linkedCustomerId رقمَين موجبَين.
6. في حال ضبطه، يجب أن يكون [CONNECTION] proxy عنوان URL صالحًا (راجِع الفلتر FILTER_VALIDATE_URL).
7. في حال ضبطه، يجب أن يكون [LOGGING] logLevel مستوى تسجيل PSR صالحًا مكتوبة بخط عريض، مثل INFO.
8. في حال ضبط [CONNECTION] transport، يجب أن يكون إمّا grpc أو rest.
9. إذا تم ضبط [CONNECTION] transport على grpc، يجب أن تكون بيئة gRPC متوافقة مع نقل البيانات (راجِع دليل transport).
10. يجب أن يكون [CONNECTION] grpcChannelIsSecure هو true عندما لا يتم ضبط [CONNECTION] transport على grpc.
11. لا يمكن ضبط [CONNECTION] grpcChannelCredential إلا عند ضبط [CONNECTION] transport على grpc.
12. لا يمكن ضبط [CONNECTION] grpcChannelCredential إلا عندما يكون [CONNECTION] grpcChannelIsSecure هو true.