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

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

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

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

يتم ربط العمليات المتوافقة مباشرةً بأفعال HTTP في REST، كما هو موضَّح في عمليات 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 API جلسة المراجعة.

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

تقديم طلب

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