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

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

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

لمزيد من المعلومات حول نموذج الوصول إلى Google Ads API، يُرجى الاطّلاع على دليل نموذج الوصول إلى "إعلانات 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 Ads API، واتّبِع التعليمات الخاصة بالمسار الذي يلبي احتياجاتك على أفضل وجه للحصول على بيانات الاعتماد المطلوبة.

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

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

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

التهيئة

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

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

سير عمل OAuth

هناك ثلاث طرق شائعة لسير العمل تُستخدَم عند التعامل مع Google Ads API.

تدفّق حساب الخدمة

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

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