التهيئة

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