دليل المطور: Java

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

تسمح واجهة برمجة التطبيقات لبيانات Blogger لتطبيقات العميل بعرض محتوى Blogger وتحديثه على شكل خلاصات Google Data API.

يمكن لتطبيق العميل استخدام واجهة برمجة تطبيقات Blogger Data API لإنشاء منشورات مدوّنة جديدة أو تعديل أو حذف مشاركات مدوّنات حالية أو طلب بحث عن مشاركات المدوّنات التي تتطابق مع معايير معيّنة.

وبالإضافة إلى توفير بعض المعلومات الأساسية حول إمكانات واجهة برمجة تطبيقات Blogger Data API، يقدّم هذا المستند أمثلة على تفاعلات Data API الأساسية باستخدام مكتبة برامج Java. إذا كنت تريد معرفة المزيد عن البروتوكول الأساسي الذي تستخدمه المكتبة، فراجع قسم البروتوكول في دليل المطوّر هذا.

المحتويات

الجمهور

هذا المستند مخصص للمبرمجين الذين يريدون كتابة تطبيقات برنامج Java التي يمكنها التفاعل مع Blogger.

يفترض هذا المستند أنّك تفهم الأفكار العامة التي تستند إليها بروتوكول Google Data APIs.

للحصول على معلومات مرجعية حول الفئات والطرق التي تقدّمها مكتبة العملاء، اطّلِع على مرجع واجهة برمجة التطبيقات لمكتبة برامج Java. للحصول على معلومات مرجعية عامة عن Blogger Data API، يُرجى الاطّلاع على دليل البروتوكولات المرجعية.

الخطوات الأولى

للحصول على المساعدة في إعداد مكتبة البرامج، يمكنك مراجعة دليل البدء.

تتطلب مكتبة برامج Java الإصدار 1.5 من Java. بعد تنزيل مكتبة البرامج، ستعثر في ملف java/lib/gdataclient-1.0.jar على الصفوف التي تحتاج إليها للبدء.

إنشاء حساب على Blogger

ويمكنك الاشتراك للحصول على حساب على Blogger لأغراض الاختبار. يستخدم Blogger حسابات Google، وبالتالي إذا كان لديك حساب Google من قبل، فأنت جاهز.

تشغيل نموذج التعليمة البرمجية

ويتوفر نموذج العميل الشامل الذي يحتوي على كل رمز النموذج المعروض في هذا المستند، في توزيع مكتبة برامج Java، ضمن الدليل 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

يمكنك الوصول إلى كل من الخلاصات العامة والخاصة باستخدام واجهة برمجة تطبيقات Blogger Data API. لا تتطلّب الخلاصات العامة أيّ مصادقة، ولكنّها للقراءة فقط. إذا كنت تريد تعديل المدونات، على عميلك المصادقة قبل طلب الخلاصات الخاصة. يمكنه المصادقة باستخدام أحد الأسلوبين: مصادقة الخادم الوكيل AuthSub أو مصادقة اسم المستخدم/كلمة المرور ClientLogin.

لمزيد من المعلومات حول المصادقة باستخدام Google Data APIs بشكل عام، يمكنك الاطّلاع على مستندات المصادقة.

تفترض معظم النماذج في الأقسام اللاحقة من هذا المستند أنّ لديك عنصر GoogleService تمت مصادقته.

مصادقة الخادم الوكيل AuthSub

تستخدم تطبيقات الويب مصادقة الخادم الوكيل AuthSub، التي تحتاج إلى مصادقة المستخدمين ضمن حسابات Google. لا يمكن لمشغّل الموقع الإلكتروني ورمز العميل الوصول إلى اسم المستخدم وكلمة المرور لمستخدم Blogger، بل يحصل العميل بدلاً من ذلك على رموز AuthSub المميّزة التي تسمح للعميل بالتصرف نيابةً عن مستخدم معيّن. للحصول على معلومات أكثر تفصيلاً، يمكنك الاطّلاع على مستندات AuthSub.

