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

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

מבוא

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

משתמשים ב-Eclipse?

מומלץ לעיין במאמר Coding in the Shade: Using Eclipse with Google Data APIs.

יחסי תלות בהתקנות

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

  • ‫JDK (Java Development Kit) מגרסה 1.5 ואילך
  • ‫Apache Ant מגרסה 1.7 ואילך
  • ‫mail.jar ב-JavaMail API 1.4+‎ של Sun
  • ‫activation.jar ב-JavaBeansActivationFramework של Sun. הדרישה הזו חלה רק על ממשקי API ספציפיים למדיה, כולל Document List Data API, ‏ Picasa Web Album API ו-YouTube Data API.
  • ‫servlet.jar ב-Servlet API של Sun בגרסה 2.3 ואילך. זה נדרש רק אם מריצים דוגמאות קוד בחבילות sample.authsub או sample.gbase.recipe.

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

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

  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 כדי לבצע build וגם כדי להריץ את הדוגמאות.

כדי לבדוק שהתקנתם הכול בצורה נכונה, פותחים את שורת הפקודה, עוברים לספרייה 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 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!‎ באמצעות שירות היומן כדי להדגים פונקציונליות בסיסית. מידע מפורט יותר זמין במדריך למפתחים של ספריית הלקוח של 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());
}

במהלך ניפוי הבאגים, פעולה שימושית נוספת היא יצירת dump של ה-XML הגולמי. יש כלי שימושי שאפשר להשתמש בו כדי לעשות את זה בספרייה. מוודאים שבוצע ייבוא של samples.util.*. לאחר מכן, משליכים את הפיד או הרשומה.

CommonUtils.dump(resultFeed, System.out);

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

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

סיכום

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

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