استخدام مكتبة عميل جافا

يصف هذا المستند كيفية استخدام مكتبة عميل جافا لإرسال طلبات بحث واجهة برمجة التطبيقات لبيانات Google ("GData") وتفسير الاستجابات المعروضة.

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

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

لاستخدام مكتبة العميل هذه، يجب تشغيل جافا الإصدار 1.5.

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

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

الفهرس

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

الجمهور

تم إعداد هذا المستند لمبرمجي جافا الذين يرغبون في كتابة تطبيقات عميل يمكنها التفاعل مع خدمات GData.

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

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

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

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

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

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

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

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

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

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

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

ولجعلها أكثر واقعية، توضح هذه الأمثلة كيفية التفاعل مع خدمة معينة: تقويم Google. سنوضح الأماكن التي يختلف فيها التقويم عن خدمات Google الأخرى، وذلك لمساعدتك على تهيئة هذه الأمثلة لاستخدامها مع الخدمات الأخرى. لمزيد من المعلومات حول التقويم، راجع وثائق واجهة برمجة التطبيقات لبيانات تقويم Google.

إنشاء العميل وتشغيله

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

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، يمكنك طلب خلاصة التقويم من خلال إرسال طلب HTTP التالي إلى التقويم:

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

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

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

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

لطلب خلاصة تقويم باستخدام مكتبة عميل جافا، بالنسبة إلى مستخدم لديه عنوان البريد الإلكتروني "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" "للتقويم") واسم تطبيقك (بالشكل 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.)

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

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

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

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

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

طلب إدخال محدد

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

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

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

مَراجع

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

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