Authentication

مثل واجهات Google APIs الأخرى، تستخدم Google Ads API بروتوكول OAuth 2.0 للمصادقة والتفويض. يتيح بروتوكول OAuth 2.0 لتطبيق عميل واجهة برمجة التطبيقات Google Ads API الوصول إلى حساب "إعلانات Google" الخاص بالمستخدم بدون الحاجة إلى معالجة معلومات تسجيل دخول المستخدم أو تخزينها.

فهم نموذج الوصول إلى "إعلانات Google"

للعمل بفعالية مع Google Ads API، عليك فهم آلية عمل نموذج الوصول إلى "إعلانات Google". راجِع دليل نموذج الوصول إلى "إعلانات Google".

سير عمل OAuth

هناك ثلاثة أنواع شائعة من سير العمل يتم استخدامها عند العمل مع Google Ads API.

مسار حساب الخدمة

هذا هو سير العمل المقترَح إذا كان سير العمل لا يتطلّب أي تفاعل بشري. يتطلّب سير العمل هذا خطوة ضبط، حيث يضيف المستخدم حساب خدمة إلى حسابه على "إعلانات Google". يمكن للتطبيق بعد ذلك استخدام بيانات اعتماد حساب الخدمة لإدارة حساب المستخدم على "إعلانات Google".

يمكن ضبط مكتبة PHP على النحو التالي:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withJsonKeyFilePath('INSERT_PATH_TO_JSON_KEY_FILE_HERE')
    // Optional in v32.1.0 and later (defaults to
    // 'https://www.googleapis.com/auth/adwords').
    ->withScopes('https://www.googleapis.com/auth/adwords')
    ->build();

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

يمكنك الرجوع إلى دليل سير عمل حساب الخدمة لمزيد من المعلومات.

عملية مصادقة المستخدم الواحد

يمكن استخدام سير العمل هذا إذا لم تتمكّن من استخدام حسابات الخدمة. يتطلّب سير العمل هذا خطوتَي إعداد:

1. امنح مستخدمًا واحدًا إذن الوصول إلى جميع الحسابات التي ستتم إدارتها باستخدام Google Ads API. من الطرق الشائعة منح المستخدم إذن الوصول إلى حساب إداري على Google Ads API، وربط جميع حسابات "إعلانات Google" بهذا الحساب الإداري.
2. بعد ذلك، يشغّل هذا المستخدم أداة سطر أوامر مثل GenerateUserCredentials لتفويض تطبيقك لإدارة جميع حساباته على "إعلانات Google" نيابةً عنه.

يمكن إعداد المكتبة باستخدام بيانات اعتماد OAuth 2.0 الخاصة بالمستخدم على النحو التالي:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

لمزيد من المعلومات، يُرجى الرجوع إلى دليل سير عمل مصادقة المستخدم الواحد.

عملية مصادقة المستخدمين المتعددين

هذا هو سير العمل المقترَح إذا كان تطبيقك يتيح للمستخدمين تسجيل الدخول ومنح الإذن لتطبيقك بإدارة حساباتهم على "إعلانات Google" نيابةً عنهم. ينشئ تطبيقك بيانات اعتماد مستخدم OAuth 2.0 ويديرها ديناميكيًا لكل جلسة مستخدم تمت مصادقته. يمكن إعداد المكتبة باستخدام بيانات اعتماد المستخدم الذي سجّل الدخول على النحو التالي:

// Construct credentials dynamically per authenticated user session.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken($userRefreshToken)
    ->build();

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

لمزيد من المعلومات، يُرجى الرجوع إلى دليل سير عمل المصادقة المتعددة المستخدمين.

بيانات الاعتماد التلقائية للتطبيق

تتيح مكتبة برامج PHP أيضًا المصادقة باستخدام بيانات الاعتماد التلقائية للتطبيق (ADC). عندما لا يتم ضبط بيانات اعتماد وضع التطبيق (clientId أو clientSecret أو refreshToken) أو وضع حساب الخدمة (jsonKeyFilePath) على OAuth2TokenBuilder، يعود استدعاء build() تلقائيًا إلى "بيانات الاعتماد التلقائية للتطبيق":

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

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

إدارة حسابات متعددة

من الشائع أن يدير المستخدم أكثر من حساب واحد على "إعلانات Google"، إما من خلال الوصول المباشر إلى الحسابات أو من خلال حساب إداري على "إعلانات Google". توفّر مكتبة برامج PHP نماذج الرموز البرمجية التالية التي توضّح كيفية التعامل مع هذه الحالات:

1. يوضّح مثال الرمز البرمجي GetAccountHierarchy كيفية استرداد قائمة بجميع الحسابات ضمن حساب إداري على "إعلانات Google".
2. يوضّح مثال الرمز البرمجي ListAccessibleCustomers كيفية استرداد قائمة بجميع الحسابات التي يمكن للمستخدم الوصول إليها مباشرةً. ويمكن بعد ذلك استخدام هذه الحسابات كقيم صالحة لإعداد loginCustomerId.