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

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

أسلوب الاتصال

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

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

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

في واجهات برمجة التطبيقات 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 معالجة جزء من عملية السماح بالنيابة عنك. وتتوفّر هذه المكتبات للعديد من لغات البرمجة، ويمكنك الاطّلاع على صفحة المكتبات والنماذج للحصول على مزيد من التفاصيل.

تقديم طلب

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