بدء استخدام مكتبة برامج Google Data Java Client Library

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

مقدمة

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

هل تستخدم Eclipse؟

اطّلِع على المقالة Coding in the Shade: Using Eclipse with Google Data APIs.

تثبيت الحِزم التابعة

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

  • الإصدار 1.5 أو إصدار أحدث من حزمة تطوير Java‏ (JDK)
  • الإصدار 1.7 أو الإصدارات الأحدث من Apache Ant
  • ‫mail.jar في Sun's JavaMail API 1.4+
  • ‫activation.jar في JavaBeansActivationFramework من Sun هذا الإجراء مطلوب فقط لواجهات برمجة التطبيقات الخاصة بالوسائط، بما في ذلك Document List Data API وPicasa Web Album API وYouTube Data API.
  • ‫servlet.jar في الإصدار 2.3 أو الإصدارات الأحدث من Sun's Servlet API، وهذا مطلوب فقط عند تنفيذ عيّنات الرموز في حِزم "sample.authsub" أو "sample.gbase.recipe".

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

تثبيت مكتبة Google Data Client Library

  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 على اسم مستخدم وكلمة مرور صالحَين. يمكننا استخدام Ant لإنشاء العيّنات وتنفيذها.

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

أنشئ ملفًا باسم 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 Data API.

الخاتمة

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

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