این سند نحوه شروع به استفاده از API بلاگر را توضیح میدهد.
قبل از شروع
دریافت حساب گوگل
مطمئن شوید که یک حساب گوگل تنظیم کردهاید. توصیه میکنیم برای اهداف توسعه و آزمایش از یک حساب گوگل جداگانه استفاده کنید تا از از دست دادن تصادفی دادهها جلوگیری شود. اگر از قبل یک حساب آزمایشی دارید، کار تمام است؛ میتوانید برای تنظیم، ویرایش یا مشاهده دادههای آزمایشی خود به رابط کاربری بلاگر مراجعه کنید.
با بلاگر آشنا شوید
اگر با مفاهیم بلاگر آشنا نیستید، قبل از شروع کدنویسی، این سند را بخوانید و با رابط کاربری آن آزمایش کنید. این سند فرض میکند که شما با بلاگر، مفاهیم برنامهنویسی وب و فرمتهای دادههای وب آشنا هستید.
درباره تأیید درخواستها و شناسایی برنامه خود اطلاعات کسب کنید
وقتی برنامه شما درخواست دادههای خصوصی میکند، درخواست باید توسط یک کاربر احراز هویت شده که به آن دادهها دسترسی دارد، تأیید شود.
وقتی برنامه شما دادههای عمومی را درخواست میکند، نیازی به مجوزدهی درخواست نیست، اما باید با یک شناسه مانند کلید API همراه باشد.
برای اطلاعات بیشتر در مورد نحوهی تأیید درخواستها و استفاده از کلیدهای API، به بخش تأیید درخواستها و شناسایی برنامهی خود در سند «استفاده از API» مراجعه کنید.
پسزمینه API بلاگر
مفاهیم بلاگر
بلاگر بر اساس پنج مفهوم اساسی ساخته شده است:
- وبلاگها : مفهوم ریشهای API. یک وبلاگ شامل پستها و صفحات است. این بخش، محفظهای برای اطلاعات متای وبلاگ مانند نام و توضیحات وبلاگ است.
- پستها : یک پست وبلاگ، مطلبی قابل انتشار است که نویسنده وبلاگ ایجاد کرده است. این اطلاعات باید بهروز باشند و منعکسکننده آنچه نویسندگان میخواهند اکنون به جهان منتشر کنند، باشند. بدیهی است که با گذشت زمان، محتوای پستهای وبلاگ قدیمی شده و کمتر مرتبط میشوند.
- نظرات : نظر جایی است که افرادی غیر از نویسنده پست وبلاگ به آنچه نویسنده نوشته است واکنش نشان میدهند. همه چیز از آجر گرفته تا دسته گل.
- صفحات : یک صفحه مکانی برای محتوای ثابت، مانند اطلاعات بیوگرافی یا راههای تماس با کاربر است. این اطلاعات عموماً بیزمان هستند و خیلی اوقات تغییر نمیکنند.
- کاربران : کاربر کسی است که با بلاگر تعامل دارد، چه به عنوان نویسنده، چه مدیر یا فقط خواننده. برای وبلاگهای عمومی، خوانندگان ممکن است ناشناس باشند، اما در وبلاگهای خصوصی، خواننده باید توسط بلاگر شناسایی شود.
مدل داده API بلاگر
یک منبع، یک موجودیت دادهی منفرد با یک شناسهی منحصر به فرد است. رابط برنامهنویسی کاربردی بلاگر (Blogger JSON API) روی پنج نوع منبع کار میکند:
- منبع وبلاگها : نشاندهنده یک وبلاگ است.
- منبع پستها : نشاندهنده یک پست است؛ هر منبع پست، فرزند یک منبع وبلاگ است.
- منبع نظرات : نشاندهندهی یک نظر در مورد یک پست خاص است؛ هر منبع نظرات، فرزند منبع پستها است.
- منبع صفحات : نشاندهنده یک صفحه استاتیک است؛ هر منبع صفحات، فرزند یک منبع وبلاگ است.
- منبع کاربران : نشاندهنده یک کاربر غیر ناشناس است. این برای شناسایی نویسنده یک صفحه، پست یا نظر استفاده میشود.
مدل داده API بلاگر بر اساس گروههایی از منابع است که مجموعه نامیده میشوند:
- مجموعه وبلاگها
- الف
- مجموعه پستها
- یک مجموعه پستها شامل تمام منابع پستها در یک منبع وبلاگ خاص است.
- مجموعه نظرات
- یک مجموعه نظرات شامل تمام منابع نظرات درون یک منبع پست خاص است.
- مجموعه صفحات
- یک مجموعه صفحات شامل تمام منابع صفحات درون یک منبع وبلاگ خاص است.
- مجموعه کاربران
- یک مجموعه کاربر شامل تمام منابع کاربران در بلاگر است و بنابراین نمیتوان آن را فهرست کرد. یک کاربر میتواند منبع کاربران خود (اما نه هیچ کس دیگری) را با شناسه یا با استفاده از شناسه
selfبازیابی کند.
عملیات API بلاگر
همانطور که در جدول زیر توضیح داده شده است، میتوانید تعدادی از متدهای مختلف را روی مجموعهها و منابع در API بلاگر فراخوانی کنید.
| عملیات | توضیحات | نگاشتهای REST HTTP |
|---|---|---|
| فهرست | تمام منابع موجود در یک مجموعه را فهرست میکند. | به یک URI مجموعه GET . |
| دریافت | منبع خاصی را دریافت میکند. | به یک آدرس اینترنتی (URI) منبع GET . |
| دریافت بایآرل | یک منبع را دریافت میکند و آن را از طریق URL جستجو میکند. | با URL ارسال شده به عنوان پارامتر GET . |
| دریافت بای مسیر | با جستجوی یک منبع از طریق مسیر آن، آن را پیدا میکند. | با ارسال مسیر به عنوان پارامتر، GET . |
| لیست توسط کاربر | منابع متعلق به یک کاربر را فهرست میکند. | روی مجموعهای که متعلق به کاربر است GET . |
| جستجو | جستجوی منابع، بر اساس یک پارامتر پرسوجو. | روی یک URL جستجو، با پرسوجوی ارسالی به عنوان پارامتر، GET میشود. |
| درج | ایجاد یک منبع در یک مجموعه | روی یک URI مجموعه POST . |
| حذف | یک منبع را حذف میکند. | DELETE روی یک آدرس منبع (URI) اجرا میشود. |
| پچ | بهروزرسانی یک منبع، با استفاده از معانی وصله (Patch semantics). | PATCH روی یک آدرس منبع (URI). |
| بهروزرسانی | بهروزرسانی یک منبع. | روی یک URI منبع PUT . |
جدول زیر نشان میدهد که هر نوع منبع از کدام متدها پشتیبانی میکند. همه عملیات لیست و دریافت در وبلاگهای خصوصی نیاز به احراز هویت دارند.
نوع منبع | روشهای پشتیبانیشده | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| فهرست | دریافت | دریافت بایآرل | دریافت بای مسیر | لیست توسط کاربر | جستجو | درج | حذف | پچ | بهروزرسانی | |
| وبلاگها | خیر | بله | بله | خیر | بله | خیر | خیر | خیر | خیر | خیر |
| پستها | بله | بله | خیر | بله | خیر | بله | بله | بله | بله | بله |
| نظرات | بله | بله | خیر | خیر | خیر | خیر | خیر | خیر | خیر | خیر |
| صفحات | بله | بله | خیر | خیر | خیر | خیر | خیر | خیر | خیر | خیر |
| کاربران | خیر | بله | خیر | خیر | خیر | خیر | خیر | خیر | خیر | خیر |
سبکهای فراخوانی
چندین روش برای فراخوانی API وجود دارد:
- استفاده مستقیم از REST یا از طریق جاوا اسکریپت (بدون نیاز به کد سمت سرور)
- استفاده از کتابخانههای کلاینت
استراحت
REST سبکی از معماری نرمافزار است که رویکردی مناسب و سازگار برای درخواست و تغییر دادهها ارائه میدهد.
اصطلاح REST مخفف عبارت « Representational State Transfer » است. در زمینه APIهای گوگل، به استفاده از افعال HTTP برای بازیابی و تغییر نمایش دادههای ذخیره شده توسط گوگل اشاره دارد.
در یک سیستم RESTful، منابع در یک مخزن داده ذخیره میشوند؛ یک کلاینت درخواستی ارسال میکند که سرور یک عمل خاص (مانند ایجاد، بازیابی، بهروزرسانی یا حذف یک منبع) را انجام دهد، و سرور عمل را انجام داده و پاسخی را ارسال میکند، که اغلب به شکل نمایشی از منبع مشخص شده است.
در APIهای RESTful گوگل، کلاینت با استفاده از یک فعل 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 هستند.
REST در API بلاگر
عملیات پشتیبانیشدهی بلاگر، همانطور که در عملیات API بلاگر توضیح داده شده است، مستقیماً به افعال REST HTTP نگاشت میشوند.
قالب خاص برای URI های 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 های مورد استفاده و نتایج هر عملیات پشتیبانی شده در API در سند مرجع API بلاگر خلاصه شده است.
مثالها
وبلاگهایی را که کاربر احراز هویت شده به آنها دسترسی دارد، فهرست کنید:
GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY
پستها را از وبلاگ code.blogger.com که شناسه وبلاگ آن ۳۲۱۳۹۰۰ است، دریافت کنید:
GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY
REST از جاوا اسکریپت
شما میتوانید API بلاگر را از طریق جاوا اسکریپت، با استفاده از پارامتر پرسوجوی callback و با ارائه یک تابع فراخوانی، فراخوانی کنید. هنگامی که مرورگر اسکریپت را بارگذاری میکند، تابع فراخوانی اجرا میشود و پاسخ به تابع فراخوانی ارائه میشود. این رویکرد به شما امکان میدهد برنامههای غنی بنویسید که دادههای بلاگر را بدون نیاز به کد سمت سرور نمایش میدهند.
مثال زیر پس از جایگزینی YOUR-API-KEY با کلید API شما، پستی را از وبلاگ code.blogger.com بازیابی میکند.
<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.org مراجعه کنید.