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

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

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

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

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

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.