المصادقة والترخيص

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

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

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

سير عمل OAuth

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

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

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

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

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

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

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

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

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

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

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

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

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = userSession.LoginCustomerId,
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = userSession.RefreshToken
};

GoogleAdsClient client = new GoogleAdsClient(config);

اعتبارًا من Google.Ads.GoogleAds v27.0.0، يمكنك أيضًا إدخال كائن ICredential أو GoogleCredential تم ضبطه مسبقًا مباشرةً في GoogleAdsConfig باستخدام السمة Credentials.

يُرجى الرجوع إلى دليل سير عمل مصادقة تعدد المستخدمين لمزيد من المعلومات. تتضمّن مكتبة برامج ‎ .NET مثالَين على الرموز البرمجية كمرجع:

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

ماذا لو كان المستخدم يدير حسابات متعددة؟

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

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

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

تتيح مكتبة برامج ‎ .NET (الإصدار v24.1.0 والإصدارات الأحدث) أيضًا المصادقة باستخدام بيانات الاعتماد التلقائية للتطبيق.

ويُعدّ ذلك مفيدًا بشكل خاص للتطوير المحلي أو للتطوير في مواجهة واجهات برمجة تطبيقات Google المختلفة، حيث يمكنك إعادة استخدام بيانات الاعتماد نفسها، بشرط أن تتمكّن من الوصول إلى نطاقات OAuth 2.0 المطلوبة.

بالنسبة إلى Google Ads API، تأكَّد من أنّ بيانات الاعتماد التلقائية للتطبيق يمكنها الوصول إلى نطاق OAuth 2.0‏ https://www.googleapis.com/auth/adwords.

لاستخدام "بيانات الاعتماد التلقائية للتطبيق"، اضبط خيار UseApplicationDefaultCredentials على true في GoogleAdsConfig (أو اضبط متغيّر البيئة USE_APPLICATION_DEFAULT_CREDENTIALS=true عند تحميل الإعدادات باستخدام config.LoadFromEnvironmentVariables()):

GoogleAdsConfig config = new GoogleAdsConfig()
{
    UseApplicationDefaultCredentials = true,
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

يُرجى الرجوع إلى صفحة الإعداد لمزيد من التفاصيل حول الخيارات المتاحة لإعداد مكتبة برامج ‎ .NET.