ملاحظة مهمة: هذه نسخة قديمة من هذه الصفحة. للحصول على أحدث إصدار، استخدِم الروابط في شريط التنقّل الأيمن.
تتيح واجهة برمجة التطبيقات Blogger Data API لتطبيقات العملاء عرض محتوى Blogger وتحديثه على شكل خلاصات Google Data API.
يمكن أن يستخدم تطبيق العميل واجهة برمجة التطبيقات Blogger Blogger لإنشاء مشاركات مدونة جديدة، وتعديل مشاركات المدونة الحالية أو حذفها، وإجراء طلب بحث عن مشاركات المدونة التي تطابق معايير معينة.
بالإضافة إلى تقديم بعض المعلومات الأساسية حول إمكانات واجهة برمجة التطبيقات لمدونة Blogger، يقدّم هذا المستند أمثلة على تفاعلات "واجهة برمجة التطبيقات للبيانات" الأساسية باستخدام مكتبة برامج Java. إذا كنت مهتمًا بمعرفة المزيد عن البروتوكول الأساسي الذي تستخدمه المكتبة، ارجع إلى قسم البروتوكول في دليل مطوّر البرامج هذا.
المحتويات
الجمهور
هذا المستند مخصص لمطوّري البرامج الذين يريدون كتابة تطبيقات عميل Java التي يمكنها التفاعل مع Blogger.
يفترض هذا المستند أنك تفهم الأفكار العامة وراء بروتوكول Google Data APIs.
للحصول على معلومات مرجعية حول الصفوف والطرق التي تقدّمها مكتبة العميل، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات لمكتبة Java. للحصول على معلومات عامة عن واجهة برمجة التطبيقات المرجعية في Blogger، يُرجى الاطلاع على دليل مرجعي للبروتوكول.
البدء
للحصول على مساعدة في إعداد مكتبة العميل، يمكنك الاطّلاع على دليل البدء.
تتطلّب مكتبة برامج Java رقم 1.5. بعد تنزيل
مكتبة العميل، ستجد الصفوف التي تحتاج إليها للبدء في ملف java/lib/gdataclient-1.0.jar
.
إنشاء حساب Blogger
ننصحك بالاشتراك في حساب Blogger لأغراض الاختبار. تستخدم خدمة Blogger حسابات Google، لذلك إذا كان لديك حساب Google، ستكون جاهزًا.
جارٍ تنفيذ نموذج الرمز
يحتوي نموذج العميل الذي يعمل بالكامل على جميع نماذج التعليمات البرمجية المعروضة في هذا المستند، وذلك في توزيع مكتبة برامج Java ضمن الدليل gdata/java/sample/blogger/BloggerClient.java
. يتم تضمين تعليمات الإصدار والتنفيذ في الدليل نفسه في الملف README.txt
.
يجري نموذج العميل عمليات متعددة على المدونة المتوفرة لعرض كيفية استخدام واجهة برمجة التطبيقات لبيانات Blogger.
لتجميع الأمثلة الواردة في هذا المستند في رمزك الخاص، ستحتاج إلى العبارات التالية التالية: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 Blogger. ولا تتطلب الخلاصات العلنية أي مصادقة، ولكنها للقراءة فقط. وإذا كنت تريد تعديل المدونات، فيجب على العميل المصادقة قبل طلب الخلاصات الخاصة. ويمكنه المصادقة باستخدام أي من الطريقتين التاليتين: مصادقة الخادم الوكيل AuthSub أو مصادقة اسم المستخدم/كلمة المرور باستخدام ClientLogin.
ولمزيد من المعلومات عن المصادقة باستخدام واجهات برمجة التطبيقات للبيانات في Google بشكل عام، يمكنك الاطّلاع على مستندات المصادقة.
تفترض معظم النماذج في الأقسام اللاحقة من هذا المستند أن لديك
كائن GoogleService
تمت مصادقته.
مصادقة الخادم الوكيل AuthSub
تستخدم تطبيقات الويب التي تحتاج إلى مصادقة مستخدميها في حسابات Google لمصادقة الخادم الوكيل AuthSub. لا يمكن لعامل الموقع الإلكتروني ورمز العميل الوصول إلى اسم المستخدم وكلمة المرور لمستخدم Blogger، وبدلاً من ذلك، يحصل العميل على رموز AuthSub خاصة تسمح للعميل بالتصرف نيابةً عن مستخدم معيّن. للحصول على معلومات أكثر تفصيلاً، يُرجى الاطّلاع على وثائق OAuthSub.
وعند زيارة المستخدم لتطبيقك للمرة الأولى، لم تتم مصادقتها بعد. في هذه الحالة، عليك عرض بعض المعلومات ورابط ينقل المستخدم إلى صفحة Google لمصادقة طلبك للدخول إلى مدوناته. توفّر مكتبة برامج Java وظيفة لإنشاء عنوان 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):
- التالي
- عنوان URL للصفحة التي يجب أن يُعيد Google توجيه المستخدم إليها بعد المصادقة.
- نطاق
- يشير هذا الإعداد إلى أن التطبيق يطلب رمزًا مميزًا للوصول إلى خلاصات Blogger. سلسلة النطاق المطلوب استخدامها هي
http://www.blogger.com/feeds/
(ترميز عنوان URL بالطبع). - آمن
- يشير هذا الإعداد إلى ما إذا كان العميل يطلب رمزًا مميزًا آمنًا.
- جلسة
- يشير هذا الإعداد إلى ما إذا كان من الممكن استبدال الرمز المميّز المعروض برمز مميّز متعدد الاستخدامات (الجلسة).
يوضّح المثال أعلاه مكالمة لا تطلب رمزًا مميزًا آمنًا (قيمة 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 توجيهه إلى عنوان URL
الذي حدّدته في معلَمة طلب البحث next
لعنوان URL AuthSubRequest. يُلحِق نظام AuthSub رمزًا مميزًا للمصادقة بعنوان URL هذا، باعتباره
قيمة معلمة طلب البحث token
. مثلاً:
http://www.example.com/welcome.html?token=yourAuthToken
تمثّل قيمة الرمز المميّز هذا رمزًا مميّزًا للاستخدام لمرة واحدة. في هذا المثال،
بعد تحديد session = true
، يمكن استبدال هذا الرمز المميّز
برمز مميّز لجلسة AuthSub عن طريق استدعاء الخدمة AuthSubSessionToken
كما يلي، حيث يكون urlFromAuthSub
هو عنوان URL الذي أرفقت فيه AuthSub الرمز المميّز بـ:
String token = AuthSubUtil.getTokenFromReply(urlFromAuthSub); String sessionToken = AuthSubUtil.exchangeForSessionToken(token, null);
وهذا يعني تمرير الرمز المميّز لمرة واحدة إلى طريقة exchangeForSessionToken
، بالإضافة إلى null
(للوضع غير المسجَّل) أو مفتاح خاص (للوضع المسجّل)، وتعرض واجهة AuthSub رمزًا مميّزًا للجلسة. لمزيد من المعلومات حول التطبيقات المسجَّلة والمفاتيح الخاصة، راجِع قسم التوقيع على الطلبات"
ومستندات AuthSub.
يمكن للتطبيق بعد ذلك استخدام الرمز المميز للجلسة في التفاعلات اللاحقة مع Blogger. لإبلاغ مكتبة برامج Java تلقائيًا بإرسال الرمز المميّز للجلسة مع كل طلب، يُرجى استدعاء طريقة GoogleService
الكائن setAuthSubToken
:
GoogleService.setAuthSubToken(sessionToken, null);
بعد ذلك، ترسل مكتبة العميل الرمز المميز مع كل طلب تلقائيًا.
مصادقة اسم المستخدم/كلمة المرور ClientLogin
استخدام مصادقة ClientLogin إذا كان البرنامج عميلاً مستقلاً لمستخدم واحد
"installed;quot;; (مثل تطبيق سطح مكتب). ما عليك سوى استدعاء الطريقة setUserCredentials
على الكائن GoogleService
، وستتم مصادقة جميع التفاعلات اللاحقة مع Blogger:
GoogleService myService = new GoogleService("blogger", "exampleCo-exampleApp-1"); myService.setUserCredentials("user@example.com", "secretPassword");
في المقتطف أعلاه، يتم تمرير معلَمتَين إلى دالة الإنشاء GoogleService
. المَعلمة الأولى هي اسم
الخدمة التي نريد التفاعل معها. المَعلمة الثانية هي اسم
تطبيقنا على النحو
companyName-applicationName-versionID.
لمزيد من المعلومات حول مصادقة ClientLogin، بما في ذلك نماذج الطلبات والردود، راجع مستندات المصادقة للتطبيقات المثبّتة.
ملاحظة: يمكنك استخدام الرمز المميّز نفسه لجميع الطلبات في جلسة معيّنة، مع عدم الحصول على رمز مميّز جديد لكل طلب من طلبات Blogger.
ملاحظة: كما هو موضّح في مستندات ClientLogin، قد يفشل طلب المصادقة وطلب اختبار CAPTCHA. إذا أردت أن تصدر Google تحدي اختبار CAPTCHA وتعالجه، أرسِل المستخدم إلى https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger
(بدلاً من إرسال عنوان URL لالتعامل مع اختبار CAPTCHA المذكور في مستندات ClientLogin).
استرداد قائمة المدونات
توفر واجهة برمجة التطبيقات لبيانات Blogger خلاصة تسرد المدونات لمستخدم محدد، وتُعرف هذه الخلاصة باسم "metafeed.".
يستخدم رمز النموذج التالي عنصر 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 إنشاء إدخالات مدونات جديدة ونشرها، بالإضافة إلى إنشاء مسودات للإدخالات.
ملاحظة: لا يمكن حاليًا تحديد مؤلف مخصّص للمشاركات. ستظهر جميع المشاركات الجديدة كما لو كان قد تم إنشاؤها من قِبل المستخدم الذي تمت مصادقته حاليًا.
نشر مشاركة مدونة
يمكنك استخدام مكتبة برنامج Java لنشر إدخالات جديدة للمدونة.
أولاً، عليك إنشاء كائن 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 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); }
يمكنك تحويل مسودة مشاركة مدونة حالية إلى مشاركة منشورة عن طريق استرداد مسودة المشاركة وضبط سمة المسودة على "خطأ" ثم تحديث المشاركة. سنتناول استرداد المشاركات وتعديلها في القسمين التاليين.
جارٍ استرداد المشاركات
توضّح الأقسام التالية كيفية استرداد قائمة بمشاركات المدوّنة مع معلَمات طلب البحث وبدونها.
يمكنك طلب البحث في خلاصة علنية على 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 طلب مجموعة من الإدخالات التي تطابق معايير محددة، مثل طلب مشاركات المدونات التي تم نشرها أو تعديلها في نطاق زمني محدد. لإجراء ذلك، عليك إنشاء كائن 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 لخلاصة المشاركات نفسها ويتم استخدامه لاسترداد المشاركات.
تدعم واجهة برمجة التطبيقات لبيانات Blogger الطرق Query
التالية:
- إضافة فئة
- حدِّد فئات (تُعرف أيضًا بالتصنيفات) لفلترة نتائج الخلاصة. على سبيل المثال، تعرض
http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie
الإدخالات ذات التصنيفينFritz
وLaurie
. - تحقيق الحد الأقصى من النتائج
- يمكنك ضبط الحد الأقصى لعدد الإدخالات التي يمكن عرضها.
- setPublisherMax وsetPublisherMax
- حدِّد الحدود في تواريخ نشر الإدخال.
- فهرس الفهرسة
- يجب ضبط الفهرس المستند إلى نتيجة واحدة للنتيجة الأولى التي سيتم استردادها (للانتقال إلى الصفحة).
- setModifiedMin, setUpdateMax
- حدّد الحدود في تواريخ تحديث الدخول. ويتم تجاهل معلَمات طلب البحث هذه ما لم يتم ضبط المعلَمة
orderby
علىupdated
.
ملاحظة: ما مِن عمليات إعداد حاليًا لمعلّمة طلب البحث orderby
. ومع ذلك، يمكنك استخدام الطريقة Query.addCustomParameter()
في حال أردت ضبطها.
للحصول على مزيد من المعلومات عن معلَمات طلب البحث، يُرجى الاطّلاع على الدليل المرجعي لواجهة برمجة تطبيقات البيانات في Blogger والدليل المرجعي لواجهات برمجة التطبيقات للبيانات في Google.
جارٍ تعديل المشاركات
لتعديل مشاركة مدونة حالية، يجب أولاً استرداد الإدخال الذي تريد
تعديله، ثم تعديله بعد ذلك، ثم إرساله إلى Blogger باستخدام طريقة
update
. يعدّل مقتطف الرمز التالي عنوان إدخال المدونة، مع افتراض أنك قبلت الإدخال من الخادم.
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
التي تتضمّن المشاركة المحدَّثة حديثًا بالكامل. لتعديل أي خصائص أخرى، ما عليك سوى ضبطها في
العنصر Entry
قبل استدعاء update
.
ملاحظة: لا تتوفّر إمكانية تعديل بيانات المؤلف المرتبطة بالمشاركات في الوقت الحالي.
جارٍ حذف المشاركات
لحذف مشاركة، مرِّر عنوان 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); }