المصادقة والتفويض

مثل واجهات 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". تم ضبط المكتبة على النحو التالي:

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

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

يُرجى الرجوع إلى دليل سير عمل حساب الخدمة لمعرفة المزيد.

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

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

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

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

GoogleAdsConfig googleAdsConfig = new GoogleAdsConfig()
{
    DeveloperToken = DEVELOPER_TOKEN,
    LoginCustomerId = LOGIN_CUSTOMER_ID,
    OAuth2ClientId = OAUTH_CLIENT_ID,
    OAuth2ClientSecret = OAUTH_CLIENT_SECRET,
    OAuth2RefreshToken = REFRESH_TOKEN,
};

GoogleAdsClient googleAdsClient = new GoogleAdsClient(googleAdsConfig);

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

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

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

GoogleAdsConfig googleAdsConfig = new GoogleAdsConfig()
{
    DeveloperToken = DEVELOPER_TOKEN,
    LoginCustomerId = LOGIN_CUSTOMER_ID,
    OAuth2ClientId = OAUTH_CLIENT_ID,
    OAuth2ClientSecret = OAUTH_CLIENT_SECRET,
    OAuth2RefreshToken = REFRESH_TOKEN,
};

GoogleAdsClient googleAdsClient = new GoogleAdsClient(googleAdsConfig);

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

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

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

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

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

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

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

تتيح مكتبة برامج .NET للعملاء أيضًا المصادقة باستخدام بيانات الاعتماد التلقائية للتطبيق.

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

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

لاستخدام بيانات الاعتماد التلقائية للتطبيق، اضبط الخيار UseApplicationDefaultCredentials على true في GoogleAdsConfig: يمكن إجراء ذلك بالطرق نفسها التي يتم بها ضبط خصائص الإعدادات الأخرى في مكتبة البرامج، أي في الرمز البرمجي أو في ملف الإعدادات أو باستخدام متغيرات البيئة.

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