تقديم طلبات مباشرة

وننصحك باستخدام مكتبات العملاء والنماذج لتنفيذ عملية التنفيذ. ومع ذلك، إذا كانت للدمج مع واجهة برمجة التطبيقات متطلبات خاصة، مثل استخدام لغة غير متاحة، يمكنك تقديم طلبات مباشرة كما هو موضّح أدناه.

نمط الاتصال

REST هي نمط من بنية البرامج التي توفر نهجًا مريحًا ومتسقًا لطلب البيانات وتعديلها.

يشير الاختصار REST إلى "نقل الولاية التمثيلية". يشير سياق Google APIs إلى استخدام أفعال HTTP لاسترداد تمثيلات البيانات التي خزّنتها Google وتعديلها.

في نظام RESTful، يتم تخزين الموارد في مخزن بيانات؛ يرسل العميل طلبًا بأن يؤدي الخادم إجراءً معينًا (مثل إنشاء مورد أو استرداده أو تحديثه أو حذفه)، وينفذ الخادم الإجراء ويرسل استجابة، غالبًا في شكل تمثيل للمورد المحدد.

في واجهات برمجة التطبيقات RESTful الخاصة بـ Google، يحدّد العميل إجراءً باستخدام فعل HTTP، مثل POST أو GET أو PUT أو DELETE. ويحدد موردًا بواسطة معرف موارد منتظم (URI) فريد عالميًا بالنموذج التالي:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

ونظرًا لأن جميع موارد واجهة برمجة التطبيقات تحتوي على عناوين URI فريدة يمكن الوصول إليها عبر HTTP، تعمل REST على تخزين البيانات مؤقتًا ويتم تحسينها للعمل مع البنية الأساسية الموزعة للويب.

يمكنك الاستفادة من تعريفات الطرق في مستندات معايير HTTP 1.1 التي تتضمّن مواصفات GET وPOST وPUT وDELETE.

REST في واجهة برمجة تطبيقات AdSense Management

يتم ربط العمليات المتوافقة مباشرةً بأفعال REST HTTP، كما هو موضّح في عمليات AdSense Management API.

التنسيق المحدد لعناوين URI لواجهة AdSense Management API هو:

https://adsense.googleapis.com/v2/resourceID?parameters

حيث resourceID هو معرّف برنامج الإعلانات أو الوحدة الإعلانية أو قناة عنوان URL أو القناة المخصّصة أو مجموعة التقارير، وparameters هي أي معلمات لتطبيقها على طلب البحث.

يتيح لك تنسيق إضافات مسارات resourceID تحديد المورد الذي تعمل عليه حاليًا، على سبيل المثال:

https://adsense.googleapis.com/v2/accounts/account_id/adclients
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits/adUnitId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/urlchannels
...

يتم تلخيص المجموعة الكاملة من معرّفات الموارد المنتظمة (URI) لكل عملية معتمدة في واجهة برمجة التطبيقات في مرجع واجهة برمجة تطبيقات AdSense Management.

في ما يلي مثالان على آلية عمل ذلك في AdSense Management API.

إدراج برامج الإعلانات:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/

سرد الوحدات الإعلانية في برنامج الإعلانات ca-pub-1234567890123456:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/ca-pub-1234567890123456/adunits

تنسيق البيانات

JSON (JavaScript Object Notation) هو تنسيق بيانات شائع ومستقل عن اللغة يوفّر تمثيلاً نصيًا بسيطًا لهياكل البيانات العشوائية. لمزيد من المعلومات، يمكنك الاطّلاع على json.org.

تفويض الطلبات

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

يجب أن يحتوي كل طلب يرسله تطبيقك إلى AdSense Management API على رمز تفويض مميز. ويساعد الرمز المميز محرك البحث Google في التعرّف على تطبيقك.

نبذة عن بروتوكولات التفويض

يجب أن يستخدم تطبيقك OAuth 2.0 للسماح بالطلبات. ولا يُسمح باستخدام أي بروتوكولات أخرى للموافقة على الطلبات. إذا كان تطبيقك يستخدم ميزة تسجيل الدخول باستخدام حساب Google، ستتم معالجة بعض جوانب عملية الموافقة على الطلبات نيابةً عنك.

الموافقة على الطلبات باستخدام OAuth 2.0

يجب أن يصادق مستخدم تمت مصادقته على جميع الطلبات الموجّهة إلى AdSense Management API.

يتم تسهيل هذه العملية باستخدام معرِّف عميل OAuth.

الحصول على معرِّف عميل بروتوكول OAuth

يمكنك بدلاً من ذلك إنشاء حساب في صفحة "بيانات الاعتماد".

تختلف تفاصيل عملية الموافقة على الطلبات لبروتوكول OAuth 2.0 نوعًا ما حسب نوع التطبيق الذي تكتبه. وتسري العملية التالية على كل أنواع التطبيقات:

  1. إذا احتاج التطبيق الدخول إلى بيانات المستخدِم، يطلب التطبيق من Google نطاقًا معينًا للدخول.
  2. يعرض Google شاشة الموافقة للمستخدم، ويطلب منه السماح لتطبيقك بطلب بعض بياناته.
  3. عند موافقة المستخدِم، يمنح Google تطبيقك رمز دخول قصير الأجل.
  4. يطلب تطبيقك بيانات المستخدِم، من خلال إرفاق رمز الدخول بالطلب.
  5. يعرض Google البيانات المطلوبة بعد تحققه من صلاحية طلبك والرمز المميز.

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

في ما يلي معلومات عن نطاق OAuth 2.0 لواجهة AdSense Management API:

النطاق المعنى
https://www.googleapis.com/auth/adsense إذن وصول للقراءة/الكتابة إلى بيانات AdSense
https://www.googleapis.com/auth/adsense.readonly إذن بالاطّلاع على بيانات AdSense

لطلب الدخول باستخدام بروتوكول OAuth 2.0، يحتاج التطبيق معلومات عن النطاق، بالإضافة إلى المعلومات التي يوفّرها Google عند تسجيل التطبيق (مثل معرِّف العميل وسر العميل).

نصيحة: يمكن لمكتبات عملاء Google APIs معالجة جزء من عملية السماح بالنيابة عنك. وتتوفّر هذه المكتبات للعديد من لغات البرمجة، ويمكنك الاطّلاع على صفحة المكتبات والنماذج للحصول على مزيد من التفاصيل.

تقديم طلب

تتمثل الخطوة الأخيرة في تقديم طلب البيانات من واجهة برمجة التطبيقات. راجِع المستندات المرجعية للحصول على معلومات محدّدة.