תחילת העבודה עם ספריית הלקוחות של Google לנתוני Java

סטפני ליו, צוות Google Data APIs
ספטמבר 2007
  1. מבוא
  2. יחסי תלות של התקנות
    1. ב-Windows
    2. ב-Mac OS X
    3. ב-Linux
  3. התקנה של ספריית הלקוח ב-Google Data
  4. הפעלת דגימות
  5. בניית אפליקציות משלכם
  6. סיכום
  7. נספח: הגדרת משתני סביבה

מבוא

מעולם לא היה קל להתחיל לפתח עם ממשק API לא מוכר, ולכן במאמר הזה תמצאו הוראות מפורטות להורדה ולהתקנה של ספריית לקוח ממשק ה-API של נתוני Google ("GData") של Java. אראה איך לקבל את כל התלות ולהגדיר את משתני הסביבה שדרושים לכם. תוך זמן קצר תמזגו שירותים שונים של GData!

משתמש בליקויפל?

כדאי לקרוא את המאמר Cuding in the Shade: Use Eclipse with Google Data APIs.

סוגי תלות של התקנה

בספריית GData Java של הלקוח יש את יחסי התלות החיצוניים הבאים. הקטעים הבאים מתארים איך להתקין את יחסי התלות האלה במערכת ההפעלה המועדפת עליך (או במערכת ההפעלה שאיתה נתקעת בעבודה).

  • JDK (ערכת פיתוח Java) גרסה 1.5 ומעלה
  • נמלי Apache גרסה 1.7 ומעלה
  • mail.gar's ב-Java Mail 1.4+ של Sun
  • activation.tar ב-JavaBeansActivationFramework של Sun. פעולה זו נדרשת רק עבור ממשקי API הספציפיים למדיה, כולל ממשק ה-API של נתוני רשימת המסמכים, ממשק ה-API של אלבומי Google וממשק API של נתונים של YouTube.
  • serverlet.gar's ב-Servlet API של גרסה 2.3 ואילך של Sun. חובה לעשות זאת רק אם מבצעים דגימות קוד בחבילות 'sample.authsub' או 'sample.gbase.recipe'.

כמה מיחסי התלות של .jar נדרשים רק עבור דגימות ספציפיות, אך כדי להימנע משגיאות build, מומלץ להשיג הכל. בוחרים את מערכת ההפעלה כדי להמשיך: Windows , Mac OS X או Linux.

התקנת ספריית הלקוח של Google Data

  1. נכנסים אל http://code.google.com/p/gdata-java-client/download/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 ולבדוק את קובץ ה-build של הדגימה. צריך לחפש את הקטע 'samples run'.

פתרון בעיות

אם ה-build נכשל עם הודעת שגיאה כמו:

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 ואילך. אפשר להיעזר בהוראות התלות שלמעלה כדי להוריד את הגרסה האחרונה של נמלה.

יצירת אפליקציות משלכם

השאלה הבאה היא איך ליצור אפליקציה משלכם. אני אעבור על תוכנית מקבילה בשם "שלום עולם!" באמצעות שירות יומן Google כדי להציג פונקציות בסיסיות. מידע מפורט יותר ניתן למצוא במדריך למפתחים של ספריית הלקוח Java, וכן במדריכים למפתחים למוצרים ספציפיים.

יוצרים קובץ בשם Calendar Test.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: סקירת התנועה מתוך התוכנית. איך להפעיל את הרישום מתוך ספריית הלקוח?

כך תוכלו להבין איך יוצרים אפליקציות באמצעות ספריית הלקוח. למידע מפורט יותר, עיינו בקטע הסיכום כדי לקבל רשימה של מדריכים למפתחים שזמינים לכל ממשק API של Google Data.

סיכום

אנחנו מקווים שעכשיו אתם יכולים ליצור ולהפעיל אפליקציות באמצעות ספריית הלקוח של GData Java. לא נכנסתי לאף אחד מסביבות הפיתוח המשולבות הפופולריות שאפשר להשתמש בהן, אבל כדאי לך לבדוק כלים פופולריים כמו Eclipse או NetBeans. הנה כמה קישורים נוספים שעשויים לעזור:

אם יש לכם שאלות לגבי השימוש בספריית לקוח של Java עם ממשק API כלשהו, תוכלו לפנות אלינו בפורומים הספציפיים ל-API.