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

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