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

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

نمط الاتصال

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

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

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

في REST API التابع لـ Google، يحدد العميل إجراءً باستخدام فعل HTTP، مثل POST أو GET أو PUT أو DELETE. ويحدد موردًا حسب معرف موارد منتظم (URI) فريد عالميًا يكون على الشكل التالي:

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

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

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

‫REST في AdSense Management API

ترتبط العمليات المتوافقة مباشرةً بأفعال HTTP الخاصة بـ REST.

في ما يلي التنسيقات المحددة لمعرّفات الموارد المنتظمة الخاصة بـ 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
...

يمكنك العثور على تلخيص لمجموعة المعرّفات الكاملة لكل عملية متاحة في واجهة برمجة التطبيقات في مستند مرجع 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 2.0 نوعًا ما حسب نوع التطبيق الذي تكتبه. وتسري العملية التالية على كل أنواع التطبيقات:

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