שימוש בספריית הלקוח של Java

במסמך הזה מוסבר איך להשתמש בספריית הלקוח של Java כדי לשלוח שאילתות ל-Google Data API ‏(GData) ולפרש את התגובות שמוחזרות.

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

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

כדי להשתמש בספריית הלקוח הזו, צריך להריץ Java 1.5.

מורידים את ספריית הלקוח של Java.

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

תוכן עניינים

  1. קהל
  2. סקירה כללית של מודל הנתונים
  3. מדריך ודוגמאות
    1. יצירה של לקוח והפעלתו
    2. בקשת פיד
    3. הוספת פריט חדש
    4. בקשה של רשומה ספציפית
    5. חיפוש רשומות
    6. שאילתות לפי קטגוריה
    7. עדכון פריט
    8. מחיקת פריט
  4. חומרי עזר

קהל

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

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

למידע על המחלקות והשיטות שספריית הלקוח מספקת, אפשר לעיין בהפניית API של ספריית הלקוח של Java (בפורמט Javadoc).

המסמך הזה מיועד לקריאה לפי הסדר, וכל דוגמה מבוססת על הדוגמאות הקודמות.

סקירה כללית על מודל הנתונים

ספריית הלקוח של Java משתמשת בקבוצה של מחלקות כדי לייצג את הרכיבים שמשמשים את Google Data APIs. לדוגמה, יש מחלקה Feed שמתאימה לאלמנט <atom:feed>. יש לה שיטות ליצירת רשומה, לקבלת ערכים של רכיבי משנה שונים ולהגדרתם וכן הלאה. יש גם מחלקה של רשומה, שמתאימה לאלמנט <atom:entry>. לא לכל רכיב שמוגדר ב-Google Data APIs יש מחלקה משלו. פרטים נוספים מופיעים במאמרי העזרה.

הספרייה יכולה לנתח באופן אוטומטי תוכן Atom ולהציב את הערכים של רכיבי Atom באובייקטים המתאימים. לדוגמה, השיטה getFeed מקבלת פיד, מנתחת אותו ומחזירה אובייקט Feed עם הערכים שמתקבלים.

כדי לשלוח פיד או רשומה לשירות, יוצרים אובייקט Feed או Entry, ואז קוראים לשיטה בספרייה (כמו השיטה insert) כדי לתרגם את האובייקט ל-XML ולשלוח אותו באופן אוטומטי.

אם אתם מעדיפים, אתם יכולים לנתח ו/או ליצור XML בעצמכם. הדרך הקלה ביותר לעשות זאת היא באמצעות ספרייה מתאימה של צד שלישי, כמו Rome.

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

מדריך ודוגמאות

בדוגמאות הבאות מוסבר איך לשלוח בקשות שונות ל-Data API באמצעות ספריית הלקוח של Java.

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

יצירה והפעלה של לקוח

כדי להדר את הדוגמאות במאמר הזה, צריך להשתמש בהצהרות הייבוא הבאות:

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 Calendar Data API, אפשר לבקש פיד של יומן על ידי שליחת בקשת ה-HTTP הבאה ליומן:

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

כמובן שצריך להחליף את userID בכתובת האימייל של המשתמש. פרטים נוספים זמינים במאמר בנושא יומן Google. במקום זאת, אפשר להשתמש בכתובת ה-URL המיוחדת שמוגדרת כברירת מחדל לאינטראקציה עם היומן (כפי שמתואר במסמך בנושא היומן), אבל במסמך הזה נשתמש בכתובת ה-URL הפרטית של הפיד המלא, שכוללת את מזהה המשתמש.

צריך גם לספק אימות מתאים. ההבדלים העיקריים בין הדוגמה הזו לבין הדוגמה הראשונה במסמך בנושא יומן הם ש-(1) הדוגמה הזו כוללת אימות, ו-(2) הדוגמה הזו משתמשת במחלקה הכללית יותר GoogleService ולא במחלקה CalendarService שספציפית ליומן.

