Authentication

على غرار واجهات برمجة تطبيقات Google الأخرى، تستخدم 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.