ملاحظة مهمة: سنتوقف عن إتاحة الإصدار 2.0 من JSON API في 30 أيلول (سبتمبر) 2024. لضمان استمرار الوظائف الأدائية، يجب تحديث تطبيقاتك التي تعتمد على الإصدار 2.0 من واجهة برمجة التطبيقات JSON API إلى أحدث إصدار من واجهة برمجة التطبيقات. للحصول على أحدث إصدار، استخدِم الروابط في شريط القوائم العلوي على يمين الصفحة.
يشرح هذا المستند كيفية بدء استخدام Blogger JSON API.
المحتويات
مقدمة
هذا المستند مخصّص للمطوّرين الذين يريدون كتابة تطبيقات يمكنها التفاعل مع Blogger JSON API.
توفّر Blogger JSON API ميزات إضافية في الإصدار 2.0 من Blogger Data API. إذا كنت تريد استرداد البيانات من Blogger بتنسيق JSON بدلاً من XML، استخدِم Blogger JSON API. إذا كنت تريد استرداد البيانات بتنسيق XML، استخدِم Blogger Data API.
هذا الإصدار من Blogger JSON API مخصّص للقراءة فقط حاليًا، ولكننا ننشد إضافة إمكانات القراءة/الكتابة، بالإضافة إلى إمكانات أخرى. يمكنك طلب ميزات أخرى في منتدى مساعدة Blogger.
قبل البدء
الحصول على حساب Google
تأكَّد من إعداد حساب Google. ننصحك باستخدام حساب Google منفصل لأغراض التطوير والاختبار بهدف حمايتك من فقدان البيانات عن طريق الخطأ. إذا كان لديك حساب تجريبي، يمكنك الانتقال إلى واجهة مستخدم Blogger لإعداد بيانات الاختبار أو تعديلها أو عرضها.
التعرّف على Blogger
إذا لم تكن على دراية بمفاهيم Blogger، اقرأ هذا المستند و جرِّب واجهة المستخدم قبل بدء الترميز. يفترض هذا المستند أنّك على دراية بخدمة Blogger ومفاهيم برمجة الويب وتنسيقات بيانات الويب.
التعرّف على طلبات التفويض وتحديد تطبيقك
إذا طلب تطبيقك بيانات خاصة، يجب أن يوافق على هذا الطلب مستخدم موثّق يملك حق الوصول إلى تلك البيانات.
عندما يطلب تطبيقك بيانات عامة، لا يلزم أن يكون الطلب مفوَّضًا، ولكن يجب أن يكون مصحوبًا بمعرّف، مثل مفتاح واجهة برمجة التطبيقات.
للحصول على معلومات عن كيفية تفويض الطلبات واستخدام مفاتيح واجهة برمجة التطبيقات، يُرجى الاطّلاع على تفويض الطلبات وتحديد هوية تطبيقك في مستند "استخدام واجهة برمجة التطبيقات".
الخلفية في Blogger JSON API
مفاهيم Blogger
تستند خدمة Blogger إلى خمسة مفاهيم أساسية:
- المدوّنات: تتناول هذه المدوّنات المفهوم الأساسي لواجهة برمجة التطبيقات. تتضمّن المدونة مشاركات و صفحات. هذه هي الحاوية للمعلومات الوصفية للمدونة، مثل اسم المدونة ووصفها.
- المشاركات: مشاركة المدونة هي العنصر القابل للنشر الذي أنشأه مؤلف المدونة. من المفترض أن تكون هذه المعلومات حديثة وتعكس ما يريده المؤلفون نشره للعالم الآن. من المعروف أنّه بمرور الوقت، يصبح محتوى المشاركات في المدونات قديمًا وأقل صلة بموضوع البحث.
- التعليقات: التعليق هو المكان الذي يتفاعل فيه المستخدمون غير مؤلف مشاركات المدونة مع ما كتبه المؤلف. كل ما تريده، بدءًا من الطوب وحتى باقات الزهور
- الصفحات: الصفحة هي مكان للمحتوى الثابت، مثل المعلومات السيرة الذاتية أو طرق التواصل مع المستخدم. هذه هي المعلومات التي لا تتغيّر كثيرًا والتي لا تنتهي صلاحيتها.
- المستخدمون: المستخدم هو شخص يتفاعل مع Blogger، سواء كان يؤدي دور كاتب أو مشرف أو قارئ فقط. بالنسبة إلى المدونات المتاحة للجميع، يمكن أن يكون هوية القرّاء مجهولة، ولكن في المدونات الخاصة، يجب أن يحدّد Blogger هوية القرّاء.
نموذج بيانات Blogger JSON API
المورد هو عنصر بيانات فردي له معرّف فريد. تعمل واجهة برمجة تطبيقات Blogger JSON على خمسة أنواع من الموارد:
- مورد المدونات: يمثّل مدوّنة.
- مورد المشاركات: يمثّل مشاركة، وكلّ مورد مشاركات هو عنصر تابع لمورد مدوّنات.
- مرجع التعليقات: يمثّل تعليقًا على مشاركة معيّنة، وكل مرجع تعليقات هو عنصر تابع لمرجع المشاركات.
- مورد الصفحات: يمثّل صفحة ثابتة، وكلّ مورد صفحات هو عنصر تابع لمورد مدوّنات.
- مورد المستخدِمين: يمثّل مستخدِمًا غير مجهول. يتم استخدام هذه السمة لتحديد مؤلف الصفحة أو المشاركة أو التعليق.
يستند نموذج بيانات Blogger JSON API إلى مجموعات من الموارد تُعرف باسم المجموعات:
- مجموعة المدونات
- تتكون <span="apicollection">مجموعة المدونات من جميع المدونات التي يملك المستخدم حقوق الوصول إليها. يمكنك إدراج المدونات حسب المستخدم، أو استرداد مدوّنة واحدة باستخدام رقم التعريف.</span="apicollection">
- مجموعة المشاركات
- تتكون مجموعة المشاركات من كلّ موارد المشاركات ضمن مورد مدوّنات معيّن.
- مجموعة التعليقات
- تتكون مجموعة التعليقات من كلّ موارد التعليقات ضمن مورد مشاركات معيّن.
- مجموعة الصفحات
- تتكون مجموعة الصفحات من كلّ موارد الصفحات ضمن مورد مدوّنات معيّن.
- مجموعة المستخدِمين
- تتكون مجموعة المستخدمين من كل
موارد المستخدمين على Blogger، وبالتالي لا يمكن
إدراجها. يمكن للمستخدم استرداد مرجع المستخدمين الخاص به
(وليس مرجع أي مستخدم آخر) باستخدام رقم التعريف أو باستخدام المعرّف
self.
عمليات Blogger JSON API
يمكنك استدعاء طريقتَين مختلفتَين على المجموعات والموارد في Blogger JSON API، كما هو موضّح في الجدول التالي.
| العملية | الوصف | عمليات الربط في REST HTTP |
|---|---|---|
| list | يتم سرد جميع الموارد ضمن مجموعة. | GET على عنوان URL للمجموعة |
| الحصول | الحصول على مورد معيّن | GET على معرّف موارد منتظم (URI) |
يوضّح الجدول التالي الطرق المتاحة لكل نوع من أنواع الموارد. تتطلّب جميع عمليات العرض و الحصول على المدوّنات الخاصة المصادقة.
نوع المورد |
الطُرق المتوافقة |
|
|---|---|---|
| list | الحصول | |
| المدوّنات | نعم | نعم |
| المشاركات | نعم | نعم |
| التعليقات | نعم | نعم |
| الصفحات | نعم | نعم |
| المستخدِمون | لا | نعم |
أنماط الاتصال
هناك عدة طرق لاستدعاء واجهة برمجة التطبيقات:
- باستخدام REST مباشرةً أو من JavaScript (لا يلزم استخدام رمز من جهة الخادم)
- باستخدام مكتبات العملاء
REST
REST هو أسلوب لبنية البرامج يقدّم نهجًا ملائمًا ومتسقًا لطلب البيانات وتعديلها.
يشير اختصار REST إلى Representational State Transfer. في سياق Google APIs، يشير ذلك إلى استخدام أفعال HTTP لاسترداد وتعديل تمثيلات البيانات التي تخزّنها Google.
في نظام RESTful، يتم تخزين الموارد في مستودع بيانات، ويرسل العميل طلبًا بأن ينفِّذ الخادم إجراءً معيّنًا (مثل إنشاء مورد أو استرجاعه أو تعديله أو حذفه)، وينفِّذ الخادم الإجراء ويرسل ردًا، غالبًا في شكل تمثيل للمورد المحدّد.
في واجهات برمجة التطبيقات RESTful من Google، يحدّد العميل إجراءً باستخدام أحد أفعال HTTP، مثل POST أو GET أو PUT أو DELETE. ويحدّد موردًا باستخدام معرّف موارد منتظم فريد عالميًا بالشكل التالي:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
بما أنّ جميع موارد واجهة برمجة التطبيقات تتضمّن عناوين URL فريدة يمكن الوصول إليها من خلال HTTP، فإنّ بروتوكول REST يتيح ميزة تخزين البيانات مؤقتًا ويتم تحسينه للعمل مع البنية الأساسية الموزّعة للويب.
قد تكون تعريفات الطرق في مستندات معايير HTTP 1.1 مفيدة، إذ تتضمّن مواصفات GET وPOST وPUT وDELETE.
واجهة برمجة التطبيقات REST في Blogger JSON API
يتم ربط عمليات Blogger المتوافقة مباشرةً بأفعال REST HTTP، كما هو описан في عمليات Blogger JSON API.
التنسيق المحدّد لعناوين URL في Blogger JSON API هو:
https://www.googleapis.com/blogger/v2/users/userId https://www.googleapis.com/blogger/v2/users/self https://www.googleapis.com/blogger/v2/users/userId/blogs https://www.googleapis.com/blogger/v2/users/self/blogs https://www.googleapis.com/blogger/v2/blogs/blogId/posts https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments/commentId https://www.googleapis.com/blogger/v2/blogs/blogId/pages https://www.googleapis.com/blogger/v2/blogs/blogId/pages/pageId
يمكنك الاطّلاع على الشرح الكامل لعناوين URL المستخدَمة ونتائج كل عملية متوافقة في واجهة برمجة التطبيقات في مستند مرجع واجهة برمجة تطبيقات Blogger JSON.
في ما يلي مثالان على آلية عمل ذلك في Blogger JSON API.
يجب إدراج المدونات التي يملك المستخدم المُعتمَد حقوق الوصول إليها:
GET https://www.googleapis.com/blogger/v2/users/self/blogs?key=YOUR-API-KEY
احصل على المشاركات في مدونة code.blogger.com (التي تحمل رقم تعريف المدونة 3213900):
GET https://www.googleapis.com/blogger/v2/blogs/3213900?key=YOUR-API-KEY
استخدام واجهة برمجة التطبيقات REST من JavaScript
يمكنك استدعاء Blogger JSON API باستخدام REST من JavaScript، باستخدام مَعلمة طلب البحث
callback ودالة ردّ اتصال. يتيح لك ذلك
كتابة تطبيقات غنية تعرض بيانات Blogger بدون كتابة أي رمز على خادم.
يسترجع المثال التالي مشاركة من مدونة code.blogger.com (بعد استبدال YOUR-API-KEY بمفتاح واجهة برمجة التطبيقات).
<html>
<head>
<title>Blogger JSON API Example</title>
</head>
<body>
<div id="content"></div>
<script>
function handleResponse(response) {
document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content;
}
</script>
<script
src="https://www.googleapis.com/blogger/v2/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY "></script>
</body>
</html>تنسيق البيانات
JSON
JSON (JavaScript Object Notation) هو تنسيق بيانات شائع لا يعتمد على اللغة، ويقدّم تمثيلاً نصيًا بسيطًا لبنى البيانات العشوائية. لمزيد من المعلومات، يُرجى الاطّلاع على json.org.