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

مثل واجهات 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 Ads.

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

يتطلّب الوصول إلى 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 APIs المختلفة، إذ يمكنك إعادة استخدام بيانات الاعتماد نفسها، شرط أن يكون بإمكانها الوصول إلى نطاقات OAuth 2.0 المطلوبة.

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

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