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

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

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

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

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

المحتويات

الجمهور

هذا المستند مخصّص للمبرمجين الذين يريدون كتابة تطبيقات 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، ضمن الdirectorygdata/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 رمزًا مميّزًا للمصادقة بهذا العنوان، وذلك بصفته قيمة مَعلمة طلب البحث 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 للعملاء إرسال رمز تمييز جلسة العميل تلقائيًا مع كل طلب، يمكنك استدعاء GoogleServicesetAuthSubToken في 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 Data API طرق Query التالية:

addCategoryFilter

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

setMaxResults

حدِّد الحد الأقصى لعدد الإدخالات التي سيتم عرضها.

setPublishedMin وsetPublishedMax

حدِّد الحدود القصوى لتواريخ نشر الإدخالات.

setStartIndex

حدِّد الفهرس المُستند إلى 1 للنتيجة الأولى التي سيتم استرجاعها (لصفحة البيانات).

setUpdatedMin وsetUpdatedMax

حدِّد الحدود القصوى لتواريخ تعديل الإدخالات. يتم تجاهل مَعلمات طلب البحث هذه ما لم يتم ضبط المَعلمة orderby على updated.

ملاحظة: لا تتوفّر حاليًا أيّ أدوات ضبط لمَعلمة طلب البحث orderby. ومع ذلك، سيظل بإمكانك استخدام الطريقة Query.addCustomParameter() إذا كنت بحاجة إلى ضبط هذا الإعداد.

لمزيد من المعلومات عن مَعلمات طلب البحث، اطّلِع على دليل مرجعي لواجهة برمجة تطبيقات Blogger Data API ودليل مرجعي لواجهات برمجة تطبيقات Google Data API.

تعديل المشاركات

لتعديل مشاركة مدوّنة حالية، عليك أولاً استرداد الإدخال الذي تريد تعديله، ثم تعديله، ثم إرساله إلى 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);
}

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