التهيئة

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

حقول الإعداد

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

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] developerToken: (سيتم إيقافها نهائيًا في 9 سبتمبر 2026) رمز مطوّر Google Ads API. اختياري، تتجاهله خوادم واجهة برمجة التطبيقات بغض النظر عن إصدار مكتبة البرامج، وسيتم رفضه في رقم إصدار رئيسي مستقبلي من Google Ads API.
     • الإصدار v35.0.0 والإصدارات الأحدث: لا يلزم ذلك عند إعداد العميل (تمت إزالة عملية التحقّق من صحة الرمز المميز للمطوّر من جهة العميل على الجهاز المحلي في الإصدار GoogleAdsClientBuilder).
     • الإصدارات الأقدم من v35.0.0: مطلوبة للتحقّق من صحة الإعدادات المحلية من جهة العميل.
   • استبدِل [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. في الإصدارات الأقدم من v35.0.0، يتم التحقّق من [GOOGLE_ADS] developerToken من خلال عملية تأكّد محلية من جهة العميل (في الإصدار v35.0.0 والإصدارات الأحدث، لا يكون [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 (راجِع دليل النقل).
10. يجب أن تكون قيمة [CONNECTION] grpcChannelIsSecure هي true عندما لا تكون قيمة [CONNECTION] transport هي grpc (تتطلّب اتصالات REST دائمًا استخدام HTTPS).
11. لا يمكن ضبط [CONNECTION] grpcChannelCredential إلا عندما يكون [CONNECTION] transport مضبوطًا على grpc.
12. لا يمكن ضبط [CONNECTION] grpcChannelCredential إلا عندما تكون قيمة [CONNECTION] grpcChannelIsSecure هي true.