مهم : ما پشتیبانی از v2.0 JSON API را در 30 سپتامبر 2024 متوقف خواهیم کرد. برای اطمینان از ادامه عملکرد، برنامه‌های کاربردی خود را که به v2.0 JSON API متکی هستند به آخرین نسخه 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 در حال حاضر فقط خواندنی است. با این حال، ما در حال برنامه ریزی برای اضافه کردن قابلیت های خواندن/نوشتن و همچنین قابلیت های دیگر هستیم. به راحتی می توانید ویژگی های دیگر را در انجمن راهنمای بلاگر درخواست کنید.
قبل از شروع
یک حساب Google دریافت کنید
مطمئن شوید که یک حساب Google راه اندازی کرده اید. توصیه می کنیم از یک حساب Google جداگانه برای اهداف توسعه و آزمایش استفاده کنید تا از از دست رفتن تصادفی داده محافظت کنید. اگر قبلاً یک حساب آزمایشی دارید، همه چیز آماده است. می توانید برای راه اندازی، ویرایش یا مشاهده داده های آزمایشی خود از رابط کاربری Blogger دیدن کنید.
با بلاگر آشنا شوید
اگر با مفاهیم بلاگر آشنا نیستید، این سند را بخوانید و قبل از شروع به کدنویسی، رابط کاربری را آزمایش کنید. این سند فرض می‌کند که شما با بلاگر، مفاهیم برنامه‌نویسی وب و قالب‌های داده‌های وب آشنا هستید.
درباره مجوز دادن به درخواست ها و شناسایی برنامه خود بیاموزید
هنگامی که برنامه شما داده های خصوصی را درخواست می کند، درخواست باید توسط یک کاربر احراز هویت که به آن داده ها دسترسی دارد مجاز باشد.
هنگامی که برنامه شما داده های عمومی را درخواست می کند، درخواست نیازی به مجوز ندارد، اما باید با یک شناسه مانند کلید API همراه شود.
برای کسب اطلاعات در مورد نحوه مجوز دادن به درخواست‌ها و استفاده از کلیدهای API، به تأیید درخواست‌ها و شناسایی برنامه خود در سند استفاده از API مراجعه کنید.
پس زمینه بلاگر JSON API
مفاهیم بلاگر
بلاگر بر اساس پنج مفهوم اساسی ساخته شده است:
- وبلاگ ها : مفهوم ریشه ای API. یک وبلاگ دارای پست ها و صفحات است. این محفظه ای برای متا اطلاعات وبلاگ مانند نام وبلاگ و توضیحات است.
- پست ها : یک پست وبلاگ آیتم قابل انتشاری است که نویسنده وبلاگ ایجاد کرده است. این اطلاعات قرار است به موقع باشد، و منعکس کننده آنچه نویسندگان می خواهند در حال حاضر در جهان منتشر کنند. قابل درک است که با گذشت زمان، پست های وبلاگ پیرتر می شود و کمتر مرتبط می شود.
- نظرات : نظر مکانی است که در آن افراد غیر از نویسنده پست وبلاگ به آنچه نویسنده نوشته است واکنش نشان می دهند. همه چیز از آجر گرفته تا دسته گل.
- صفحات : صفحه مکانی برای محتوای ثابت، مانند اطلاعات بیوگرافی، یا راه های تماس با کاربر است. این اطلاعات عموماً بی‌زمان است که اغلب تغییر نمی‌کند.
- کاربران : کاربر شخصی است که با بلاگر تعامل دارد، خواه به عنوان نویسنده، مدیر، یا فقط یک خواننده عمل کند. برای وبلاگ های عمومی، خوانندگان ممکن است ناشناس باشند، اما در وبلاگ های خصوصی، خواننده باید توسط Blogger شناسایی شود.
مدل داده Blogger JSON API
یک منبع یک موجودیت داده منفرد با یک شناسه منحصر به فرد است. Blogger JSON API بر روی پنج نوع منبع کار می کند:
- منبع وبلاگ ها : نشان دهنده یک وبلاگ است.
- منبع پست ها : یک پست را نشان می دهد. هر منبع پست فرزند یک منبع وبلاگ است.
- منبع نظرات : نمایانگر یک نظر در مورد یک پست خاص است. هر منبع نظرات فرزند یک منبع پست است.
- منابع صفحات : یک صفحه ثابت را نشان می دهد. هر منبع صفحات فرزند یک منبع وبلاگ است.
- منابع کاربران : نشان دهنده یک کاربر غیر ناشناس است. این برای شناسایی نویسنده یک صفحه، پست یا نظر استفاده می شود.
مدل داده‌های Blogger JSON API مبتنی بر گروه‌هایی از منابع است که مجموعه‌ها نامیده می‌شوند:
- مجموعه وبلاگ ها
- الف
- مجموعه پست ها
- مجموعه پست ها شامل تمام منابع پست ها در یک منبع وبلاگ خاص است.
- مجموعه نظرات
- مجموعه نظرات شامل تمام منابع نظرات در یک منبع پست خاص است.
- مجموعه صفحات
- مجموعه صفحات شامل تمام منابع صفحات در یک منبع بلاگ خاص است.
- مجموعه کاربران
- یک مجموعه کاربران از تمام منابع کاربران در بلاگر تشکیل شده است و بنابراین نمی توان آنها را فهرست کرد. یک کاربر می تواند منبع کاربران خود را (اما هیچ کس دیگری) با شناسه یا با استفاده از
selfشناسه بازیابی کند.
عملیات JSON API Blogger
همانطور که در جدول زیر توضیح داده شده است، می توانید دو روش مختلف را در مجموعه ها و منابع در Blogger JSON API فراخوانی کنید.
| عملیات | توضیحات | REST نگاشت HTTP |
|---|---|---|
| فهرست | تمام منابع موجود در یک مجموعه را فهرست می کند. | GET URI مجموعه. |
| دریافت کنید | منبع خاصی را دریافت می کند. | GET URI منبع. |
جدول زیر نشان می دهد که کدام روش توسط هر نوع منبع پشتیبانی می شود. همه عملیات لیست و دریافت در وبلاگ های خصوصی نیاز به احراز هویت دارند.
نوع منبع | روش های پشتیبانی شده | |
|---|---|---|
| فهرست | دریافت کنید | |
| وبلاگ ها | بله | بله |
| پست ها | بله | بله |
| نظرات | بله | بله |
| صفحات | بله | بله |
| کاربران | نه | بله |
سبک های فراخوانی
چندین راه برای فراخوانی API وجود دارد:
- استفاده از REST به طور مستقیم یا از جاوا اسکریپت (بدون نیاز به کد سمت سرور)
- استفاده از کتابخانه های مشتری
استراحت
REST سبکی از معماری نرم افزار است که یک رویکرد راحت و سازگار برای درخواست و اصلاح داده ها ارائه می دهد.
اصطلاح REST مخفف " انتقال دولت نمایندگی " است. در زمینه Google API ها، به استفاده از افعال HTTP برای بازیابی و اصلاح نمایش داده های ذخیره شده توسط Google اشاره دارد.
در یک سیستم RESTful، منابع در یک فروشگاه داده ذخیره می شوند. یک سرویس گیرنده درخواستی را ارسال می کند که سرور یک عمل خاص را انجام دهد (مانند ایجاد، بازیابی، به روز رسانی یا حذف یک منبع)، و سرور این عمل را انجام می دهد و پاسخی را می فرستد، اغلب به شکل یک نمایش از منبع مشخص شده.
در API های RESTful Google، مشتری با استفاده از یک فعل HTTP مانند POST ، GET ، PUT ، یا DELETE ، اقدامی را مشخص می کند. این یک منبع را توسط یک URI منحصر به فرد جهانی به شکل زیر مشخص می کند:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
از آنجایی که همه منابع API دارای URI های منحصر به فرد قابل دسترسی با HTTP هستند، REST ذخیره داده را فعال می کند و برای کار با زیرساخت های توزیع شده وب بهینه شده است.
ممکن است تعاریف روش را در مستندات استانداردهای HTTP 1.1 مفید بیابید. آنها شامل مشخصات GET ، POST ، PUT و DELETE هستند.
در Blogger JSON API استراحت کنید
عملیات پشتیبانی شده Blogger به طور مستقیم به افعال HTTP REST، همانطور که در عملیات Blogger JSON API توضیح داده شده است، نگاشت.
فرمت خاص برای Blogger JSON API URI عبارتند از:
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 های استفاده شده و نتایج هر عملیات پشتیبانی شده در API در سند مرجع JSON API Blogger خلاصه شده است.
در اینجا چند نمونه از نحوه عملکرد این در 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 از جاوا اسکریپت
می‌توانید با استفاده از REST از جاوا اسکریپت، با استفاده از پارامتر پرس و جوی callback و تابع پاسخ به تماس، Blogger JSON API را فراخوانی کنید. این به شما امکان می دهد برنامه های کاربردی غنی بنویسید که داده های بلاگر را بدون نوشتن کد سمت سرور نمایش می دهند.
مثال زیر یک پست را از وبلاگ code.blogger.com بازیابی می کند (پس از اینکه YOUR-API-KEY با کلید API خود جایگزین کردید).
<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 مراجعه کنید.