التهيئة

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

ملف الإعداد

يمكنك تخزين معظم إعدادات الضبط هذه في ملفات 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.