استخدام مكتبة برامج Java

يوضّح هذا المستند كيفية استخدام مكتبة برامج Java لإرسال طلبات بحث إلى Google Data API‏ ("GData") وتفسير الردود التي يتم إرجاعها.

توفّر Google مجموعة من مكتبات العملاء بلغات برمجة متنوعة للتفاعل مع الخدمات التي تتضمّن واجهات برمجة تطبيقات للبيانات. باستخدام هذه المكتبات، يمكنك إنشاء طلبات GData وإرسالها إلى إحدى الخدمات وتلقّي الردود.

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

لاستخدام مكتبة البرامج هذه، يجب أن يكون لديك الإصدار 1.5 من Java.

نزِّل مكتبة برامج Java.

تشير الأمثلة الواردة في هذا الدليل إلى Google Calendar API، ولكن هذا الدليل ليس دقيقًا أو محدّثًا لاستخدام Calendar API. للحصول على معلومات حول استخدام مكتبة برامج Java مع Data API لخدمة معيّنة، يُرجى الاطّلاع على المستندات الخاصة بالخدمة. على سبيل المثال، إذا كنت تعمل مع "تقويم Google"، اطّلِع على دليل مطوّري برامج واجهة برمجة التطبيقات لبيانات "تقويم Google".

المحتويات

  1. الجمهور
  2. نظرة عامة على نموذج البيانات
  3. برنامج تعليمي وأمثلة
    1. إنشاء عميلك وتشغيله
    2. طلب خلاصة
    3. إدراج عنصر جديد
    4. طلب إدخال بيانات معيّنة
    5. البحث عن إدخالات
    6. الاستعلام حسب الفئة
    7. تعديل عنصر
    8. حذف عنصر
  4. Reference

الجمهور

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

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

للحصول على معلومات مرجعية حول الفئات والطرق التي توفّرها مكتبة البرامج، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات لمكتبة برامج Java (بتنسيق Javadoc).

تم تصميم هذا المستند ليتم قراءته بالترتيب، حيث يعتمد كل مثال على الأمثلة السابقة.

نظرة عامة على نموذج البيانات

تستخدم مكتبة برامج Java مجموعة من الفئات لتمثيل العناصر التي تستخدمها Google Data APIs. على سبيل المثال، هناك فئة Feed تتوافق مع العنصر <atom:feed>، وتتضمّن طرقًا لإنشاء إدخال والحصول على قيم العناصر الفرعية المختلفة وتحديدها وما إلى ذلك. هناك أيضًا فئة Entry تتوافق مع العنصر <atom:entry>. لا يحتوي كل عنصر محدّد في Google Data APIs على فئته الخاصة. للحصول على التفاصيل، يُرجى الاطّلاع على المستندات المرجعية.

يمكن للمكتبة تحليل محتوى Atom تلقائيًا ووضع قيم عناصر Atom في الكائنات المناسبة. على سبيل المثال، يحصل الإجراء getFeed على خلاصة ويحلّلها ويعرض كائن خلاصة يتضمّن القيم الناتجة.

لإرسال خلاصة أو إدخال إلى خدمة، عليك إنشاء عنصر "خلاصة" أو "إدخال"، ثم استدعاء طريقة مكتبة (مثل الطريقة insert) لترجمة العنصر تلقائيًا إلى XML وإرساله.

يمكنك تحليل و/أو إنشاء XML بنفسك إذا كنت تفضّل ذلك، وأسهل طريقة لإجراء ذلك هي استخدام مكتبة مناسبة تابعة لجهة خارجية، مثل Rome.

وكما أنّ بنية XML في Google Data API قابلة للتوسيع، فإنّ نموذج العناصر المقابل قابل للتوسيع أيضًا. على سبيل المثال، توفّر مكتبة البرامج المساعدة فئات تتوافق مع العناصر المحدّدة في مساحة اسم Google Data.

البرنامج التعليمي والأمثلة

تعرض الأمثلة التالية كيفية إرسال طلبات مختلفة إلى Data API باستخدام مكتبة برامج Java.

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

إنشاء البرنامج وتشغيله

لتجميع الأمثلة في هذا المستند، عليك استخدام عبارات الاستيراد التالية:

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;
import java.net.URL;

