يجب أن يتم تفويض جميع طلبات Google Ad Manager API من خلال OAuth2، وهو معيار مفتوح يتيح للمستخدمين منح أذونات للتطبيقات التابعة لجهات خارجية، ما يتيح للتطبيق التفاعل مع خدمات الويب نيابةً عن المستخدم. يتيح بروتوكول OAuth2 لتطبيق العميل الذي يستخدم Ad Manager API الوصول إلى حساب المستخدم على "مدير إعلانات Google" بدون الحاجة إلى التعامل مع اسم المستخدم أو كلمة المرور أو تخزينهما.
إنشاء بيانات اعتماد OAuth2
اتّبِع الخطوات التالية لإنشاء بيانات اعتماد OAuth2.
1. تحديد نوع المصادقة
راجِع الجدول أدناه لمعرفة نوع المصادقة الأنسب لتطبيقك على واجهة برمجة التطبيقات في "إدارة إعلانات Google":
| اختيار نوع مصادقة OAuth2 | |
|---|---|
| حساب الخدمة |
اختَر هذا الخيار إذا كنت بحاجة إلى الوصول إلى بياناتك على "إدارة إعلانات Google" فقط. مزيد من المعلومات |
| تطبيق الويب |
اختَر هذا الخيار إذا كنت تريد المصادقة كمستخدم يمنح تطبيقك الإذن بالوصول إلى بياناته على "مدير إعلانات Google". مزيد من المعلومات |
2. إنشاء بيانات اعتماد OAuth2
بعد تحديد نوع المصادقة، انقر على علامة التبويب المناسبة أدناه واتّبِع التعليمات لإنشاء بيانات اعتماد OAuth2:
- افتح صفحة بيانات الاعتماد في Google API Console.
- من القائمة المنسدلة الخاصة بالمشروع، اختَر إنشاء مشروع جديد، وأدخِل اسمًا للمشروع، ويمكنك اختياريًا تعديل رقم تعريف المشروع المقدَّم. انقر على إنشاء.
- في صفحة "بيانات الاعتماد"، انقر على إنشاء بيانات اعتماد، ثم اختَر مفتاح حساب الخدمة.
- اختَر حساب خدمة جديد، ثم اختَر JSON.
- انقر على إنشاء لتنزيل ملف يحتوي على مفتاح خاص.
- افتح صفحة بيانات الاعتماد في Google API Console.
- من القائمة المنسدلة الخاصة بالمشروع، اختَر إنشاء مشروع جديد، وأدخِل اسمًا للمشروع (يمكنك أيضًا تعديل رقم تعريف المشروع المقدَّم)، ثم انقر على إنشاء.
- في صفحة "بيانات الاعتماد"، انقر على إنشاء بيانات اعتماد، ثم انقر على معرّف عميل OAuth.
- قد يُطلب منك ضبط اسم منتج في صفحة شاشة طلب الموافقة. في هذه الحالة، انقر على إعداد شاشة طلب الموافقة، وقدِّم المعلومات المطلوبة، ثم انقر على حفظ للرجوع إلى صفحة بيانات الاعتماد.
- اختَر تطبيق الويب في حقل نوع التطبيق. اتّبِع التعليمات لإدخال مصادر JavaScript أو معرّفات الموارد المنتظمة (URI) لإعادة التوجيه أو كليهما.
- انقر على إنشاء.
- في الصفحة التي تظهر، انسخ معرّف العميل وسر العميل إلى الحافظة، لأنّك ستحتاج إليهما عند إعداد مكتبة العميل.
3- ضبط شبكة "مدير إعلانات Google"
إذا كنت مطوّرًا تابعًا لجهة خارجية، قد تحتاج إلى أن ينفّذ عميلك هذه الخطوة نيابةً عنك.
- انتقِل إلى شبكة "مدير الإعلانات".
- انقر على علامة التبويب المشرف.
- تأكَّد من تفعيل إمكانية الوصول إلى واجهة برمجة التطبيقات.
- انقر على الزر إضافة مستخدم حساب خدمة.
- املأ النموذج باستخدام البريد الإلكتروني لحساب الخدمة. يجب منح مستخدم حساب الخدمة أذونات للوصول إلى الكيانات كما لو كان مستخدم حساب الخدمة سيصل إلى الكيانات على واجهة المستخدم.
- انقر على الزر حفظ. من المفترض أن تظهر رسالة تؤكّد إضافة حساب الخدمة.
- يمكنك عرض مستخدمي حساب الخدمة الحاليين من خلال الانتقال إلى علامة التبويب "المستخدمون" ثم النقر على فلتر حساب الخدمة.
- انتقِل إلى شبكة "مدير الإعلانات".
- انقر على علامة التبويب المشرف.
- تأكَّد من تفعيل إمكانية الوصول إلى واجهة برمجة التطبيقات.
4. ضبط مكتبة برامج واستخدامها
اتّبِع الدليل المناسب أدناه لاستخدام بيانات الاعتماد في مكتبة العميل:
جافا
NET.
Python
PHP
Ruby
إذا اخترت عدم استخدام إحدى مكتبات العملاء، عليك تنفيذ عملية حساب الخدمة أو تطبيق الويب الخاصة ببروتوكول OAuth2 بنفسك.
وراء الكواليس
تتولّى مكتبات برامجنا تلقائيًا معالجة التفاصيل الموضّحة أدناه، لذا يمكنك تخطّي هذه الفقرة إذا كنت مهتمًا بمعرفة ما يحدث وراء الكواليس. هذا القسم مخصّص للمستخدمين المتقدّمين الذين يعرفون مواصفات OAuth2 ولديهم خبرة في استخدام OAuth2 مع Google APIs.
عنوان طلب HTTP
يجب أن يتضمّن عنوان HTTP في كل طلب إلى Ad Manager API رمزًا مميزًا للوصول بهذا الشكل:
Authorization: Bearer ACCESS_TOKEN
على سبيل المثال:
POST … HTTP/1.1 Host: … Authorization: Bearer 1/fFAGRNJru1FTz70BzhT3Zg Content-Type: text/xml;charset=UTF-8 Content-Length: … <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope"> … </soap:Envelope>
النطاق
يمكن أن يمنح رمز الدخول الواحد درجات متفاوتة من الوصول إلى واجهات برمجة تطبيقات متعددة. معلَمة متغيرة باسم scope تتحكّم في مجموعة الموارد والعمليات التي يسمح بها رمز الدخول. أثناء طلب رمز الدخول، يرسل تطبيقك قيمة واحدة أو أكثر في المَعلمة scope.
يتضمّن "مدير إعلانات Google" نطاقًا واحدًا فقط، كما هو موضّح أدناه. يجب إجراء التفويض على مستوى المستخدم داخل المنتج.
| النطاق | الأذونات |
|---|---|
https://www.googleapis.com/auth/admanager |
عرض حملاتك وإدارتها على "إدارة إعلانات Google" |