واجهة برمجة تطبيقات Blogger: البدء

يوضّح هذا المستند كيفية بدء استخدام Blogger API.

قبل البدء

أنشئ حسابًا على Google

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

التعرّف على Blogger

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

مزيد من المعلومات حول منح الإذن للطلبات وتعريف تطبيقك

إذا طلب التطبيق بيانات خاصة، يجب أن تتم الموافقة على الطلب من قِبل مستخدم مصادَق عليه ولديه الإذن بالوصول إلى تلك البيانات.

عندما يطلب تطبيقك بيانات عامة، لا يحتاج الطلب إلى تفويض، ولكن يجب أن يكون مصحوبًا بمعرّف، مثل مفتاح واجهة برمجة التطبيقات.

للحصول على معلومات حول كيفية الموافقة على الطلبات واستخدام مفاتيح واجهة برمجة التطبيقات، يُرجى الاطّلاع على مقالة الموافقة على الطلبات وتحديد تطبيقك في مستند "استخدام واجهة برمجة التطبيقات".

معلومات أساسية عن Blogger API

مفاهيم Blogger

يستند Blogger إلى خمسة مفاهيم أساسية:

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

نموذج بيانات Blogger API

المورد هو كيان بيانات فردي يتضمّن معرّفًا فريدًا. تعمل واجهة Blogger JSON API على خمسة أنواع من الموارد:

مورد المدونات: يمثّل مدونة.
مورد المشاركات: يمثّل مشاركة، وكل مورد مشاركات هو عنصر فرعي من مورد المدونات.
مورد التعليقات: يمثّل تعليقًا على مشاركة معيّنة، وكل مورد تعليقات هو عنصر تابع لمورد المشاركات.
مورد الصفحات: يمثّل صفحة ثابتة، وكل مورد صفحات هو عنصر فرعي من مورد المدونات.
مورد المستخدمين: يمثّل مستخدمًا غير مجهول الهوية. تُستخدم هذه السمة لتحديد مؤلف صفحة أو مشاركة أو تعليق.

يتضمّن مورد المدونات نوعَين من الموارد الفرعية، وهما الصفحات والمشاركات.
قد يتضمّن مصدر المشاركات مصادر تعليقات ثانوية. — نظرة عامة على العلاقات بين المراجع

يستند نموذج بيانات Blogger API إلى مجموعات من الموارد تُعرف باسم المجموعات:

مجموعة المدونات: تتألف <span="apicollection">مجموعة المدونات من جميع المدونات التي يملك المستخدم حقوق الوصول إليها. يمكنك إدراج المدونات حسب المستخدم أو استرداد مدونة واحدة حسب رقم التعريف.</span="apicollection">
مجموعة المشاركات: تتألف مجموعة المنشورات من جميع موارد المنشورات ضمن مورد مدوّنات معيّن.
جمع التعليقات: تتألف مجموعة التعليقات من جميع موارد التعليقات ضمن مورد مشاركات معيّن.
مجموعة الصفحات: تتألف مجموعة الصفحات من جميع موارد الصفحات ضمن مورد مدوّنات معيّن.
مجموعة المستخدمين: تتألف مجموعة المستخدمين من جميع موارد المستخدمين على Blogger، وبالتالي لا يمكن إدراجها. يمكن للمستخدم استرداد مورد المستخدمين الخاص به (وليس موارد المستخدمين الآخرين) حسب رقم التعريف أو باستخدام المعرّف self.

عمليات Blogger API

يمكنك استدعاء عدد من الطرق المختلفة على المجموعات والمراجع في Blogger API، كما هو موضّح في الجدول التالي.