طلب خلاصة

كما هو موضّح في مستند Google Calendar Data API، يمكنك طلب خلاصة "تقويم" من خلال إرسال طلب HTTP التالي إلى "تقويم Google":

GET http://www.google.com/calendar/feeds/userID/private/full

بالطبع، عليك استبدال userID بعنوان البريد الإلكتروني للمستخدم. راجِع مستند "تقويم Google" للحصول على التفاصيل. يمكنك بدلاً من ذلك استخدام عنوان URL التلقائي الخاص للتفاعل مع "تقويم Google" (كما هو موضّح في مستند "تقويم Google")، ولكن في هذا المستند سنستخدم عنوان URL الخاص بالخلاصة الكاملة الذي يحتوي على رقم تعريف المستخدم.

عليك أيضًا تقديم مستندات المصادقة المناسبة. تتمثّل الاختلافات الرئيسية بين هذا المثال والمثال الأول في مستند "تقويم Google" في أنّ (1) هذا المثال يتضمّن المصادقة، و (2) يستخدم هذا المثال فئة GoogleService الأكثر عمومية بدلاً من فئة CalendarService الخاصة بـ "تقويم Google".

يُرجى العِلم أنّ نظام المصادقة الذي نستخدمه هنا (المعروف باسم "مصادقة Google للتطبيقات المثبَّتة") مناسب فقط للاستخدام في تطبيقات العميل المثبَّتة، مثل برامج العميل على الكمبيوتر المكتبي، وليس للاستخدام في تطبيقات الويب. لمزيد من المعلومات عن المصادقة، يُرجى الاطّلاع على مستندات مصادقة حساب Google.

لطلب خلاصة "تقويم Google" باستخدام مكتبة عميل Java، لمستخدم عنوان بريده الإلكتروني هو "liz@gmail.com" وكلمة المرور هي "mypassword"، استخدِم الرمز التالي:

// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");

// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());

// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);

يمثّل الصف GoogleService اتصال عميل (مع المصادقة) بخدمة GData. يتضمّن الإجراء العام لإرسال طلب بحث إلى إحدى الخدمات باستخدام مكتبة برامج العميل الخطوات التالية:

  1. الحصول على عنوان URL المناسب أو إنشاؤه
  2. إذا كنت سترسل بيانات إلى إحدى الخدمات (على سبيل المثال، إذا كنت ستُدرج إدخالاً جديدًا)، عليك تحويل البيانات الأولية إلى عناصر باستخدام فئات مكتبة البرامج. (لا تنطبق هذه الخطوة إذا كنت تطلب خلاصة فقط، كما نفعل في هذا المثال).
  3. أنشئ مثيلاً جديدًا من GoogleService، مع ضبط اسم الخدمة (مثل "cl" لتقويم Google) واسم تطبيقك (بالتنسيق companyName-applicationName-versionID).
  4. اضبط بيانات الاعتماد المناسبة.
  5. حدِّد لمكتبة البرامج الإضافية الإضافات التي ستستخدمها الخلاصة، حتى تتمكّن المكتبة من تحليل الخلاصات التي يتم عرضها بشكل صحيح.
  6. استدعِ إحدى الطرق لإرسال الطلب وتلقّي أي نتائج.

تحدّد الطريقة setUserCredentials رقم التعريف وكلمة المرور للمستخدم الذي يرسل عميلك طلب البحث نيابةً عنه. تستخدِم الأمثلة الواردة في هذا المستند نظام المصادقة "المصادقة للتطبيقات المثبَّتة". لمزيد من المعلومات عن أنظمة المصادقة، يُرجى الاطّلاع على مستند مصادقة حساب Google.

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

لطلب خلاصة كاملة، عليك استدعاء الطريقة getFeed التي تأخذ عنوان URL وتعرض الخلاصة الكاملة المتوفّرة في عنوان URL هذا. سنوضّح كيفية إرسال طلبات بحث أكثر تحديدًا في وقت لاحق من هذا المستند.

مثل الطرق الأخرى في الفئة GoogleService، تعالج الدالة getFeed عمليات المصادقة وعمليات إعادة التوجيه حسب الحاجة.

