دليل مطوّري البرامج: Java

ملاحظة مهمة: هذه نسخة قديمة من هذه الصفحة. للحصول على أحدث إصدار، استخدِم الروابط في شريط التنقّل الأيمن.

تتيح واجهة برمجة التطبيقات 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 رمزًا مميّزًا للجلسة. لمزيد من المعلومات حول التطبيقات المسجَّلة والمفاتيح الخاصة، راجِع قسم التوقيع على الطلبات&quot ومستندات 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.&quot.

يستخدم رمز النموذج التالي عنصر 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);
}

الرجوع إلى أعلى الصفحة