العملية	الوصف	عمليات ربط REST HTTP
list	تعرض هذه الطريقة جميع الموارد ضِمن مجموعة.	`GET` على معرّف الموارد المنتظم (URI) الخاص بمجموعة.
الحصول على	تعرض هذه الطريقة موردًا معيّنًا.	`GET` على معرّف الموارد المنتظم (URI) الخاص بمورد
getByUrl	يحصل هذا الإجراء على مورد من خلال البحث عنه باستخدام عنوان URL.	`GET` مع عنوان URL الذي تم تمريره كمَعلمة.
getByPath	تعرض هذه الطريقة موردًا من خلال البحث عنه حسب مساره.	`GET` مع المسار الذي تم تمريره كمَعلمة.
listByUser	تعرض هذه الطريقة قائمة بالموارد التي يملكها المستخدم.	`GET` في مجموعة يملكها مستخدم
search	البحث عن مراجع استنادًا إلى مَعلمة طلب بحث	`GET` في عنوان URL للبحث، مع إدخال طلب البحث كمعلَمة
إدراج	أنشئ مرجعًا في مجموعة.	`POST` على معرّف الموارد المنتظم (URI) الخاص بمجموعة.
حذف	لحذف مرجع	`DELETE` على معرّف الموارد المنتظم (URI) الخاص بمورد
patch	تعديل مورد باستخدام دلالات Patch	`PATCH` على معرّف الموارد المنتظم (URI) الخاص بمورد
تعديل	تعديل مورد	`PUT` على معرّف الموارد المنتظم (URI) الخاص بمورد

يوضّح الجدول أدناه الطرق المتوافقة مع كل نوع من أنواع الموارد. تتطلّب جميع عمليات القائمة والحصول في المدوّنات الخاصة المصادقة.

نوع المورد	الطُرق المتاحة
	list	الحصول على	getByUrl	getByPath	listByUser	search	إدراج	delete	patch	تعديل
المدوّنات	لا	نعم	نعم	لا	نعم	لا	لا	لا	لا	لا
المنشورات	نعم	نعم	لا	نعم	لا	نعم	نعم	نعم	نعم	نعم
التعليقات	نعم	نعم	لا	لا	لا	لا	لا	لا	لا	لا
الصفحات	نعم	نعم	لا	لا	لا	لا	لا	لا	لا	لا
المستخدِمون	لا	نعم	لا	لا	لا	لا	لا	لا	لا	لا

أنماط الاتصال

تتوفّر عدة طرق لاستدعاء واجهة برمجة التطبيقات:

استخدام REST مباشرةً أو من JavaScript (لا يلزم استخدام رمز من جهة الخادم)
استخدام مكتبات العملاء

REST

‫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 في Blogger API

ترتبط مباشرةً عمليات Blogger المتوافقة بأفعال HTTP الخاصة بـ REST، كما هو موضّح في عمليات Blogger API.

في ما يلي التنسيقات المحددة لمعرفات الموارد المنتظمة الخاصة بـ Blogger API:

https://www.googleapis.com/blogger/v3/users/userId
https://www.googleapis.com/blogger/v3/users/self
https://www.googleapis.com/blogger/v3/users/userId/blogs
https://www.googleapis.com/blogger/v3/users/self/blogs
https://www.googleapis.com/blogger/v3/blogs/blogId
https://www.googleapis.com/blogger/v3/blogs/byurl
https://www.googleapis.com/blogger/v3/blogs/blogId/posts
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v3/blogs/blogId/pages
https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId

يمكنك العثور على شرح كامل لمعرّفات الموارد الموحّدة المستخدَمة ونتائج كل عملية متاحة في واجهة برمجة التطبيقات في مستند مرجع Blogger API.

أمثلة

أدرِج المدوّنات التي يملك المستخدم المصادَق عليه أذونات الوصول إليها:

GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY

احصل على المشاركات من مدونة code.blogger.com التي تحمل رقم تعريف المدونة 3213900:

GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY

REST من JavaScript

يمكنك استدعاء Blogger API من JavaScript باستخدام المَعلمة callback الخاصة بطلب البحث وتوفير دالة ردّ اتصال. عندما يحمّل المتصفّح النص البرمجي، يتم تنفيذ دالة رد الاتصال ويتم تقديم الرد إلى دالة رد الاتصال. يتيح لك هذا الأسلوب كتابة تطبيقات متقدّمة تعرض بيانات Blogger بدون الحاجة إلى رمز من جهة الخادم.

يسترد المثال التالي مشاركة من المدونة code.blogger.com بعد استبدال YOUR-API-KEY بمفتاح واجهة برمجة التطبيقات.

<html>
  <head>
    <title>Blogger 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/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
  </body>
</html>

تنسيق البيانات

JSON

‫JSON‏ (JavaScript Object Notation) هو تنسيق بيانات شائع مستقل عن اللغة يقدّم تمثيلاً نصيًا بسيطًا عن بنى عشوائية للبيانات. لمزيد من المعلومات، انتقِل إلى json.org‏.

واجهة برمجة تطبيقات Blogger: البدء تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.