إدراج عنصر جديد

لإنشاء حدث جديد في التقويم، يمكنك استخدام الرمز التالي:

URL postUrl =
  new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();

myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));

Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);

DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);

// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);

بعد ضبط عنوان URL، ننشئ عنصر EventEntry، ويتم اشتقاق EventEntry من فئة الأساس المجردة BaseEntry، وهي أيضًا الفئة الرئيسية للفئة Entry التي تمثّل عنصر <atom:entry>.

يمثّل الصف EventEntry نوع حدث. لمزيد من المعلومات، يُرجى الاطّلاع على مستند الأنواع. بالنسبة إلى الخدمات الأخرى غير "تقويم Google"، يمكنك إسناد الإدخال الذي تم إرجاعه إلى عنصر Entry بدلاً من عنصر EventEntry.

عنوان الإدخال هو TextConstruct، وهو فئة تحتوي على نص بأشكال مختلفة (نص عادي أو HTML أو XHTML). يتم تمثيل محتوى الإدخال بواسطة كائن Content، وهو فئة يمكنها الاحتفاظ بنص عادي أو أشكال أخرى من المحتوى، بما في ذلك XML والبيانات الثنائية. (ولكن يمكن أن تقبل الدالة setContent أيضًا قيمة TextConstruct).

يتم تمثيل كل مؤلف باسم ومعرّف موارد منتظم (URI) وعنوان بريد إلكتروني. (في هذا المثال، لن ندرج عنوان URI). يمكنك إضافة مؤلف إلى إدخال من خلال استدعاء الطريقة getAuthors().add الخاصة بالإدخال.

نحن نستخدم كائن GoogleService نفسه الذي أنشأناه في المثال السابق. في هذه الحالة، تكون الطريقة المطلوب استدعاؤها هي insert، والتي ترسل عنصرًا إلى عنوان URL المحدّد للإدراج.

تعرض الخدمة الإدخال الذي تم إنشاؤه حديثًا، والذي قد يحتوي على عناصر إضافية من إنشاء الخادم، مثل عنوان URL لتعديل الإدخال.

يتم إرجاع رموز حالة HTTP كاستثناءات.

الرمز أعلاه يعادل إرسال POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (مع المصادقة المناسبة) وتقديم إدخال في شكل نوع حدث.

طلب إدخال معيّن

تتيح لك التعليمة البرمجية التالية طلب الإدخال المحدّد الذي أدرجته في المثال السابق.

في سياق هذه السلسلة من الأمثلة، ليس من الضروري استرداد هذا الإدخال، لأنّ "تقويم Google" سبق أن عرض الإدخال الذي تم إدراجه، ولكن يمكن تطبيق الأسلوب نفسه كلما عرفت معرّف الموارد المنتظم الخاص بإدخال معيّن.

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

يحتوي الإدخال المُدرَج على طريقة، getSelfLink، تعرض عنصر Link يتضمّن عنوان URL الخاص بالإدخال. يحتوي الصف Link على الدالة getHref التي تعرض عنوان URL كسلسلة String، ويمكننا من خلالها إنشاء كائن عنوان URL.

بعد ذلك، ما علينا سوى استدعاء طريقة getEntry الخاصة بالخدمة للحصول على الإدخال.

يُرجى العِلم أنّنا نقدّم EventEntry.class كمَعلمة إلى getEntry، ما يشير إلى أنّنا نتوقّع تحديدًا أن تعرض الخدمة حدثًا بدلاً من مجرّد إدخال عادي. بالنسبة إلى الخدمات الأخرى غير "تقويم Google"، يمكنك تمرير Entry.class فقط بدلاً من ذلك.

الرمز أعلاه يعادل إرسال GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID إلى "تقويم Google" مع المصادقة المناسبة.

البحث عن إدخالات

لاسترداد أول نتيجة مطابقة من بحث بنص كامل، استخدِم الرمز التالي:

Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
  Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
  String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}

يبدأ هذا المثال بإنشاء عنصر Query يتألف في الغالب من عنوان URL بالإضافة إلى مَعلمات طلب البحث المرتبطة به. تحتوي كل مَعلمة من مَعلمات طلب البحث القياسية في GData على طريقة ضبط. يمكنك أيضًا ضبط مَعلمات طلب بحث مخصّصة لخدمة معيّنة باستخدام طريقة addCustomParameter.

