التهيئة

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

ملاحظة: تلغي الإعدادات الديناميكية المحدّدة صراحةً الإعدادات التي تم تحميلها من متغيّرات البيئة أو ملفات إعدادات INI استنادًا إلى الترتيب الذي يتم فيه استدعاء طرق الإنشاء.

ملف الإعداد

يمكنك تخزين معظم إعدادات الضبط هذه في ملفات ضبط 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_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->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 (تكون تلقائيًا https://www.googleapis.com/auth/adwords في الإصدار v32.1.0 والإصدارات الأحدث، وهي مطلوبة في الإصدارات الأقدم من v32.1.0 أو عند استخدام نطاقات مخصّصة، ولا تتم قراءتها من متغيّر بيئة بواسطة fromEnvironmentVariables()).
     • [OAUTH2] impersonatedEmail: عنوان بريد إلكتروني اختياري لانتحال الهوية عند استخدام التفويض على مستوى نطاق Google Workspace
   • وضع "بيانات الاعتماد التلقائية للتطبيق":
     • في حال عدم ضبط حقول "وضع التطبيق" أو "وضع حساب الخدمة"، يعود OAuth2TokenBuilder تلقائيًا إلى "بيانات الاعتماد التلقائية للتطبيق" (ADC).
2. الحقول التي يستخدمها "GoogleAdsClientBuilder":
   • ‫[GOOGLE_ADS] loginCustomerId: رقم تعريف العميل المفوَّض لاستخدامه في الطلب
   • ‫[GOOGLE_ADS] linkedCustomerId: الرقم التعريفي للعميل المرتبط
   • ‫[GOOGLE_ADS] endpoint: نقطة نهاية اختيارية بديلة لخادم Google Ads API
   • ‫[LOGGING] logFilePath: مسار مخرجات التسجيل
   • ‫[LOGGING] logLevel: مستوى التسجيل
   • ‫[CONNECTION] proxy: عنوان URL للخادم الوكيل المستخدَم للاتصال بالإنترنت
   • ‫[CONNECTION] transport: بروتوكول نقل البيانات في الشبكة (grpc أو rest).
   • ‫[CONNECTION] grpcChannelIsSecure: تشير إلى ما إذا كانت قناة gRPC آمنة.
   • ‫[CONNECTION] grpcChannelCredential: بيانات اعتماد قناة gRPC
   • ‫[CONNECTION] unaryMiddlewares: البرامج الوسيطة الأحادية
   • ‫[CONNECTION] streamingMiddlewares: البرامج الوسيطة للبث
   • ‫[CONNECTION] grpcInterceptors: تمثّل هذه السمة معترضات gRPC.

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

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

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