المصادقة والتفويض

مثل واجهات 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 للمفتاح الخاص في الإعدادات. إذا كنت تستخدم ملف googleads.properties، أضِف ما يلي:

   jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
   

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

   export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH
   

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

   يُرجى الرجوع إلى دليل سير عمل حساب الخدمة لمعرفة المزيد.

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

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

1. امنح مستخدمًا واحدًا إذن الوصول إلى جميع الحسابات التي ستتم إدارتها باستخدام واجهة برمجة التطبيقات مع "إعلانات Google". ويتم عادةً منح المستخدم إذن الوصول إلى حساب إداري على 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 {client_id} -client_secret {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&client_id=...
   

   انتقِل إلى عنوان 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
developerToken=DEVELOPER_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_DEVELOPER_TOKEN=DEVELOPER_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
developerToken=DEVELOPER_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_DEVELOPER_TOKEN=DEVELOPER_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.