بعد إنشاء Query، نمرّره إلى طريقة query في الخدمة، والتي تعرض خلاصة تحتوي على نتائج طلب البحث. يمكنك بدلاً من ذلك إنشاء عنوان URL بنفسك (عن طريق إلحاق مَعلمات طلب البحث بعنوان URL الخاص بالخلاصة) ثم استدعاء الطريقة getFeed، ولكن الطريقة query توفّر طبقة تجريد مفيدة حتى لا تضطر إلى إنشاء عنوان URL بنفسك.

تعرض الطريقة getEntries في الخلاصة قائمة بالإدخالات في الخلاصة، بينما تعرض الطريقة getEntries().size عدد الإدخالات في الخلاصة.

في هذه الحالة، إذا عرض الاستعلام أي نتائج، سنعيّن النتيجة الأولى المطابقة لكائن Entry. بعد ذلك، نستخدم طريقة getTitle().getPlainText للفئة Entry لاسترداد عنوان الإدخال وتحويله إلى نص.

الرمز أعلاه مكافئ لإرسال GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis إلى "تقويم Google".

الاستعلام حسب الفئة

ملاحظة: لا يربط "تقويم Google" التصنيفات بالأحداث، لذا لا يعمل هذا المثال مع "تقويم Google".

لاسترداد خلاصة تتضمّن جميع الإدخالات التي تتطابق مع البحث السابق عن النص الكامل والتي تنتمي إلى فئة معيّنة أو تحمل تصنيفًا معيّنًا، استخدِم الرمز التالي:

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

تمثّل الفئة Category بالطبع فئة سيتم استخدامها في فلتر الفئات. يمكن أن يحتوي الصف Query.CategoryFilter على فئات متعددة، ولكن في هذه الحالة، سننشئ فلترًا بفئة واحدة فقط.

بعد ذلك، نضيف عامل التصفية هذا إلى طلب البحث الحالي الذي لا يزال يحتوي على سلسلة طلب البحث بالنص الكامل من المثال السابق.

نستخدم مرة أخرى الطريقة query لإرسال طلب البحث إلى الخدمة.

إذا كان "تقويم Google" يسمح بالبحث عن فئة، سيكون الرمز أعلاه مكافئًا لإرسال GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis إلى "تقويم Google".

تعديل عنصر

لتعديل عنصر حالي، استخدِم الرمز التالي. في هذا المثال، نغيّر عنوان الإدخال الذي تم استرجاعه سابقًا من النص القديم ("لعب التنس مع دارسي") إلى "اجتماع مهم".

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

أولاً، نضبط عنوانًا جديدًا للإدخال الذي استرجعناه سابقًا. بعد ذلك، نحصل على عنوان URL للتعديل الخاص بالإدخال باستخدام الطريقة getEditLink. بعد ذلك، نستدعي الطريقة update للخدمة لإرسال الإدخال المعدَّل.

تعرض الخدمة الإدخال المعدَّل، بما في ذلك عنوان URL جديد للإصدار الجديد من هذا الإدخال. (لمزيد من المعلومات عن إصدارات الإدخالات، اطّلِع على قسم التزامن المتفائل في مستند مرجع البروتوكول).

إنّ الرمز أعلاه يعادل تقريبًا إرسال PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID إلى الخدمة، بالإضافة إلى الإدخال الجديد (بتنسيق Atom) لاستبدال الإدخال الأصلي.

حذف عنصر

لحذف الإدخال المعدَّل، استخدِم الرمز التالي:

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

عنوان URL الذي سيتم استخدامه للحذف هو نفسه عنوان URL للتعديل، لذا فإنّ هذا المثال يشبه المثال السابق إلى حد كبير، باستثناء أنّنا نستدعي الطريقة delete بدلاً من update.

الرمز أعلاه يعادل تقريبًا إرسال DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID إلى الخدمة.

مراجع

للحصول على معلومات مرجعية حول الفئات والطرق التي توفّرها مكتبة البرامج، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات لمكتبة برامج Java (بتنسيق Javadoc).

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