ملاحظة مهمة: سنتوقف عن إتاحة الإصدار 2.0 من واجهة برمجة التطبيقات JSON API في 30 أيلول (سبتمبر) 2024. لضمان استمرار الوظائف الأدائية، يجب تحديث تطبيقاتك التي تعتمد على الإصدار 2.0 من واجهة برمجة التطبيقات JSON API إلى أحدث إصدار من واجهة برمجة التطبيقات. للحصول على أحدث إصدار، استخدِم الروابط في شريط القوائم العلوي على يمين الصفحة.
يوضِّح هذا المستند كيفية استخدام الميزات الشائعة لواجهة برمجة التطبيقات Blogger JSON API باستخدام أسلوب الاستدعاء RESTful.
المحتويات
مقدمة
هذا المستند مخصّص للمطوّرين الذين يريدون كتابة تطبيقات يمكنها التفاعل مع Blogger JSON API. Blogger هي أداة ل إنشاء مواقع إلكترونية تتيح للمستخدمين نشر أفكارهم بشكلٍ مستمر.
إذا لم تكن على دراية بمفاهيم Blogger، ننصحك بقراءة البدء قبل بدء الترميز.
تفويض الطلبات وتحديد تطبيقك
يجب أن يحدد كل طلب يرسله تطبيقك إلى Blogger JSON API هوية تطبيقك لـ Google. هناك طريقتان لتحديد هوية تطبيقك: باستخدام رمز مميز OAuth 2.0 (الذي يمنح التفويض للطلب أيضًا) و/أو باستخدام مفتاح واجهة برمجة التطبيقات للتطبيق. في ما يلي كيفية تحديد الخيار الذي يجب استخدامه:
- إذا كان الطلب يتطلّب تفويضًا (مثل طلب بيانات خاصة لشخص معيّن)، على التطبيق تقديم رمز مميز لبروتوكول OAuth 2.0 مع الطلب. قد يقدّم التطبيق أيضًا مفتاح واجهة برمجة التطبيقات، ولكن ليس بالضرورة أن يقدّمه.
- إذا كان الطلب لا يتطلّب إذنًا (مثل طلب بيانات عامة)، يجب أن يقدّم التطبيق إما مفتاح واجهة برمجة التطبيقات أو رمز مميّز عبر بروتوكول OAuth 2.0، أو كليهما، أيًّا كان الخيار الأنسب لك.
لمحة عن بروتوكولات الموافقة على الطلبات
يجب أن يستخدم تطبيقك OAuth 2.0 للسماح بالطلبات. ولا يُسمح باستخدام أي بروتوكولات أخرى للموافقة على الطلبات.
ملاحظة: لا تتيح Blogger JSON API حاليًا تسجيل الدخول في الوقت نفسه الذي تطلب فيه إذن الوصول إلى البيانات (النموذج المختلط) أو تفويض السُلطة على مستوى النطاق (2LO).
الموافقة على الطلبات باستخدام OAuth 2.0
يجب أن يوافق مستخدم موثّق على الطلبات الموجّهة إلى Blogger JSON API للحصول على بيانات المستخدم غير العلنية.
تختلف تفاصيل عملية الموافقة على الطلبات لبروتوكول OAuth 2.0 نوعًا ما حسب نوع التطبيق الذي تكتبه. تنطبق العملية العامة التالية على كل أنواع التطبيقات:
- عند إنشاء تطبيقك، عليك تسجيله لدى Google. ويوفّر محرك بحث Google المعلومات التي ستحتاجها في ما بعد، مثل معرّف العميل وسر العميل.
- فعِّل واجهة برمجة التطبيقات Blogger JSON API في لوحة "الخدمات" ضمن Google APIs Console. (يمكنك تخطّي هذه الخطوة إذا لم يكن مُدرَجًا في وحدة التحكّم.)
- إذا احتاج التطبيق الدخول إلى بيانات المستخدِم، يطلب التطبيق من Google نطاقًا معيّنًا للوصول.
- يعرض Google مربّع حوار OAuth للمستخدم، ويطلب منه السماح لتطبيقك بطلب بعض بياناته.
- عند موافقة المستخدِم، يمنح Google تطبيقك رمز دخول قصير الأجل.
- يطلب تطبيقك بيانات المستخدِم، من خلال إرفاق رمز الدخول بالطلب.
- يعرض Google البيانات المطلوبة بعد أن يتأكّد من صلاحية طلبك والرمز المميّز.
تستلزم بعض التدفقات إجراء خطوات إضافية، مثل استخدام رموز مميزة للتحديث للحصول على رموز دخول جديدة. لمزيد من المعلومات التفصيلية حول عمليات الموافقة على الطلبات لأنواع مختلفة من التطبيقات، راجِع مستندات بروتوكول OAuth 2.0 في Google.
في ما يلي معلومات عن نطاق OAuth 2.0 في واجهة برمجة التطبيقات Blogger JSON API:
https://www.googleapis.com/auth/blogger
لطلب الوصول باستخدام بروتوكول OAuth 2.0، يحتاج تطبيقك إلى معلومات عن النطاق، بالإضافة إلى المعلومات التي يوفّرها Google أثناء تسجيل التطبيق (مثل معرِّف العميل و/أو سر العميل).
ملاحظة: يمكن لمكتبات عملاء Google APIs معالجة جزء من عملية السماح بالنيابة عنك. وتتوفّر هذه المكتبات للعديد من لغات البرمجة، ويمكنك الاطّلاع على صفحة "المكتبات والنماذج" للحصول على مزيد من التفاصيل.
الحصول على مفتاح واجهة برمجة التطبيقات واستخدامه
يجب أن تكون الطلبات المرسَلة إلى Blogger JSON API للحصول على البيانات العامة مصحوبة بأحد المعرّفات، والذي يمكن أن يكون مفتاح واجهة برمجة التطبيقات أو رمز مميّز للمصادقة.
للحصول على مفتاح واجهة برمجة التطبيقات، انتقِل إلى وحدة تحكّم واجهات برمجة التطبيقات. في paneالخدمات، تفعِّل [api_name]، وإذا ظهرت بنود الخدمة، اقرأها وقبلها.
بعد ذلك، انتقِل إلى لوحة الوصول إلى واجهة برمجة التطبيقات. يظهر مفتاح واجهة برمجة التطبيقات بالقرب من أسفل هذه اللوحة، في القسم بعنوان "الوصول البسيط إلى واجهة برمجة التطبيقات".
بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكن لتطبيقك إلحاق مَعلمة طلب البحث
key=yourAPIKey
بجميع عناوين URL الخاصة بالطلبات.
مفتاح واجهة برمجة التطبيقات آمن لتضمينه في عناوين URL، ولا يحتاج إلى أي ترميز.
العمل مع المدونات
استرداد مدونة
يمكنك استرداد معلومات عن مورد مدوّنات معيّن عن طريق إرسال طلب HTTP
GET
إلى معرّف الموارد المنتظم للمدوّنة. يكون تنسيق معرّف الموارد المنتظم لمورد مدونة على النحو التالي:
https://www.googleapis.com/blogger/v2/blogs/blogId
الطلب
يُرجى الاطّلاع على المثال أدناه:
GET https://www.googleapis.com/blogger/v2/blogs/2399953&key=YOUR-API-KEY
بما أنّه ليس على المستخدم مصادقة للوصول إلى مدوّنة علنية،
ليس عليك تقديم عنوان HTTP Authorization
مع هذا
GET
الطلب، ولكن في حال عدم تقديم هذا العنوان، عليك تقديم مفتاح واجهة برمجة التطبيقات.
تتوفّر أيضًا في Blogger مدونات خاصة تتطلّب المصادقة.
الردّ
إذا كان الطلب ناجحًا، يستجيب الخادم برمز حالة HTTP
200 OK
وبيانات المدوّنة:
200 OK { "kind": "blogger#blog", "id": "2399953", "name": "Blogger Buzz", "description": "The Official Buzz from Blogger at Google", "published": "2007-04-23T22:17:29.261Z", "updated": "2011-08-02T06:01:15.941Z", "url": "http://buzz.blogger.com/", "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953", "posts": { "totalItems": 494, "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts" }, "pages": { "totalItems": 2, "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/pages" }, "locale": { "language": "en", "country": "", "variant": "" } }
استرداد مدوّنات المستخدم
يمكنك استرداد قائمة بمدوّنات المستخدم من خلال إرسال طلب HTTP GET
إلى معرّف الموارد المنتظم لمجموعة المدونات:
https://www.googleapis.com/blogger/v2/users/userId/blogs
الطلب
في ما يلي مثال على طلب GET
يسرد مدوّنات
المستخدِم:
GET https://www.googleapis.com/blogger/v2/users/self/blogs
Authorization: /* OAuth 2.0 token here */
ملاحظة: يجب مصادقة المستخدم لإضافة مدوّناته، لذا عليك تقديم Authorization
HTTP
العنوان مع طلب GET
.
الردّ
إذا تمكّن الطلب من النجاح، يستجيب الخادم برمز حالة HTTP
200 OK
وتمثيل كامل لقائمة مدوّنات
المستخدم:
200 OK { "kind": "blogger#blogList", "items": [ { "kind": "blogger#blog", "id": "4967929378133675647", "name": "Brett's Test Blawg", "description": "", "published": "2010-10-06T23:33:31.662Z", "updated": "2011-08-08T06:50:02.005Z", "url": "http://brettmorgan-test-blawg.blogspot.com/", "selfLink": "https://www.googleapis.com/blogger/v2/blogs/4967929378133675647", "posts": { "totalItems": 13, "selfLink": "https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/posts" }, "pages": { "totalItems": 1, "selfLink": "https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/pages" }, "locale": { "language": "en", "country": "", "variant": "" } } ] }
العمل مع المشاركات
استرداد المشاركات من مدونة
يمكنك استرداد قائمة بالمشاركات من مدونة معيّنة عن طريق إرسال طلب
GET
إلى معرّف الموارد المنتظم لمجموعة المشاركات. يكون تنسيق معرّف URI لمجموعة Posts
على النحو التالي:
https://www.googleapis.com/blogger/v2/blogs/blogId/posts
الطلب
يُرجى الاطّلاع على المثال أدناه:
GET https://www.googleapis.com/blogger/v2/blogs/2399953/posts&key=YOUR-API-KEY
بما أنّه ليس على المستخدم مصادقة لاسترداد المشاركات من مدوّنة علنية،
ليس عليك تقديم عنوان HTTP Authorization
مع طلب GET
هذا، ولكن في حال عدم تقديم هذا العنوان، عليك تقديم مفتاح واجهة برمجة التطبيقات.
تتوفّر أيضًا في Blogger مدونات خاصة تتطلّب المصادقة.
الردّ
إذا تمكّن الطلب من إكمال العملية بنجاح، يستجيب الخادم برمز حالة HTTP
200 OK
وقائمة المشاركات:
200 OK { "kind": "blogger#postList", "nextPageToken": "CgkIChiAkceVjiYQ0b2SAQ", "prevPageToken": "CgkIChDBwrK3mCYQ0b2SAQ", "items": [ { "kind": "blogger#post", "id": "7706273476706534553", "blog": { "id": "2399953" }, "published": "2011-08-01T19:58:00.000Z", "updated": "2011-08-01T19:58:51.947Z", "url": "http://buzz.blogger.com/2011/08/latest-updates-august-1st.html", "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/7706273476706534553", "title": "Latest updates, August 1st", "content": "elided for readability", "author": { "id": "401465483996", "displayName": "Brett Wiltshire", "url": "http://www.blogger.com/profile/01430672582309320414", "image": { "url": "http://4.bp.blogspot.com/_YA50adQ-7vQ/S1gfR_6ufpI/AAAAAAAAAAk/1ErJGgRWZDg/S45/brett.png" } }, "replies": { "totalItems": "0", "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/7706273476706534553/comments" } }, { "kind": "blogger#post", "id": "6069922188027612413", elided for readability } ] }
استرداد مشاركة معيّنة
يمكنك استرداد مشاركة معيّنة من مدوّنة عن طريق إرسال طلب
GET
إلى عنوان URL لمورد المشاركات. يكون تنسيق معرّف الموارد المنتظم (URI) لمورد Posts
على النحو التالي:
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId
الطلب
يُرجى الاطّلاع على المثال أدناه:
GET https://www.googleapis.com/blogger/v2/blogs/2399953/posts/7706273476706534553&key=YOUR-API-KEY
بما أنّه ليس على المستخدم مصادقة لاسترداد المشاركات من مدوّنة علنية،
ليس عليك تقديم عنوان HTTP Authorization
مع طلب GET
هذا، ولكن في حال عدم تقديم هذا العنوان، عليك تقديم مفتاح واجهة برمجة التطبيقات.
تتوفّر أيضًا في Blogger مدونات خاصة تتطلّب المصادقة.
الردّ
إذا كان الطلب ناجحًا، يستجيب الخادم برمز حالة HTTP
200 OK
ومحتوى الرسالة:
200 OK { "kind": "blogger#post", "id": "7706273476706534553", "blog": { "id": "2399953" }, "published": "2011-08-01T19:58:00.000Z", "updated": "2011-08-01T19:58:51.947Z", "url": "http://buzz.blogger.com/2011/08/latest-updates-august-1st.html", "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/7706273476706534553", "title": "Latest updates, August 1st", "content": "elided for readability", "author": { "id": "401465483996", "displayName": "Brett Wiltshire", "url": "http://www.blogger.com/profile/01430672582309320414", "image": { "url": "http://4.bp.blogspot.com/_YA50adQ-7vQ/S1gfR_6ufpI/AAAAAAAAAAk/1ErJGgRWZDg/S45/brett.png" } }, "replies": { "totalItems": "0", "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/7706273476706534553/comments" } }
استخدام التعليقات
استرداد التعليقات على مشاركة
يمكنك استرداد قائمة بالتعليقات على مشاركة من خلال إرسال طلب
GET
إلى معرّف الموارد المنتظم لمجموعة التعليقات. يكون تنسيق عنوان URL الخاص بأحد
مجموعات التعليقات على النحو التالي:
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments
الطلب
يُرجى الاطّلاع على المثال أدناه:
GET https://www.googleapis.com/blogger/v2/blogs/2399953/posts/6069922188027612413/comments&key=YOUR-API-KEY
بما أنّه ليس على المستخدم مصادقة لاسترداد التعليقات من مدوّنة علنية،
ليس عليك تقديم عنوان HTTP Authorization
مع هذاGET
الطلب، ولكن إذا لم تقدّم هذا العنوان، عليك تقديم مفتاح واجهة برمجة التطبيقات.
تتوفّر أيضًا في Blogger مدونات خاصة تتطلّب المصادقة.
الردّ
إذا نجح الطلب، يستجيب الخادم برمز حالة HTTP
200 OK
وقائمة التعليقات:
200 OK { "kind": "blogger#commentList", "nextPageToken": "CgkIFBDwjvDXlyYQ0b2SARj9mZe9n8KsnlQ", "prevPageToken": "CgkIFBisvMGRlyYQ0b2SARj9mZe9n8KsnlQ", "items": [ { "kind": "blogger#comment", "id": "9200761938824362519", "post": { "id": "6069922188027612413" }, "blog": { "id": "2399953" }, "published": "2011-07-28T19:19:57.740Z", "updated": "2011-07-28T21:29:42.015Z", "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/6069922188027612413/comments/9200761938824362519", "content": "elided", "author": { "id": "530579030283", "displayName": "elided", "url": "elided", "image": { "url": "elided" } } }, { "kind": "blogger#comment", "id": "400101178920857170", elided for readability } ] }
استرداد تعليق معيّن
يمكنك استرداد تعليق معيّن من مشاركة من خلال إرسال طلب
GET
إلى معرّف الموارد الخاص بالتعليقات. يكون تنسيق معرّف URI لمورد ملف التعليقات على النحو التالي:
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments/commentId
الطلب
يُرجى الاطّلاع على المثال أدناه:
GET https://www.googleapis.com/blogger/v2/blogs/2399953/posts/6069922188027612413/comments/9200761938824362519&key=YOUR-API-KEY
بما أنّه ليس على المستخدم مصادقة لاسترداد التعليقات من مدوّنة علنية،
ليس عليك تقديم عنوان HTTP Authorization
مع هذاGET
الطلب، ولكن إذا لم تقدّم هذا العنوان، عليك تقديم مفتاح واجهة برمجة التطبيقات.
تتوفّر أيضًا في Blogger مدونات خاصة تتطلّب المصادقة.
الردّ
إذا كان الطلب ناجحًا، يستجيب الخادم برمز حالة HTTP
200 OK
وبيانات التعليق:
200 OK { "kind": "blogger#comment", "id": "9200761938824362519", "post": { "id": "6069922188027612413" }, "blog": { "id": "2399953" }, "published": "2011-07-28T19:19:57.740Z", "updated": "2011-07-28T21:29:42.015Z", "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/6069922188027612413/comments/9200761938824362519", "content": "elided", "author": { "id": "530579030283", "displayName": "elided", "url": "elided", "image": { "url": "elided" } } }
العمل مع "الصفحات"
استرداد صفحات مدونة
يمكنك استرداد قائمة بصفحات مدونة من خلال إرسال طلب
GET
إلى معرّف الموارد المنتظم (URI) لمجموعة الصفحات. يكون تنسيق معرّف URI لمجموعة صفحات على النحو التالي:
https://www.googleapis.com/blogger/v2/blogs/blogId/pages
الطلب
يُرجى الاطّلاع على المثال أدناه:
GET https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/pages&key=YOUR-API-KEY
بما أنّه ليس على المستخدم مصادقة لاسترداد الصفحات من مدوّنة علنية،
ليس عليك تقديم عنوان HTTP Authorization
مع طلب GET
هذا، ولكن إذا لم تقدِّم هذا العنوان، عليك تقديم مفتاح واجهة برمجة التطبيقات.
تتوفّر أيضًا في Blogger مدونات خاصة تتطلّب المصادقة.
الردّ
إذا تمكّن الطلب من إكمال العملية بنجاح، يستجيب الخادم برمز حالة HTTP
200 OK
وقائمة بالصفحات:
200 OK { "kind": "blogger#pageList", "items": [ { "kind": "blogger#page", "id": "273541696466681878", "blog": { "id": "4967929378133675647" }, "published": "2011-07-14T16:16:00.000Z", "updated": "2011-07-14T16:16:23.602Z", "url": "http://brettmorgan-test-blawg.blogspot.com/p/static-content.html", "selfLink": "https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/pages/273541696466681878", "title": "Static Content", "content": "elided for readability", "author": { "id": "901569848744", "displayName": "brett", "url": "http://www.blogger.com/profile/16258312240222542576", "image": { "url": "https://resources.blogblog.com/img/b16-rounded.gif" } } } ] }
استرداد صفحة معيّنة
يمكنك استرداد صفحة معيّنة من مدوّنة من خلال إرسال طلب
GET
إلى عنوان URL لمورد الصفحات. يكون تنسيق معرّف الموارد المنتظم لمورد صفحات Google على النحو التالي:
https://www.googleapis.com/blogger/v2/blogs/blogId/pages/pageId
الطلب
يُرجى الاطّلاع على المثال أدناه:
GET https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/pages/273541696466681878&key=YOUR-API-KEY
بما أنّه ليس على المستخدم مصادقة لاسترداد الصفحات من مدوّنة علنية،
ليس عليك تقديم عنوان HTTP Authorization
مع طلب GET
هذا، ولكن إذا لم تقدِّم هذا العنوان، عليك تقديم مفتاح واجهة برمجة التطبيقات.
تتوفّر أيضًا في Blogger مدونات خاصة تتطلّب المصادقة.
الردّ
إذا كان الطلب ناجحًا، يستجيب الخادم برمز حالة HTTP
200 OK
وبيانات الصفحة:
200 OK { "kind": "blogger#page", "id": "273541696466681878", "blog": { "id": "4967929378133675647" }, "published": "2011-07-14T16:16:00.000Z", "updated": "2011-07-14T16:16:23.602Z", "url": "http://brettmorgan-test-blawg.blogspot.com/p/static-content.html", "selfLink": "https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/pages/273541696466681878", "title": "Static Content", "content": "elided for readability", "author": { "id": "901569848744", "displayName": "brett", "url": "http://www.blogger.com/profile/16258312240222542576", "image": { "url": "https://resources.blogblog.com/img/b16-rounded.gif" } } }
العمل مع المستخدمين
استرداد مستخدم
يمكنك استرداد معلومات المستخدم من خلال إرسال طلب HTTP GET
إلى معرّف الموارد Users Resource URI:
https://www.googleapis.com/blogger/v2/users/userId
الطلب
في ما يلي مثال على طلب GET
يسرد مدوّنات
المستخدِم:
GET https://www.googleapis.com/blogger/v2/users/self
Authorization: /* OAuth 2.0 token here */
ملاحظة: يجب مصادقة المستخدم لعرض معلوماته، لذا عليك تقديم Authorization
HTTP
العنوان مع طلب GET
.
الردّ
إذا تمكّن الطلب من إتمام عملية الربط، يستجيب الخادم باستخدام رمز حالة HTTP
200 OK
ورابط يؤدي إلى قائمة بالمدوّنات الخاصة بالمستخدم:
200 OK { "kind": "blogger#user", "id": "901569848744", "selfLink": "https://www.googleapis.com/blogger/v2/users/901569848744", "blogs": { "selfLink": "https://www.googleapis.com/blogger/v2/users/901569848744/blogs" } }
مَعلمات طلب البحث العادية
يمكن استخدام مَعلمات طلب البحث التالية مع جميع الطرق وجميع الموارد في واجهات برمجة تطبيقات Blogger.
يمكنك الاطّلاع على مَعلمات طلب البحث التي تنطبق على جميع عمليات Blogger APIs في مَعلمات النظام.