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

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

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

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

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

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

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

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

تتيح المكتبة ثلاث عمليات:

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

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

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

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

في مكتبة برامج العميل، يتم تحديد رقم تعريف العميل لتسجيل الدخول من خلال المفتاح 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
# 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 Ads API. هناك نهج شائع يتمثل في منح المستخدم حسابًا إداريًا على واجهة برمجة التطبيقات مع "إعلانات Google"، وربط جميع حسابات "إعلانات Google" ضمن هذا الحساب الإداري.
  2. يُشغِّل المستخدم أداة سطر أوامر، مثل gcloud CLI أو نموذج الرمز البرمجي 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

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

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

هذه هي العملية المقترَحة إذا كان تطبيقك يسمح للمستخدمين بتسجيل الدخول والموافقة على تطبيقك لإدارة حساباتهم على "إعلانات Google" نيابةً عنهم. The 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

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

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

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

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

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

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

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

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

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