מדריך למפתחים של ספריית הלקוח של ‎.NET

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

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

במסמך הזה מופיעות דוגמאות לשימושים נפוצים בגרסת C# ‎ של ספריית הלקוח, ואחריהן מידע נוסף על כתיבת לקוחות GData. בסוף המסמך הזה יש קישור למאמרי העזרה של ספריית הלקוח של C#, בפורמט NDoc.

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

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

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

תוכן עניינים

  1. קהל
  2. סקירה כללית של מודל הנתונים
  3. מדריך ודוגמאות
  4. חומרי עזר

קהל

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

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

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

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

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

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

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

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

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

בדוגמאות הבאות אפשר לראות איך לשלוח בקשות שונות של GData באמצעות ספריית הלקוח C#.

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

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

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

using Google.GData.Client;

בקשת פיד

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

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

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

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

כדי לבקש פיד של יומן באמצעות ספריית הלקוח C#, עבור משתמש עם כתובת האימייל jo@gmail.com והסיסמה mypassword, משתמשים בקוד הבא:

// Create a query and service object:

FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");

// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Tell the service to query:
AtomFeed calFeed = service.Query(query);

המחלקות Service מייצגות חיבור לקוח (עם אימות) לשירות GData. התהליך הכללי לשליחת שאילתה לשירות באמצעות ספריית הלקוח כולל את השלבים הבאים:

  1. משיגים או יוצרים את כתובת ה-URL המתאימה.
  2. אם אתם שולחים נתונים לשירות (לדוגמה, אם אתם מוסיפים רשומה חדשה), צריך להפוך את הנתונים הגולמיים לאובייקטים באמצעות המחלקות של ספריית הלקוח. (השלב הזה לא רלוונטי אם אתם רק מבקשים פיד, כמו בדוגמה הזו).
  3. יוצרים מופע חדש של Service, מגדירים את שם השירות (לדוגמה, "cl" ליומן) ואת שם האפליקציה (בפורמט companyName-applicationName-versionID).
  4. מגדירים את פרטי הכניסה המתאימים.
  5. קוראים למתודה כדי לשלוח את הבקשה ולקבל את התוצאות.

השיטה service.setUserCredentials מגדירה את המאפיין service.Credentials באמצעות אובייקט סטנדרטי של פרטי כניסה לרשת .NET. פרטי הכניסה מוגדרים כמזהה והסיסמה של המשתמש שבשמו הלקוח שולח את השאילתה. בדוגמאות שבמסמך הזה נעשה שימוש במערכת האימות Authentication for Installed Applications. למידע נוסף על מערכות אימות אחרות, אפשר לעיין במסמכי התיעוד בנושא Google Account Authentication.

כדי לבקש פיד שלם, קוראים לשיטה service.Query, שמקבלת אובייקט FeedQuery ומחזירה את הפיד כולו שנמצא בכתובת ה-URL הזו. בהמשך המאמר נסביר איך לשלוח שאילתות ספציפיות יותר.

בדומה לשיטות אחרות במחלקה Service, Query מטפלת באימות ובהפניות אוטומטיות לפי הצורך.

הוספת פריט חדש

כדי להוסיף פריט לפיד של יומן, אפשר להשתמש בקוד הבא:

AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March"; 
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth"; 
entry.Content.Content = "Meet for a quick lesson.";

Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);

אחרי שמגדירים את כתובת ה-URL, אנחנו יוצרים אובייקט AtomEntry.

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

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

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

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

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

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

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

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

FeedQuery singleQuery = new FeedQuery();
singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); 
AtomFeed newFeed = service.Query(singleQuery);
AtomEntry retrievedEntry = newFeed.Entries[0];

לרשומה שנוספה יש מאפיין, SelfUri, שמחזיר אובייקט AtomUri שאפשר להשתמש בו כדי ליצור אובייקט URI חדש באמצעות השיטה ToString() שלו.

לאחר מכן, צריך רק לקרוא לשיטת Query של השירות כדי לקבל אובייקט AtomFeed חדש, עם רשומה אחת בלבד באוסף הרשומות שלו.

הקוד שלמעלה שווה לשליחת GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID ליומן, עם אימות מתאים.

חיפוש רשומה

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

FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis"; 
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
  AtomEntry firstMatchEntry = myResultsFeed.Entries[0]; 
  String myEntryTitle = firstMatchEntry.Title.Text; 
}

בדוגמה הזו מתחילים ביצירת אובייקט FeedQuery, שמורכב בעיקר מכתובת URL בתוספת פרמטרים של שאילתה שמשויכים אליה. לכל אחד מפרמטרים השאילתה הרגילים של GData יש מאפיין.

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

האוסף Entries של הפיד מחזיר רשימה של הרשומות בפיד, והפונקציה Entries.Count מחזירה את מספר הרשומות בפיד.

במקרה הזה, אם השאילתה מחזירה תוצאות, אנחנו מקצים את התוצאה התואמת הראשונה לאובייקט AtomEntry. לאחר מכן משתמשים במאפיין Title של המחלקה AtomEntry כדי לאחזר את שם הרשומה.

הקוד שלמעלה שווה לשליחת GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis ליומן.

שאילתות לפי קטגוריה

הערה: יומן Google לא משייך תוויות לאירועים, ולכן הדוגמה הזו לא פועלת עם היומן.

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

AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);

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

לאחר מכן נוסיף את המסנן הזה לשאילתה הקיימת, שעדיין מכילה את מחרוזת השאילתה של הטקסט המלא מהדוגמה הקודמת.

אנחנו משתמשים שוב בשיטה Query כדי לשלוח את השאילתה לשירות.

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

עדכון פריט

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

retrievedEntry.Title.Text = "Important meeting";
retrievedEntry.Update();

קודם כל, מגדירים כותרת חדשה לרשומה שאותה אחזרנו קודם. אחרי זה פשוט מפעילים את השיטה Upate כדי לשלוח את הרשומה המעודכנת לשירות.

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

הקוד שלמעלה שווה בערך לשליחת PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID לשירות, יחד עם הרשומה החדשה (בפורמט Atom) כדי להחליף את הרשומה המקורית.

מחיקת פריט

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

updateEntry.Delete();

כתובת ה-URL שמשמשת למחיקה זהה לכתובת ה-URL לעריכה, ולכן הדוגמה הזו דומה מאוד לדוגמה הקודמת, חוץ מזה שאנחנו קוראים למתודה Delete במקום למתודה Update.

הקוד שלמעלה שווה בערך לשליחת DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID לשירות.

עבודה עם פידים של יומן Google

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

using Google.GData.Extensions;
using Google.GData.Calendar;

מרחב השמות Extensions עוסק בתוספים באופן כללי, ומרחב השמות Calendar מאפשר לכם לגשת לשירות יומן מותאם אישית, לפיד ולאובייקט שאילתה. דוגמה מפורטת יותר לשימוש בתוספים האלה מופיעה בספריית המשנה ‎ /Samples של התקנת C# API. האובייקטים הבאים נוספים:

EventQuery
מחלקת משנה של FeedQuery, שמאפשרת להגדיר שני פרמטרים מותאמים אישית לשירות היומן (start-min ו-start-max).
CalendarService
מחלקת משנה של שירות, שיכולה להחזיר פיד אירועים.
EventFeed
מחלקת משנה של AtomFeed, שחושפת EventEntries.
EventEntry
מחלקת משנה של AtomEntry, שיש לה מאפיינים נוספים שקשורים לנתוני לוח שנה.

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

חומרי עזר

מידע נוסף על ספריית הלקוח של C# זמין במאמרי העזרה.

חזרה למעלה