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

مثل واجهات 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، وفي بعض الحالات، رقم تعريف عميل لتسجيل الدخول.

بيانات اعتماد 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=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

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

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

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

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

بالنسبة إلى التطبيقات المتعددة المستخدمين، يمكنك تخزين معرِّف عميل OAuth 2.0 وسر العميل الخاص بتطبيقك في ads.properties (أو في مخزن إعدادات آخر)، مع تخزين الرمز المميز لإعادة التحميل لكل مستخدم نهائي بشكل آمن في قاعدة بيانات تطبيقك وتمريره آليًا في وقت التشغيل عند إنشاء UserCredentials وGoogleAdsClient:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_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 (أو استدعِ .enableApplicationDefaultCredentials() في GoogleAdsClient.newBuilder()). عند استخدام "بيانات الاعتماد التلقائية للتطبيق"، يجب عدم ضبط معرّف العميل وسرّ العميل والرمز المميّز لإعادة التحميل.