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

مثل واجهات 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 كيفية إنشاء تطبيق ويب يحصل على مصادقة المستخدم في وقت التشغيل لإدارة حساباته على "إعلانات 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، تأكَّد من أنّ بيانات الاعتماد التلقائية للتطبيق يمكنها الوصول إلى نطاق https://www.googleapis.com/auth/adwords OAuth 2.0.

لاستخدام "بيانات الاعتماد التلقائية للتطبيق"، اضبط الخيار 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.