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

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

فهم نموذج الوصول إلى "إعلانات Google"

للعمل بفعالية مع Google Ads API، عليك فهم آلية عمل نموذج الوصول إلى "إعلانات Google". راجِع دليل نموذج الوصول إلى "إعلانات Google".

سير عمل OAuth

هناك ثلاثة أنواع شائعة من سير العمل يتم استخدامها عند العمل مع Google Ads API.

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

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

في ما يلي كيفية إعداد OAuth2 للوصول إلى واجهة برمجة التطبيقات باستخدام بيانات الاعتماد الخاصة بك مع حساب خدمة في مكتبة برامج Perl:

1. إنشاء بيانات اعتماد OAuth2:

   اتّبِع التعليمات لإنشاء حساب خدمة وملف مفتاح JSON.

2. إعداد مكتبة البرامج:

   اضبط مسار JSON للمفتاح الخاص (وimpersonatedEmail اختياري في حال استخدام تفويض Google Workspace على مستوى النطاق) في الإعدادات. إذا كنت تستخدم ملف googleads.properties، أضِف ما يلي:

   jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
   # Optional unless using Google Workspace domain-wide delegation:
   impersonatedEmail=IMPERSONATED_EMAIL
   loginCustomerId=LOGIN_CUSTOMER_ID
   

   إذا كنت تستخدم متغيّرات البيئة، أضِف ما يلي إلى إعدادات Bash أو بيئتها:

   export GOOGLE_ADS_JSON_KEY_FILE_PATH=KEY_FILE_PATH
   export GOOGLE_ADS_IMPERSONATED_EMAIL=\
   IMPERSONATED_EMAIL
   export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID
   

   نقطة أساسية: عند تحميل الإعدادات، تبحث المكتبة أولاً عن بيانات الاعتماد من مسارات OAuth2 لتطبيقات الويب أو أجهزة الكمبيوتر المكتبي، ثم تستخدمها إذا تم العثور عليها. إذا أردت استخدام حساب خدمة للمصادقة، تأكَّد من أنّ بيانات الاعتماد الخاصة بالمسارات الأخرى غير متوفّرة في الإعدادات.

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

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

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

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

تنفّذ الخطوات التالية مثالاً تفاعليًا على الرمز البرمجي، ما يتطلّب منك بعد ذلك تقديم إدخال.

1. في الوحدة الطرفية، شغِّل مثال generate_user_credentials.pl في دليل examples. يمكنك تعديل قيم INSERT_XXX_HERE في المثال قبل تشغيله أو استخدام وسيطات سطر الأوامر -client_id لمعرّف العميل و-client_secret لسر العميل.

   perl generate_user_credentials.pl \
     -client_id OAUTH_CLIENT_ID \
     -client_secret OAUTH_CLIENT_SECRET
   

2. يطلب منك نموذج الرمز هذا الانتقال إلى عنوان URL حيث يجب منح التطبيق الإذن بالوصول إلى حسابك على "إعلانات Google" نيابةً عنك.

   Paste this url in your browser:
   https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline...
   

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

   

   ستتم إعادة توجيهك إلى صفحة تتضمّن رسالة تشير إلى نجاح عملية التفويض.

   Authorization code was successfully retrieved.
   

3. ارجع إلى وحدة التحكّم التي تشغّل فيها نموذج الرمز البرمجي. سيظهر لك أنّ نموذج الرمز البرمجي قد اكتمل ويعرض الرمز المميز لإعادة التحميل وبعض التعليمات، تليها التعليمات التي عليك اتّباعها لضبط مكتبة العميل:

   Replace the following keys and values in your googleads.properties
   configuration file:
   
   clientId=***********************apps.googleusercontent.com
   clientSecret=****
   refreshToken=****
   

4. اضغط على Ctrl + C لإنهاء العملية. بعد ذلك، انسخ الرمز المميز لإعادة التحميل الذي تم إنشاؤه مع معرّف العميل والرمز السري للعميل إلى ملف googleads.properties أو احفظه في مكان آخر لاستخدامه عند إنشاء مثيل للمكتبة في وقت التشغيل.

يمكن إعداد المكتبة باستخدام بيانات اعتماد OAuth 2.0 الخاصة بالمستخدم من خلال ضبط ما يلي في googleads.properties:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

يمكنك بدلاً من ذلك استخدام متغيّرات البيئة:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

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

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

بالنسبة إلى Perl، يمكنك عادةً تنفيذ مسار تطبيق ويب حيث يتعامل تطبيقك مع إعادة توجيه OAuth 2.0 وإدارة الرموز المميّزة. يُجري المستخدم المصادقة من خلال تطبيقك، ويخزّن تطبيقك الرمز المميز لإعادة التحميل الخاص بالمستخدم ويستخدمه لإجراء طلبات بيانات من واجهة برمجة التطبيقات نيابةً عنه.

إنّ إعدادات استخدام بيانات الاعتماد التي تم الحصول عليها هي نفسها المستخدمة في مسار مصادقة المستخدم الواحد:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

يمكنك بدلاً من ذلك استخدام متغيّرات البيئة:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

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

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

1. يوضّح مثال get_account_hierarchy.pl كيفية استرداد قائمة بجميع الحسابات ضمن حساب إداري على "إعلانات Google".
2. يوضّح مثال list_accessible_customers.pl كيفية استرداد قائمة بجميع الحسابات التي يمكن للمستخدم الوصول إليها مباشرةً. يمكن بعد ذلك استخدام هذه الحسابات كقيم صالحة لإعداد loginCustomerId في ملف googleads.properties أو متغير بيئة GOOGLE_ADS_LOGIN_CUSTOMER_ID.