عندما يزور أحد المستخدمين تطبيقك لأول مرة، لن تتم مصادقته بعد. وفي هذه الحالة، تحتاج إلى عرض بعض المعلومات ورابط يوجّه المستخدم إلى صفحة 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

تمثّل قيمة الرمز المميّز هذه رمزًا مميّزًا لـ AuthSub يُستخدم لمرة واحدة. في هذا المثال، بعد تحديد session = true، يمكن استبدال هذا الرمز المميّز برمز مميّز لجلسة AuthSub من خلال طلب الخدمة AuthSubSessionToken على النحو التالي، حيث يشير urlFromAuthSub إلى عنوان URL الذي ألحق AuthSub الرمز المميّز به:

String token = AuthSubUtil.getTokenFromReply(urlFromAuthSub);
String sessionToken = AuthSubUtil.exchangeForSessionToken(token, null);

وهذا يعني أنّك تمرر الرمز المميّز الذي يُستخدم لمرة واحدة إلى طريقة exchangeForSessionToken مع null (للوضع غير المسجَّل) أو مفتاح خاص (للوضع المسجَّل)، وتعرض واجهة AuthSub رمزاً مميزًا للجلسة. لمزيد من المعلومات حول التطبيقات المسجّلة والمفاتيح الخاصة، يمكنك الاطّلاع على قسم توقيع الطلبات في مستندات AuthSub.

ويمكن لتطبيقك بعد ذلك استخدام الرمز المميز للجلسة في التفاعلات اللاحقة مع Blogger. لتوجيه مكتبة برامج Java إلى إرسال الرمز المميّز للجلسة تلقائيًا مع كل طلب، يمكنك استدعاء طريقة 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، بما في ذلك نماذج الطلبات والاستجابات، يمكنك الاطّلاع على مستندات المصادقة على التطبيقات المثبّتة.

ملاحظة: استخدِم الرمز المميّز نفسه لجميع الطلبات في جلسة معيّنة، ولا تحصل على رمز مميّز جديد لكل طلب من طلبات Blogger.

ملاحظة: كما هو موضّح في مستندات 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 بإنشاء إدخالات جديدة للمدونات ونشرها، بالإضافة إلى إنشاء مسودات للإدخالات.

ملاحظة: لا يمكن حاليًا ضبط مؤلف مخصّص للمشاركات. ستظهر جميع المشاركات الجديدة كما لو كان قد تم إنشاؤها بواسطة المستخدم الذي تمت مصادقته حاليًا.

نشر مشاركة مدونة

يمكنك استخدام مكتبة برامج 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 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 لخلاصة المشاركات نفسه المستخدَم لاسترداد المشاركات.

تتيح واجهة برمجة التطبيقات لبيانات Blogger استخدام طرق Query التالية:

addCategoryFilter

حدِّد الفئات (المعروفة أيضًا باسم التصنيفات) لفلترة نتائج الخلاصة. على سبيل المثال، تعرض الدالة http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie إدخالات بكل من التصنيفين Fritz وLaurie.

setMaxResults

إعداد الحد الأقصى لعدد الإدخالات المطلوب عرضها

setPublishMin، setPublishMax

وضع حدود لتواريخ نشر المشاركات

setStartIndex

إعداد الفهرس المستند إلى 1 لأول نتيجة تريد استردادها (لترقيم الصفحات)

setUpdatedMin، setUpdatedMax

ضبط الحدود على تواريخ تعديل الإدخالات. ويتم تجاهل مَعلمات طلب البحث هذه ما لم يتم ضبط المَعلمة 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 بإنشاء التعليقات واستردادها وحذفها. تحديث التعليقات غير معتمد (ولا يتوفر كذلك في واجهة الويب).

إنشاء التعليقات

لنشر تعليق، أنشئ كائن 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);
}

الرجوع إلى الأعلى