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

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

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

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

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

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

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

תוכן עניינים

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

Audience

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

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

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

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

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

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

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

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

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

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

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

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

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

איך שולחים פיד

כמתואר במסמך ממשק ה-API לנתוני יומן Google , תוכל לבקש עדכון יומן על ידי שליחת בקשת ה-HTTP הבאה ליומן:

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

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

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

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

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

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

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

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

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

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

חזרה למעלה