مهم : پشتیبانی از API Google Data v2.0 را در 30 سپتامبر 2024 متوقف خواهیم کرد. برای اطمینان از ادامه عملکرد، برنامه‌های کاربردی خود را که به API Google Data v2.0 متکی هستند به آخرین نسخه API به‌روزرسانی کنید. برای آخرین نسخه، از پیوندهای موجود در نوار ناوبری سمت چپ استفاده کنید. توجه: در حالی که برخی از درخواست‌های GET (مانند پست‌های فهرست‌بندی) همچنان به عنوان URL فید پشتیبانی می‌شوند، تفاوت‌های جزئی در رفتار آنها وجود دارد. برای اطلاعات دقیق، به مستندات راهنمای Blogger مراجعه کنید.
Blogger Data API به برنامه های مشتری اجازه می دهد تا محتوای Blogger را در قالب فیدهای Google Data API مشاهده و به روز کنند.
برنامه مشتری شما می تواند از Blogger Data API برای ایجاد پست های وبلاگ جدید، ویرایش یا حذف پست های وبلاگ موجود و پرس و جو برای پست های وبلاگی که با معیارهای خاصی مطابقت دارند استفاده کند.
این سند علاوه بر ارائه پیش‌زمینه‌ای در مورد قابلیت‌های Blogger Data API، نمونه‌هایی از تعاملات پایه داده API با استفاده از کتابخانه سرویس گیرنده جاوا را ارائه می‌کند. اگر علاقه مند به درک بیشتر در مورد پروتکل اساسی که کتابخانه استفاده می کند، به بخش پروتکل این راهنمای توسعه دهنده مراجعه کنید.
مطالب
مخاطب
این سند برای برنامه نویسانی در نظر گرفته شده است که می خواهند برنامه های کلاینت جاوا بنویسند که می توانند با بلاگر تعامل داشته باشند.
این سند فرض می‌کند که شما ایده‌های کلی پشت پروتکل Google Data APIs را درک می‌کنید.
برای اطلاعات مرجع در مورد کلاس‌ها و روش‌های ارائه شده توسط کتابخانه سرویس گیرنده، به مرجع API کتابخانه مشتری Java مراجعه کنید. برای اطلاعات عمومی مرجع Blogger Data API، به راهنمای مرجع پروتکل مراجعه کنید.
شروع کردن
برای راهنمایی در تنظیم کتابخانه سرویس گیرنده، به راهنمای شروع مراجعه کنید.
کتابخانه سرویس گیرنده جاوا به جاوا 1.5 نیاز دارد. پس از دانلود کتابخانه کلاینت ، کلاس هایی را که برای شروع نیاز دارید در فایل java/lib/gdataclient-1.0.jar پیدا خواهید کرد.
ایجاد حساب بلاگر
ممکن است بخواهید برای اهداف آزمایشی برای یک حساب Blogger ثبت نام کنید . Blogger از حساب‌های Google استفاده می‌کند، بنابراین اگر از قبل یک حساب Google دارید، همه چیز آماده است.
اجرای کد نمونه
یک کلاینت نمونه کار کامل، حاوی تمام کدهای نمونه نشان داده شده در این سند، در توزیع کتابخانه سرویس گیرنده جاوا، تحت دایرکتوری gdata/java/sample/blogger/BloggerClient.java موجود است. دستورالعمل های ساخت و اجرا در همان دایرکتوری در فایل README.txt گنجانده شده است.
مشتری نمونه چندین عملیات را در وبلاگ ارائه شده برای نشان دادن استفاده از Blogger Data API انجام می دهد.
برای کامپایل نمونه های موجود در این سند در کد خود، به دستورهای import زیر نیاز دارید:
import com.google.gdata.client.*; import com.google.gdata.data.*; import com.google.gdata.util.*; import java.io.IOException; import java.net.URL;
احراز هویت در سرویس بلاگر
با استفاده از Blogger Data API می توانید به فیدهای عمومی و خصوصی دسترسی داشته باشید. فیدهای عمومی نیازی به احراز هویت ندارند، اما فقط خواندنی هستند. اگر می‌خواهید وبلاگ‌ها را اصلاح کنید، مشتری شما باید قبل از درخواست فیدهای خصوصی، احراز هویت کند. این می تواند با استفاده از هر یک از سه روش احراز هویت کند: احراز هویت OAuth ، احراز هویت پروکسی AuthSub یا احراز هویت نام کاربری/گذرواژه ClientLogin .
برای اطلاعات بیشتر در مورد احراز هویت با APIهای Google Data به طور کلی، به مستندات احراز هویت مراجعه کنید.
اکثر نمونه‌های موجود در بخش‌های بعدی این سند فرض می‌کنند که شما یک شیء GoogleService تأیید شده دارید.
احراز هویت OAuth
برای مستندات مربوط به احراز هویت OAuth با استفاده از کتابخانه Java GData، لطفاً به OAuth در کتابخانه های سرویس گیرنده پروتکل داده Google مراجعه کنید.
احراز هویت پروکسی AuthSub
احراز هویت پراکسی AuthSub توسط برنامه‌های کاربردی وب استفاده می‌شود که باید کاربران خود را در حساب‌های Google احراز هویت کنند. اپراتور وب سایت و کد مشتری به نام کاربری و رمز عبور کاربر بلاگر دسترسی ندارند. در عوض، کلاینت توکن های AuthSub ویژه ای را دریافت می کند که به مشتری اجازه می دهد از طرف یک کاربر خاص عمل کند. برای اطلاعات بیشتر، به مستندات AuthSub مراجعه کنید.
وقتی کاربر برای اولین بار از برنامه شما بازدید می کند، هنوز احراز هویت نشده است. در این مورد، شما باید برخی از اطلاعات و لینکی را نمایش دهید که کاربر را به صفحه Google هدایت می کند تا درخواست شما برای دسترسی به وبلاگ خود را تأیید کند. کتابخانه سرویس گیرنده جاوا تابعی را برای ایجاد URL صفحه Google ارائه می دهد. کد زیر URL صفحه AuthSubRequest را بازیابی می کند:
String next = "http://www.example.com/welcome.html"; String scope = "http://www.blogger.com/feeds/"; boolean secure = false; boolean session = true; String authSubLogin = AuthSubUtil.getRequestUrl(next, scope, secure, session);
متد getRequestUrl پارامترهای زیر را می گیرد (مرتبط با پارامترهای پرس و جو مورد استفاده توسط AuthSubRequest handler):
- بعدی
- آدرس صفحه ای که گوگل باید پس از احراز هویت کاربر را به آن هدایت کند.
- دامنه
- نشان می دهد که برنامه برای دسترسی به فیدهای Blogger درخواست یک رمز می کند. رشته scope مورد استفاده
http://www.blogger.com/feeds/است (البته با URL-encoded). - امن
- نشان می دهد که آیا مشتری یک توکن امن درخواست می کند یا خیر.
- جلسه
- نشان می دهد که آیا رمز برگشتی را می توان با یک توکن چند منظوره (جلسه) مبادله کرد یا خیر.
مثال بالا تماسی را نشان می دهد که توکن ایمن درخواست نمی کند (مقدار secure false است). URL درخواست حاصل ممکن است به شکل زیر باشد:
https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.html
کاربر پیوند به سایت Google را دنبال می کند و در حساب Google خود احراز هویت می کند.
پس از احراز هویت کاربر، سیستم AuthSub آنها را به آدرس اینترنتی که در پارامتر پرس و جو next URL AuthSubRequest مشخص کرده اید هدایت می کند. سیستم AuthSub یک نشانه احراز هویت را به عنوان مقدار پارامتر کوئری token به آن URL اضافه می کند. به عنوان مثال:
http://www.example.com/welcome.html?token=yourAuthToken
این مقدار توکن نشان دهنده یک توکن AuthSub یکبار مصرف است. در این مثال، از آنجایی که session = true مشخص شده است، این نشانه را می توان با یک نشانه جلسه AuthSub با فراخوانی سرویس AuthSubSessionToken ، به صورت زیر مبادله کرد، که در آن urlFromAuthSub نشانی اینترنتی است که AuthSub توکن را به آن اضافه کرده است:
String token = AuthSubUtil.getTokenFromReply(urlFromAuthSub); String sessionToken = AuthSubUtil.exchangeForSessionToken(token, null);
یعنی توکن یک بار مصرف خود را به متد exchangeForSessionToken به همراه null (برای حالت ثبت نشده) یا یک کلید خصوصی (برای حالت ثبت شده) ارسال می‌کنید و رابط AuthSub یک نشانه جلسه را برمی‌گرداند. برای اطلاعات بیشتر درباره برنامه‌های کاربردی ثبت‌شده و کلیدهای خصوصی، به بخش « درخواست‌های امضا » در اسناد AuthSub مراجعه کنید.
سپس برنامه شما می تواند از نشانه جلسه در تعاملات بعدی با بلاگر استفاده کند. برای اینکه به کتابخانه سرویس گیرنده جاوا بگویید که رمز جلسه را به صورت خودکار با هر درخواست ارسال کند، با متد setAuthSubToken شی GoogleService تماس بگیرید:
GoogleService.setAuthSubToken(sessionToken, null);
پس از آن، کتابخانه مشتری به طور خودکار توکن را همراه با هر درخواست ارسال می کند.
احراز هویت نام کاربری/گذرواژه ClientLogin
اگر کلاینت شما یک کلاینت «نصب شده» مستقل و تک کاربره است (مانند یک برنامه دسکتاپ) از احراز هویت ClientLogin استفاده کنید. فقط روش setUserCredentials را در شیء GoogleService خود فراخوانی کنید و تمام تعاملات بعدی با Blogger احراز هویت می شود:
GoogleService myService = new GoogleService("blogger", "exampleCo-exampleApp-1");
myService.setUserCredentials("user@example.com", "secretPassword");
در قطعه بالا، دو پارامتر را به سازنده GoogleService ارسال می کنیم. اولین پارامتر نام سرویسی است که می خواهیم با آن تعامل داشته باشیم. پارامتر دوم نام برنامه ما به شکل companyName - applicationName - versionID است.
برای اطلاعات بیشتر درباره احراز هویت ClientLogin، از جمله درخواست‌ها و پاسخ‌های نمونه، به مستندات احراز هویت برای برنامه‌های نصب‌شده مراجعه کنید.
توجه : برای همه درخواست ها در یک جلسه معین از یک نشانه استفاده کنید. برای هر درخواست بلاگر یک نشانه جدید دریافت نکنید.
توجه : همانطور که در مستندات ClientLogin توضیح داده شده است، درخواست احراز هویت ممکن است با شکست مواجه شود و یک چالش CAPTCHA درخواست کند. اگر می‌خواهید Google چالش CAPTCHA را صادر و رسیدگی کند، کاربر را به https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger بفرستید (به جای URL مربوط به CAPTCHA که در اسناد ClientLogin ارائه شده است).
بازیابی لیستی از وبلاگ ها
Blogger Data API خوراکی را ارائه می دهد که وبلاگ ها را برای یک کاربر خاص فهرست می کند. آن خوراک به عنوان "متافید" شناخته می شود.
کد نمونه زیر از یک شیء GoogleService تأیید شده برای بازیابی متافید استفاده می کند و سپس عنوان هر وبلاگ را چاپ می کند.
public static void printUserBlogs(GoogleService myService)
throws ServiceException, IOException {
// Request the feed
final URL feedUrl = new URL("http://www.blogger.com/feeds/default/blogs");
Feed resultFeed = myService.getFeed(feedUrl, Feed.class);
// Print the results
System.out.println(resultFeed.getTitle().getPlainText());
for (int i = 0; i < resultFeed.getEntries().size(); i++) {
Entry entry = resultFeed.getEntries().get(i);
System.out.println("\t" + entry.getTitle().getPlainText());
}
}
به URL استفاده شده توسط متد getFeed توجه کنید. این URL پیش فرض متافید است. لیستی از وبلاگ ها را برای کاربر تأیید شده فعلی برمی گرداند. برای دسترسی به فید برای یک کاربر دیگر، می توانید شناسه کاربر را به جای default در URL متافید قرار دهید. شناسه کاربر رشته اعدادی است که در انتهای URL نمایه کاربر قرار دارد.
ایجاد پست ها
Blogger Data API به شما امکان ایجاد و انتشار مطالب جدید وبلاگ و همچنین ایجاد پیش نویس ورودی ها را می دهد.
توجه : تنظیم یک نویسنده سفارشی برای پست ها در حال حاضر پشتیبانی نمی شود. همه پست های جدید به گونه ای ظاهر می شوند که گویی توسط کاربر تأیید شده فعلی ایجاد شده اند.
انتشار پست وبلاگ
می توانید از کتابخانه مشتری جاوا برای انتشار مطالب جدید وبلاگ استفاده کنید.
ابتدا یک شیء Entry برای نمایش پست وبلاگ ایجاد کنید. سپس می توانید عنوان، محتوا و سایر ویژگی های پست وبلاگ را تنظیم کنید. در نهایت، از شی GoogleService برای درج پست استفاده کنید. در اینجا مثالی از نحوه انتشار یک پست وبلاگ جدید آورده شده است:
public static Entry createPost(
GoogleService myService, String blogID, String title,
String content, String userName)
throws ServiceException, IOException {
// Create the entry to insert
Entry myEntry = new Entry();
myEntry.setTitle(new PlainTextConstruct(title));
myEntry.setContent(new PlainTextConstruct(content));
// Ask the service to insert the new entry
URL postUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
return myService.insert(postUrl, myEntry);
}
متد insert URL پست سرویس را به عنوان پارامتر می گیرد. سپس متد ورودی را همانطور که توسط Blogger ذخیره شده است برمی گرداند. ورودی برگشتی همان ورودی است که ارسال کردید، اما حاوی عناصر مختلفی است که توسط Blogger اضافه شده است، مانند شناسه پست.
اگر درخواست شما به دلایلی ناموفق باشد، Blogger ممکن است کد وضعیت دیگری را برگرداند. برای اطلاعات در مورد کدهای وضعیت، به سند مرجع پروتکل Google Data API مراجعه کنید.
ایجاد پیش نویس پست وبلاگ
پست‌های پیش‌نویس مانند پست‌های عمومی ایجاد می‌شوند، اما باید ویژگی draft شی Entry را تنظیم کنید. می‌توانید با افزودن خط برجسته، یک پست وبلاگ مانند پست بالا به عنوان پیش‌نویس ایجاد کنید:
public static Entry createPost(GoogleService myService, String blogId,
String title, String content, String userName,
Boolean isDraft)
throws ServiceException, IOException {
// Create the entry to insert
Entry myEntry = new Entry();
myEntry.setTitle(new PlainTextConstruct(title));
myEntry.setContent(new PlainTextConstruct(content));
myEntry.setDraft(isDraft);
// Ask the service to insert the new entry
URL postUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
return myService.insert(postUrl, myEntry);
}
می‌توانید با بازیابی پست پیش‌نویس، تنظیم ویژگی پیش‌نویس روی false، و سپس به‌روزرسانی پست، یک پست وبلاگ پیش‌نویس موجود را به یک پست منتشر شده تبدیل کنید. ما بازیابی و به روز رسانی پست ها را در دو بخش بعدی پوشش خواهیم داد.
در حال بازیابی پست ها
بخش‌های زیر نحوه بازیابی فهرستی از پست‌های وبلاگ، با و بدون پارامترهای پرس و جو را شرح می‌دهند.
می‌توانید بدون احراز هویت، فید عمومی Blogger را درخواست کنید. بنابراین، قبل از بازیابی پست‌ها از یک وبلاگ عمومی، نیازی به فراخوانی متد setUserCredentials یا احراز هویت AuthSub ندارید.
بازیابی همه پست های وبلاگ
برای بازیابی پست های کاربر، همان روش getFeed مورد استفاده برای بازیابی متافید وبلاگ ها را فراخوانی کنید، اما این بار URL فید وبلاگ-پست را ارسال کنید:
public static void printAllPosts(
GoogleService myService, String blogId)
throws ServiceException, IOException {
// Request the feed
URL feedUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
Feed resultFeed = myService.getFeed(feedUrl, Feed.class);
// Print the results
System.out.println(resultFeed.getTitle().getPlainText());
for (int i = 0; i < resultFeed.getEntries().size(); i++) {
Entry entry = resultFeed.getEntries().get(i);
System.out.println("\t" + entry.getTitle().getPlainText());
}
System.out.println();
}
بازیابی پست ها با استفاده از پارامترهای پرس و جو
Blogger Data API به شما امکان می‌دهد مجموعه‌ای از ورودی‌ها را درخواست کنید که با معیارهای مشخص شده مطابقت دارند، مانند درخواست پست‌های وبلاگ منتشر شده یا به‌روزرسانی شده در یک محدوده تاریخ معین. برای این کار، یک آبجکت Query ایجاد می‌کنید و آن را به متد GoogleService.getQuery ارسال می‌کنید.
به عنوان مثال، برای ارسال یک جستجوی محدوده تاریخ، از متدهای setPublishedMin و setPublishedMax شی Query استفاده کنید. قطعه کد زیر عنوان هر پست وبلاگ منتشر شده را بین زمان شروع و پایان مشخص شده چاپ می کند:
public static void printDateRangeQueryResults(
GoogleService myService, String blogId,
DateTime startTime, DateTime endTime)
throws ServiceException, IOException {
// Create query and submit a request
URL feedUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
Query myQuery = new Query(feedUrl);
myQuery.setPublishedMin(startTime);
myQuery.setPublishedMax(endTime);
Feed resultFeed = myService.query(myQuery, Feed.class);
// Print the results
System.out.println(resultFeed.getTitle().getPlainText() +
" posts between " + startTime + " and " + endTime);
for (int i = 0; i < resultFeed.getEntries().size(); i++) {
Entry entry = resultFeed.getEntries().get(i);
System.out.println("\t" + entry.getTitle().getPlainText());
System.out.println("\t" + entry.getUpdated().toStringRfc822());
}
System.out.println();
}
توجه داشته باشید که شئ Query با استفاده از همان URL feed post که برای بازیابی پست ها استفاده می شود ساخته شده است.
Blogger Data API از روش های Query زیر پشتیبانی می کند:
- AddCategoryFilter
- برای فیلتر کردن نتایج فید، دسته‌ها (همچنین به عنوان برچسب شناخته می‌شوند) را مشخص کنید. برای مثال،
http://www.blogger.com/feeds/ blogID /posts/default/-/Fritz/Laurieورودی‌هایی را با هر دو برچسبFritzوLaurieبرمی‌گرداند. - setMaxResults
- حداکثر تعداد ورودی ها را برای بازگشت تنظیم کنید.
- setPublishedMin، setPublishedMax
- محدودیت ها را در تاریخ انتشار ورودی تنظیم کنید.
- setStartIndex
- شاخص 1-based اولین نتیجه ای را که باید بازیابی شود (برای صفحه بندی) تنظیم کنید.
- setUpdatedMin، setUpdatedMax
- محدودیت‌ها را در تاریخ‌های به‌روزرسانی ورودی تنظیم کنید. این پارامترهای پرس و جو نادیده گرفته می شوند مگر اینکه پارامتر
orderbyرویupdatedتنظیم شود.
توجه : در حال حاضر هیچ تنظیم کننده ای برای پارامتر پرس و جو orderby وجود ندارد. با این حال، در صورت نیاز به تنظیم، همچنان می توانید از متد Query.addCustomParameter() استفاده کنید.
برای اطلاعات بیشتر در مورد پارامترهای پرس و جو، به راهنمای مرجع API داده Blogger و راهنمای مرجع Google Data APIs مراجعه کنید.
به روز رسانی پست ها
برای به‌روزرسانی یک پست وبلاگ موجود، ابتدا ورودی مورد نظر برای به‌روزرسانی را بازیابی می‌کنید، سپس آن را تغییر می‌دهید و سپس با استفاده از روش update به Blogger ارسال می‌کنید. قطعه کد زیر عنوان یک ورودی وبلاگ را تغییر می دهد، با این فرض که شما قبلاً ورودی را از سرور بازیابی کرده اید.
public static Entry updatePostTitle(
GoogleService myService, Entry entryToUpdate, String newTitle)
throws ServiceException, IOException {
entryToUpdate.setTitle(new PlainTextConstruct(newTitle));
URL editUrl = new URL(entryToUpdate.getEditLink().getHref());
return myService.update(editUrl, entryToUpdate);
}
کد بالا یک Entry حاوی کل پست تازه به روز شده را برمی گرداند. برای به‌روزرسانی سایر ویژگی‌ها، کافی است قبل از فراخوانی update ، آنها را در شیء Entry تنظیم کنید.
توجه : تغییر داده های نویسنده مرتبط با پست ها در حال حاضر پشتیبانی نمی شود.
حذف پست ها
برای حذف یک پست، URL ویرایش پست را به روش delete در شیء GoogleService خود منتقل کنید، مانند این:
public static void deletePost(
GoogleService myService, String editLinkHref)
throws ServiceException, IOException {
URL deleteUrl = new URL(editLinkHref);
myService.delete(deleteUrl);
}
نظرات
Blogger Data API امکان ایجاد، بازیابی و حذف نظرات را فراهم می کند. به روز رسانی نظرات پشتیبانی نمی شود (و نه در رابط وب موجود است).
ایجاد نظرات
برای ارسال نظر، یک شیء Entry ایجاد کنید و آن را به صورت زیر وارد کنید:
public static Entry createComment(
GoogleService myService, String blogID, String postId,
String commentText)
throws ServiceException, IOException {
// Build the comment feed URI
String commentsFeedUri = "http://www.blogger.com/feeds/" + blogID + "/" + postId + "/comments/default";
URL feedUrl = new URL(commentsFeedUri);
// Create a new entry for the comment and submit it to the GoogleService
Entry myEntry = new Entry();
myEntry.setContent(new PlainTextConstruct(commentText));
return myService.insert(feedUrl, myEntry);
}
توجه : در حال حاضر، فقط می‌توانید برای وبلاگی که متعلق به کاربر تأیید شده است، نظر ارسال کنید.
توجه : تنظیم یک نویسنده سفارشی برای نظرات در حال حاضر پشتیبانی نمی شود. همه نظرات جدید به گونه ای ظاهر می شوند که گویی توسط کاربر تأیید شده فعلی ایجاد شده اند.
بازیابی نظرات
می‌توانید نظرات یک پست خاص را از URL خوراک نظرات آن پست بازیابی کنید:
public static void printAllComments(
GoogleService myService, String blogID, String postId)
throws ServiceException, IOException {
// Build comment feed URI and request comments on the specified post
String commentsFeedUri = "http://www.blogger.com/feeds/" + blogID + "/" + postId + "/comments/default";
URL feedUrl = new URL(commentsFeedUri);
Feed resultFeed = myService.getFeed(feedUrl, Feed.class);
// Display the results
System.out.println(resultFeed.getTitle().getPlainText());
for (int i = 0; i < resultFeed.getEntries().size(); i++) {
Entry entry = resultFeed.getEntries().get(i);
System.out.println("\t" +
((TextContent) entry.getContent()).getContent().getPlainText());
System.out.println("\t" + entry.getUpdated().toStringRfc822());
}
System.out.println();
}
یا می توانید نظرات همه پست ها را با استفاده از URL خوراک نظرات وبلاگ دریافت کنید:
http://www.blogger.com/feeds/blogID/comments/default
حذف نظرات
برای حذف یک نظر، URL ویرایش نظر را به روش delete در شیء GoogleService خود ارسال کنید:
public static void deleteComment(GoogleService myService, String editLinkHref)
throws ServiceException, IOException {
URL deleteUrl = new URL(editLinkHref);
myService.delete(deleteUrl);
}