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

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

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

للتعمّق في نموذج الوصول إلى واجهة برمجة تطبيقات "إعلانات Google"، يُرجى قراءة دليل نموذج الوصول إلى "إعلانات Google".

بيانات الاعتماد

يتطلّب الوصول إلى Google Ads API رمزًا مميّزًا للمطوّر وبيانات اعتماد OAuth 2.0، وفي بعض الحالات، رقم تعريف عميل تسجيل الدخول.

الرمز المميز للمطوِّر

يرتبط الرمز المميّز للمطوّر بحساب إداري ويمكن العثور عليه في واجهة الويب الخاصة بخدمة "إعلانات Google".

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

في مكتبة برامج العميل، يتم تحديد الرمز المميّز للمطوّر من خلال المفتاح api.googleads.developerToken في ملف ads.properties.

بيانات اعتماد OAuth 2.0

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

تتيح المكتبة ثلاثة مسارات:

  • مسار حساب الخدمة
  • مسار المصادقة لمستخدم واحد
  • مسار المصادقة لتعدد المستخدمين

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

رقم تعريف عميل تسجيل الدخول

يمكنك اختياريًا تحديد رقم تعريف عميل لحساب إداري يمنح إذن الوصول إلى حساب عرض الإعلانات. يجب تحديد هذا الخيار إذا كان إذن الوصول إلى حساب العميل يتم من خلال حساب إداري. ليس من الضروري تحديد جميع الحسابات الإدارية على المسار المؤدي إلى رقم تعريف العميل، بل فقط رقم تعريف الحساب الإداري الأعلى الذي تستخدمه لأذونات الوصول. لمزيد من التفاصيل، يُرجى الاطّلاع على المستندات ذات الصلة related documentation.

في مكتبة برامج العميل، يتم تحديد رقم تعريف عميل تسجيل الدخول من خلال المفتاح api.googleads.loginCustomerId في ملف ads.properties.

التهيئة

يمكنك ضبط مكتبة برامج العميل باستخدام ملف ads.properties أو متغيّرات البيئة أو بشكلٍ آلي. يركّز هذا الدليل على استخدام ملف ads.properties. يُرجى الاطّلاع على دليل التهيئة للحصول على تفاصيل حول جميع الخيارات.

في حال استخدام ملف ads.properties، ضعه في دليلك الرئيسي: ~/ads.properties.

مسارات عمل OAuth

هناك ثلاثة مسارات عمل شائعة تُستخدَم عند التعامل مع واجهة برمجة تطبيقات "إعلانات Google".

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

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

بعد الحصول على ملف JSON للمفتاح الخاص، أضِف ما يلي إلى ملف ads.properties:

api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

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

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

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

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

بعد الحصول على بيانات الاعتماد هذه، أضِف ما يلي إلى ملف ads.properties:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

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

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

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

أضِف ما يلي إلى ملف ads.properties:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

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

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

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

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

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

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

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

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

لاستخدام بيانات الاعتماد التلقائية للتطبيق، اضبط الخيار api.googleads.useApplicationDefaultCredentials على true في ملف ads.properties. عند استخدام بيانات الاعتماد التلقائية للتطبيق، يجب عدم ضبط معرّف العميل وسرّ العميل والرمز المميز لإعادة التحميل.