ملاحظة مهمة: سنتوقف عن إتاحة الإصدار 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، وبمفاهيم برمجة الويب وتنسيقات بيانات الويب.
مزيد من المعلومات حول منح الإذن بالطلبات وتحديد هوية تطبيقك
عندما يطلب تطبيقك بيانات خاصة، يجب أن يتم السماح بالطلب من قِبل مستخدم مصادق عليه ولديه حق الوصول إلى هذه البيانات.
عندما يطلب تطبيقك بيانات علنية، لا يجب أن يكون الطلب مفوَّضًا، ولكن يجب أن يكون مقترنًا بمعرّف، مثل مفتاح واجهة برمجة التطبيقات.
للحصول على معلومات حول كيفية الموافقة على الطلبات واستخدام مفاتيح واجهة برمجة التطبيقات، يمكنك الاطّلاع على تفويض الطلبات وتحديد تطبيقك في مستند "استخدام واجهة برمجة التطبيقات".
خلفية واجهة برمجة التطبيقات JSON JSON في Blogger
مفاهيم Blogger
تم إنشاء Blogger استنادًا إلى خمسة مفاهيم أساسية:
- المدونات: المفهوم الجذري لواجهة برمجة التطبيقات. تتضمّن المدوّنة مشاركات وصفحات. هذه هي حاوية المعلومات الوصفية للمدوّنة، مثل اسم المدوّنة والوصف.
- المشاركات: مشاركة المدونة هي العنصر القابل للنشر الذي أنشأه مؤلف المدوّنة. من المفترض أن نحصل على هذه المعلومات في الوقت المناسب، وتعرض ما يريد المؤلفون نشره حول العالم الآن. من المفهوم أنّه بمرور الوقت، تصبح مدة المحتوى المنشور على المدونة أقل صلة باهتماماته.
- التعليقات: التعليق هو المكان الذي يتفاعل فيه المستخدمون، غير مؤلف مشاركة المدوّنة، مع ما كتبه. تمثّل هذه السمة كل شيء بدءًا من الطوب إلى الباقات.
- الصفحات: الصفحة هي مكان للمحتوى الثابت، مثل معلومات السيرة الذاتية أو طُرق التواصل مع المستخدم. وهذه المعلومات عامة، ولا تتغيّر في كثير من الأحيان.
- المستخدمون: المستخدم هو شخص يتفاعل مع Blogger، سواء كان كمؤلف أو مشرف أو مجرد قارئ. في المدونات العلنية، قد يكون القرّاء مجهولين، ولكن يجب أن يتعرّف Blogger على القارئ في المدونات الخاصة.
نموذج بيانات واجهة برمجة تطبيقات JSON JSON
المورد هو كيان بيانات فردي بمعرف فريد. تعمل واجهة برمجة التطبيقات Blogger JSON API على خمسة أنواع من الموارد:
- مورد للمدونات: يمثل المدونة.
- مصدر المشاركات: يمثل مشاركة، وكل مورد مشاركات هو عنصر ثانوي لمورد مدوّنات.
- مورد التعليقات: يمثل تعليقًا على مشاركة معينة، ويمثل كل مورد تعليقات عنصرًا ثانويًا من "مورد المشاركات".
- مورد الصفحات: يمثل صفحة ثابتة، وكل مورد صفحة هو عنصر ثانوي لمورد مدونات.
- مورد المستخدمين: يمثل مستخدمًا مجهولاً. يُستخدم هذا لتحديد مؤلف صفحة أو مشاركة أو تعليق.
يستند نموذج بيانات Blogger JSON API إلى مجموعات من الموارد تُسمى المجموعات:
- مجموعة المدونات
- تتألف مجموعة <span="apicollection">المدونات من جميع المدوّنات التي يملك المستخدم إمكانية الوصول إليها. يمكنك إدراج مدونات حسب المستخدم، أو استرداد مدوّنة واحدة باستخدام رقم التعريف.</span="apicollection">
- مجموعة مختارات المشاركات
- تتألف مجموعة المشاركات من جميع موارد المشاركات ضمن مورد مدوّنات محدّد.
- مجموعة مختارات التعليقات
- تتألف مجموعة التعليقات من كل موارد التعليقات ضمن مورد المشاركات المحدّد.
- مجموعة الصفحات
- تتألف مجموعة الصفحات من جميع موارد الصفحات ضمن مورد مدوّنات محدّد.
- مجموعة مختارات المستخدمين
- تتألف مجموعة "المستخدمون" من جميع
موارد المستخدمين على Blogger، وبالتالي لا يمكن
إدراجها. يمكن للمستخدم استرداد مورد المستخدمين الخاص به (ولكن لا يمكن لأي مستخدم آخر) استرداده باستخدام رقم التعريف أو باستخدام المعرّف
self.
عمليات واجهة برمجة التطبيقات JSON JSON في Blogger
يمكنك استدعاء طريقتين مختلفتين في المجموعات والموارد في Blogger JSON API، كما هو موضح في الجدول التالي.
| العملية | الوصف | تعيينات REST HTTP |
|---|---|---|
| list | يسرد جميع الموارد ضمن مجموعة. | GET على معرّف الموارد المنتظم (URI) للمجموعة. |
| الحصول على | الحصول على مورد محدّد | GET على معرّف الموارد المنتظم (URI) للمورد. |
يعرض الجدول أدناه الطرق المتوافقة مع كل نوع من أنواع الموارد. تتطلب جميع عمليات قوائم والحصول على المدونات الخاصة مصادقة.
نوع المورد |
الطُرق المتوافقة |
|
|---|---|---|
| list | الحصول على | |
| المدونات | نعم | نعم |
| المشاركات | نعم | نعم |
| التعليقات | نعم | نعم |
| الصفحات | نعم | نعم |
| المستخدِمون | لا | نعم |
أنماط المكالمات
هناك عدة طرق لاستدعاء واجهة برمجة التطبيقات:
- استخدام REST مباشرةً أو من JavaScript (لا حاجة إلى استخدام رمز من جهة الخادم)
- استخدام مكتبات البرامج
راحة
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 في واجهة برمجة تطبيقات Blogger JSON
ترتبط عمليات Blogger المتوافقة مباشرةً بأفعال REST HTTP، كما هو موضّح في عمليات Blogger JSON API.
التنسيق المحدد لمعرّفات الموارد المنتظمة (URI) لواجهة برمجة تطبيقات Blogger JSON هو:
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
تم تلخيص الشرح الكامل لعناوين URI المستخدمة ونتائج كل عملية متوافقة في واجهة برمجة التطبيقات في المستند مرجع واجهة برمجة تطبيقات 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.