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

ستيفاني ليو، فريق Google Data APIs
أيلول (سبتمبر) 2007
  1. المقدمة
  2. تثبيت العناصر التابعة
    1. على نظام التشغيل Windows
    2. على نظام التشغيل Mac OS X
    3. على الأجهزة التي تعمل بنظام التشغيل Linux
  3. تثبيت "مكتبة برامج بيانات Google"
  4. تشغيل النماذج
  5. إنشاء تطبيقاتك الخاصة
  6. الخاتمة
  7. الملحق: إعداد متغيّرات البيئة

المقدمة

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

هل تريد استخدام Eclipse؟

يمكنك الاطّلاع على مقالة الترميز في الظل: استخدام Eclipse مع Google Data APIs.

تثبيت العناصر التابعة

تحتوي مكتبة عميل جافا بيانات GData على التبعيات الخارجية التالية. ستوضح الأقسام التالية كيفية تثبيت هذه التبعيات على نظام التشغيل المفضل لديك (أو نظام التشغيل الذي تعمل معه).

  • JDK (حزمة تطوير جافا) الإصدار 1.5 أو الأحدث
  • Apache Ant الإصدار 1.7 أو أحدث
  • mail.jar في واجهة برمجة تطبيقات جافا بلغة Sun الإصدار 1.4 أو الأحدث
  • activation.jar في إطار JavaBeansactivationFramework التابع للشمس. وهذا مطلوب فقط لواجهات برمجة التطبيقات الخاصة بالوسائط، بما في ذلك واجهة برمجة التطبيقات لبيانات قائمة المستندات وواجهة برمجة التطبيقات لألبومات الويب بيكاسا وواجهة برمجة التطبيقات لبيانات YouTube.
  • servlet.jar في الإصدار 2.3 من واجهة برمجة تطبيقات خدمة Servlet أو الإصدارات الأحدث. هذا الإجراء مطلوب فقط في حالة تنفيذ نماذج التعليمات البرمجية في حزم "sample.authsub" أو "sample.gbase.recipe".

هناك عدد قليل من تبعيات .jar مطلوبة فقط لعينات معينة، ولكن من الأفضل تجنب أخطاء الإصدار للحصول على كل شيء. اختر نظام التشغيل الذي تفضله للمتابعة: Windows أو Mac OS X أو Linux.

تثبيت مكتبة برامج "بيانات Google"

  1. انتقل إلى http://code.google.com/p/gdata-java-client/downloads/list
  2. نزِّل أحدث إصدار من مكتبة العميل (gdata-src.java-1.x.x.java.zip) والنماذج (gdata-samples.java-1.x.x.java.zip).
  3. استخرج مصدر مكتبة العميل على جهاز الكمبيوتر.
  4. انتقِل إلى gdata/java/build-src/build.properties وافتح الملف.
  5. عدِّل التبعيات الخارجية للإشارة إلى مواقع ملفات .jar على جهازك المحلي.

    6. ملاحظة: في نظام التشغيل Windows، تأكد من عدم استخدام الشرطة المائلة للخلف. على سبيل المثال:

    servlet.jar=C:\\Program Files\\Apache Software Foundation\\Tomcat 6.0\\lib\\servlet-api.jar

تشغيل النماذج

تقع جميع النماذج المتاحة ضمن gdata/java/sample من أرشيف gdata-samples.java-1.x.x.java.zip. يحتوي الملف gdata/java/build-samples/build.properties على جميع قيم الإدخال للعيّنات الواردة في المكتبة. اضبط sample.credentials.username وsample.credentials.password على اسم مستخدم وكلمة مرور صالحين. يمكننا استخدام النمل لتصميم العيّنات وتنفيذها.

اختبر لمعرفة ما إذا كنت قد ثبّت كل شيء بشكل صحيح من خلال فتح موجه الأوامر، والتغيير إلى الدليل gdata/java، والكتابة:

ant -f build-samples.xml sample.calendar.run

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

جرّب عيّنة أكثر تفاعلية من خلال كتابة:

ant -f build-samples.xml sample.spreadsheet.guidemo.run

لمعرفة كيفية تنفيذ نموذج معيّن، انتقِل إلى gdata/java/build-samples وتحقّق من ملف الإصدار الخاص بهذا النموذج. ابحث عن القسم samples run.

تحديد المشاكل وحلّها

إذا أخفق الإصدار مع ظهور رسالة خطأ مثل،

BUILD FAILED
Target 'core.sample.core.util.build' does not exist in this project. It is used from target 'sample.calendar.build'.

Total time: 0 seconds

أو رسالة خطأ مشابهة حول ملف مفقود مفقود من المشروع، فربما يرجع السبب إلى تشغيل إصدار قديم من Ant. اكتب ant -version للتأكد من أن جهازك يعمل بالإصدار 1.7 أو إصدار أحدث. يمكنك الرجوع إلى تعليمات التبعية أعلاه للحصول على أحدث إصدار من Ant.

