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

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

قبل البدء

الحصول على حساب Google

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

التعرف على Blogger

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

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

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

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

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

خلفية Blogger API

مفاهيم Blogger

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

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

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

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

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

يستند نموذج بيانات واجهة برمجة تطبيقات Blogger إلى مجموعات من الموارد، تُسمى المجموعات:

مجموعة المدونات
تتضمّن مجموعة المدوّنات &ltltspanspanquot;apicollection">blogs كل المدوّنات التي يملك المستخدم حق الوصول إليها. يمكنك إدراج المدوّنات حسب المستخدم أو استرداد مدونة واحدة حسب رقم التعريف.</spanrlquot;apicollection">
جمع المشاركات
تشتمل مجموعة مشاركات على جميع موارد المشاركات ضمن مورد مدونات معيّن.
جمع التعليقات
تشتمل مجموعة التعليقات على جميع موارد التعليقات ضمن مورد مشاركات معيّن.
جمع الصفحات
تتكوّن مجموعة الصفحات من جميع موارد الصفحات ضمن مورد مدونات معيّن.
جمع المستخدمين
تتضمن مجموعة المستخدمين جميع موارد المستخدمين على Blogger، وبالتالي لا يمكن إدراجها. يمكن للمستخدم استرداد مورد المستخدمين الخاص به (ولكن لا شيء آخر's) حسب رقم التعريف أو باستخدام المعرّف self.

عمليات واجهة برمجة تطبيقات Blogger

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

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

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

نوع المورد
الطرق المتوافقة
القائمة get getByUrl getByPath listByUser بحث Google insert حذف رمز تصحيح تحديث
المدونات لا نعم نعم لا نعم لا لا لا لا لا
المشاركات نعم نعم لا نعم لا نعم نعم نعم نعم نعم
التعليقات نعم نعم لا لا لا لا لا لا لا لا
الصفحات نعم نعم لا لا لا لا لا لا لا لا
المستخدمون لا نعم لا لا لا لا لا لا لا لا

أنماط المكالمات

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

راحة

وتُعدّ REST أسلوبًا من بنية البرامج التي توفّر منهجًا مريحًا ومتسقًا لطلب البيانات وتعديلها.

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

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

في واجهات برمجة تطبيقات RESTful في Google\u3d، يحدد العميل إجراءً باستخدام فعل 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 API

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

في ما يلي التنسيق المحدّد لمعرّفات الموارد المنتظمة (URI) في 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

ويمكن الاطّلاع على الشرح الكامل لمعرّفات الموارد المنتظمة (URI) المستخدمة والنتائج لكل عملية معتمدة في واجهة برمجة التطبيقات في المستند مرجع واجهة برمجة تطبيقات Blogger.

أمثلة

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

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 من 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.