שימו לב שמערכת האימות שבה אנחנו משתמשים כאן (שנקראת 'אימות Google לאפליקציות מותקנות') מתאימה לשימוש רק באפליקציות לקוח מותקנות, כמו לקוחות למחשב, ולא לשימוש באפליקציות אינטרנט. למידע נוסף על אימות, אפשר לעיין במסמכי התיעוד בנושא אימות חשבון Google.

כדי לבקש פיד של יומן באמצעות ספריית הלקוח של Java, עבור משתמש עם כתובת האימייל 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 מייצגות סוג של אירוע. מידע נוסף זמין במסמך בנושא סוגים. בשירותים אחרים מלבד היומן, יכול להיות שתקצו את הרשומה שהוחזרה לאובייקט Entry ולא לאובייקט EventEntry.

כותרת הרשומה היא TextConstruct, מחלקה שמכילה טקסט בצורות שונות (טקסט רגיל, HTML או XHTML). התוכן של הרשומה מיוצג על ידי אובייקט Content, מחלקה שיכולה להכיל טקסט פשוט או סוגים אחרים של תוכן, כולל XML ונתונים בינאריים. (אבל השיטה setContent יכולה לקבל גם TextConstruct).

כל מחבר מיוצג כשם, כ-URI וככתובת אימייל. (בדוגמה הזו, לא ציינו את ה-URI). כדי להוסיף מחבר לרשומה, קוראים לשיטה getAuthors().add של הרשומה.

אנחנו משתמשים באותו אובייקט GoogleService שיצרנו בדוגמה הקודמת. במקרה הזה, השיטה להפעלת הקריאה היא insert, ששולחת פריט לכתובת ה-URL שצוינה להוספה.

השירות מחזיר את הרשומה החדשה שנוצרה, שעשויה להכיל רכיבים נוספים שנוצרו על ידי השרת, כמו כתובת URL לעריכה של הרשומה.

קודי מצב HTTP מוחזרים כחריגים.

הקוד שלמעלה שווה לשליחת POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (עם אימות מתאים) ולציון רשומה בצורה של סוג אירוע.

בקשה לרשומה ספציפית

הקוד הבא מאפשר לבקש את הרשומה הספציפית שהכנסתם בדוגמה הקודמת.

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

חיפוש ערכים

כדי לאחזר את ההתאמה הראשונה מחיפוש טקסט מלא, משתמשים בקוד הבא:

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 יש שיטת setter. אפשר גם להגדיר פרמטרים מותאמים אישית של שאילתות לשירות מסוים באמצעות ה-method ‏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 לא משייך תוויות לאירועים, ולכן הדוגמה הזו לא פועלת עם היומן.

כדי לאחזר פיד שכולל את כל הרשומות שתואמות לחיפוש הקודם של טקסט מלא ושנמצאות בקטגוריה מסוימת או שיש להן תווית מסוימת, משתמשים בקוד הבא:

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 כדי לשלוח את השאילתה לשירות.

אם הייתה אפשרות לחפש קטגוריה ביומן, הקוד שלמעלה היה שווה לשליחת GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis ליומן.

עדכון פריט

כדי לעדכן פריט קיים, משתמשים בקוד הבא. בדוגמה הזו, אנחנו משנים את הכותרת של הרשומה שאוחזרה קודם מהטקסט הישן שלה ("טניס עם דרסי") ל"פגישה חשובה".

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

קודם כל, מגדירים כותרת חדשה לרשומה שאותה אחזרנו קודם. לאחר מכן מקבלים את כתובת ה-URL לעריכה של הרשומה באמצעות שיטת getEditLink. אחר כך אנחנו מפעילים את השיטה update של השירות כדי לשלוח את הרשומה המעודכנת.

השירות מחזיר את הרשומה המעודכנת, כולל כתובת URL חדשה לגרסה החדשה של הרשומה הזו. (מידע נוסף על גרסאות של רשומות זמין בקטע Optimistic concurrency במאמר protocol reference document).

הקוד שלמעלה שווה בערך לשליחת 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 לשירות.

חומרי עזר

למידע על המחלקות והשיטות שספריית הלקוח מספקת, אפשר לעיין בהפניית API של ספריית הלקוח של Java (בפורמט Javadoc).

חזרה למעלה