إنشاء تطبيقاتك الخاصة

السؤال التالي هو كيفية إنشاء تطبيقك الخاص. سوف أنفذ برنامجًا مكافئًا لـ "Hello, World!" باستخدام خدمة التقويم لعرض الوظائف الأساسية. يمكن العثور على معلومات أكثر تفصيلاً في دليل مطوّري البرامج لمكتبة جافا، بالإضافة إلى أدلة مطوّري البرامج لكل منتج على حدة.

أنشئ ملفًا باسم CalendarTest.java. ابدأ بتضمين عبارات الاستيراد التالية.

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.acl.*;
import com.google.gdata.data.calendar.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;

import java.net.*;
import java.io.*;

import sample.util.*;

في ما يلي البرنامج بالكامل (بدون أي معالجة استثنائية).

public class CalendarTest {

    public static void main(String[] args) {
        CalendarService myService = new CalendarService("exampleCo-exampleApp-1.0");
        myService.setUserCredentials("root@gmail.com", "pa$$word");

        URL feedUrl = new URL("http://www.google.com/calendar/feeds/default/allcalendars/full");
        CalendarFeed resultFeed = myService.getFeed(feedUrl, CalendarFeed.class);

        System.out.println("Your calendars:");
        System.out.println();

        for (int i = 0; i < resultFeed.getEntries().size(); i++) {
          CalendarEntry entry = resultFeed.getEntries().get(i);
          System.out.println("\t" + entry.getTitle().getPlainText());
        }

    }
}

This little program will request all the calendars you own and display all the titles. It's a little longer than the canonical "Hello, World!" example, but it's very simple once we break it down. The first couple of lines creates a service object and sets the user credentials.

CalendarService myService = new CalendarService("exampleCo-exampleApp-1.0");
myService.setUserCredentials("root@gmail.com", "pa$$word");

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

URL feedUrl = new URL("http://www.google.com/calendar/feeds/default/allcalendars/full");

سينفذ السطر أدناه الأمر GET الفعلي على عنوان URL وسيضع الخلاصة الناتجة في كائن منظّم.

CalendarFeed resultFeed = myService.getFeed(feedUrl, CalendarFeed.class);

ستتكرر حلقة for أدناه خلال كل إدخال وتطبع العنوان. تجدر الإشارة إلى أنه يتم تخزين العنوان كـ TextConstruct، لذا يجب استدعاء وظيفة إضافية للحصول على النص العادي.

for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    CalendarEntry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
}

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

URL postURL = new URL("http://www.google.com/calendar/feeds/root@gmail.com/private/full");
CalendarEventEntry myEvent = new CalendarEventEntry();

//Set the title and description
myEvent.setTitle(new PlainTextConstruct("Pi Day Party"));
myEvent.setContent(new PlainTextConstruct("I am throwing a Pi Day Party!"));

//Create DateTime events and create a When object to hold them, then add
//the When event to the event
DateTime startTime = DateTime.parseDateTime("2007-03-14T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2007-03-14T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEvent.addTime(eventTimes);

// POST the request and receive the response:
CalendarEventEntry insertedEntry = myService.insert(postURL, myEvent);

هناك عملية شائعة أخرى تتمثل في إنشاء طلب بحث.

//Create a new query object and set the parameters
Query myQuery = new Query(feedURL);
myQuery.setFullTextQuery("Pi");

//Send the request with the built query URL
CalendarEventFeed myResultsFeed = myService.query(myQuery, CalendarEventFeed.class);

//Take the first match and print the title
if (myResultsFeed.getEntries().size() > 0) {
    CalendarEventEntry firstMatchEntry = new CalendarEventEntry();
    myResultsFeed.getEntries().get(0);
    System.out.println(firstMatchEntry.getTitle().getPlainText());
}

أثناء تصحيح الأخطاء، هناك عملية أخرى مفيدة هي حذف ملف XML الأولي. هناك أداة سهلة الاستخدام يمكنك استخدامها لتنفيذ ذلك في المكتبة. تأكد من استيراد samples.util.*. بعد ذلك، عليك تفريغ الخلاصة أو الإدخال.

CommonUtils.dump(resultFeed, System.out);

للحصول على أدوات أكثر دقة لتصحيح الأخطاء، اطّلع على مقالة تصحيح أخطاء برامج عملاء Google Data API: استكشاف الزيارات من داخل برنامجك لمعرفة كيفية تفعيل التسجيل من داخل مكتبة العميل.

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

الخاتمة

نأمل أن تكون قادرًا الآن على إنشاء التطبيقات وتشغيلها باستخدام مكتبة عملاء جافا داتا جاتا! لم أستعرض أيًا من برامج IDE الشائعة التي يمكنك استخدامها، ولكن ننصحك بالاطّلاع على الأدوات الرائجة مثل Eclipse أو NetBeans. في ما يلي بعض الروابط الإضافية التي قد تكون مفيدة:

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