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

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

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

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

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

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

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

תוכן עניינים

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

Audience

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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, ששולחת פריט לכתובת האתר שצוינה להוספה.

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

הקוד שלמעלה מקביל לשליחת 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 שניתן להשתמש בו בשיטת ToString() כדי ליצור אובייקט URI חדש.

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

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

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

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

שאילתת אירוע
קבוצת משנה של FeedQuery, המאפשרת להגדיר שני פרמטרים מותאמים אישית עבור שירות יומן Google (start-min ו-start-max).
שירות יומן
סוג משנה של שירות, שיכול להחזיר פיד של אירוע.
פיד אירועים
קבוצת משנה של AtomFeed, שחושפת אירועי Entry.
כניסה לאירוע
קבוצת משנה של AtomEntry, שיש לה מאפיינים נוספים שקשורים לנתוני יומן.

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

מקורות מידע

מידע על ספריית הלקוח C# זמין במסמכי התיעוד.

חזרה למעלה