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

على غرار واجهات Google APIs الأخرى، تستخدم Google Ads API بروتوكول OAuth 2.0 للمصادقة والتفويض. يتيح بروتوكول OAuth 2.0 لتطبيق عميل Google Ads API‏ ‎ .NET الوصول إلى حساب أحد المستخدمين على "إعلانات 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 code example كيفية إنشاء تطبيق ويب يحصل على مصادقة المستخدم في وقت التشغيل لإدارة حساباته على "إعلانات Google" نيابةً عنه. يستخدم التطبيق بيانات اعتماد OAuth 2.0 الخاصة بالمستخدم لاسترداد الحملات في حسابه على "إعلانات Google".
2. يوضّح نموذج الرمز البرمجي لسطر الأوامر GenerateUserCredentials كيفية الحصول على مصادقة المستخدم في وقت التشغيل لإدارة حساباته على "إعلانات Google" نيابةً عنه. يمكنك استخدام نموذج الرمز البرمجي هذا كمرجع لإنشاء تطبيقات متوافقة مع الكمبيوتر المكتبي تتطلّب مصادقة المستخدم.

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

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

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

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

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

يكون هذا مفيدًا بشكل خاص للتطوير المحلي أو التطوير باستخدام واجهات Google APIs المختلفة، لأنّه يمكنك إعادة استخدام بيانات الاعتماد نفسها، شرط أن تتمكّن من الوصول إلى نطاقات 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.