מדריך למפתחים: .NET

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

Blogger Data API מאפשר לאפליקציות לקוח להציג ולעדכן תוכן ב-Blogger באמצעות פידים של Google Data API.

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

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

תוכן עניינים

  1. קהל
  2. תחילת העבודה
    1. יצירת חשבון Blogger
    2. הרצת הקוד לדוגמה
  3. אימות לשירות Blogger
    1. אימות שרת proxy של AuthSub
    2. אימות באמצעות שם משתמש/סיסמה ב-ClientLogin
  4. אחזור רשימת בלוגים
  5. יצירת פוסטים
    1. פרסום פוסט בבלוג
    2. יצירת טיוטה של פוסט בבלוג
  6. אחזור פוסטים
    1. אחזור כל הפוסטים בבלוג
    2. אחזור פוסטים באמצעות פרמטרים של שאילתות
  7. עדכון פוסטים
  8. מחיקת פוסטים
  9. תגובות
    1. יצירת תגובות
    2. אחזור תגובות
    3. מחיקת תגובות

קהל

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

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

למידע על הכיתות והשיטות שספריית הלקוח מספקת, ראו חומר העזר בנושא API של ספריית הלקוח ל-‎.NET. למידע כללי על Blogger Data API, אפשר לעיין במדריך למידע על הפרוטוקול.

תחילת העבודה

במדריך למתחילים תוכלו לקרוא איך מגדירים את ספריית הלקוח.

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

יצירת חשבון Blogger

כדאי להירשם לחשבון Blogger למטרות בדיקה. ב-Blogger נעשה שימוש בחשבונות Google, כך שאם כבר יש לכם חשבון Google, אתם מוכנים.

הרצת הקוד לדוגמה

לקוח לדוגמה שפועל באופן מלא, שמכיל את כל הקוד לדוגמה שמוצג במסמך הזה, זמין בפרויקט של ספריית הלקוח ב-‎ .NET. הדוגמה נמצאת בכתובת /trunk/clients/cs/samples/blogger/ConsoleSample.cs בכרטיסייה Source במאגר SVN.

לפני שמאגדים ומריצים את הדוגמה הזו, צריך לעדכן את הערכים של username,‏ password,‏ blogName ו-postId בערכים המתאימים. הערכים username ו-password מייצגים את פרטי הכניסה שמשמשים להתחברות ל-Blogger. הערך של blogName הוא ההתחלה של כתובת ה-URL של הבלוג ב-blogspot.

לקוח לדוגמה מבצע כמה פעולות בבלוג שסופק כדי להדגים את השימוש ב-Blogger Data API.

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

using Google.GData.Client;
using System.Net;
using System.Xml;
using System.Text.RegularExpressions;

אימות לשירות Blogger

אפשר לגשת לפידים ציבוריים ופרטיים באמצעות Blogger Data API. לא נדרשת אימות כדי לגשת לפידים ציבוריים, אבל הם ניתנים לקריאה בלבד. אם רוצים לשנות בלוגים, הלקוח צריך לבצע אימות לפני שהוא מבקש פידים פרטיים. הוא יכול לבצע אימות באמצעות אחת משתי גישות: אימות שרת proxy מסוג AuthSub או אימות באמצעות שם משתמש וסיסמה מסוג ClientLogin.

למידע נוסף על אימות באמצעות Google Data APIs באופן כללי, תוכלו לעיין במסמכי התיעוד בנושא אימות.

אימות שרת proxy של AuthSub

אימות שרת proxy של AuthSub משמש אפליקציות אינטרנט שצריכות לאמת את המשתמשים שלהן בחשבונות Google. למפעיל האתר ולקוד הלקוח אין גישה לשם המשתמש ולסיסמה של משתמש Blogger. במקום זאת, הלקוח מקבל אסימוני AuthSub מיוחדים שמאפשרים לו לפעול בשם משתמש מסוים. מידע מפורט יותר זמין במסמכי התיעוד של AuthSub.

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

נניח שההיפר-קישור הבא של ASP מוגדר בדף:

<asp:HyperLink ID="GotoAuthSubLink" runat="server"/>

לאחר מכן, כדי ליצור את כתובת ה-URL של AuthSubRequest לאפליקציה, צריך לבצע קריאה לספריית לקוח של ‎ .NET באופן הבא:

GotoAuthSubLink.Text = "Login to your Google Account";
GotoAuthSubLink.NavigateUrl =
  AuthSubUtil.getRequestUrl("http://www.example.com/RetrieveToken",
  "http://www.blogger.com/feeds/",
  false,
  true);

השיטה getRequestUrl מקבלת את הפרמטרים הבאים (התואמים לפרמטרים של השאילתה שבהם משתמש הטיפול בבקשת AuthSub):

הבא
כתובת ה-URL של הדף שאליו Google צריכה להפנות את המשתמש אחרי האימות.
היקף
מציין שהאפליקציה מבקשת אסימון כדי לגשת לפידים של Blogger. מחרוזת ההיקף שבה צריך להשתמש היא http://www.blogger.com/feeds/ (כמובן, מקודדת ככתובת URL).
מאובטח
הערך הזה מציין אם הלקוח מבקש אסימון מאובטח.
ביקור
הערך הזה מציין אם אפשר להמיר את האסימון שהוחזר לאסימון לשימוש רב-פעמי (סשן).

בדוגמה שלמעלה מוצגת קריאה שלא מבקשת אסימון מאובטח (הערך של secure הוא false). כתובת ה-URL של הבקשה שמתקבלת עשויה להיראות כך:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2FRetrieveToken

המשתמש עוקב אחרי הקישור לאתר של Google ומבצע אימות בחשבון Google שלו.

אחרי שהמשתמש עובר אימות, מערכת AuthSub מפנה אותו לכתובת ה-URL שציינתם בפרמטר השאילתה next בכתובת ה-URL של AuthSubRequest. מערכת AuthSub מצרפת אסימון אימות לכתובת ה-URL הזו, בתור הערך של פרמטר השאילתה token. לכן, אפשר לגשת לאסימון כמשתנה באובייקט Request.QueryString של דף ה-ASP. המשתמש מופנה לכתובת URL שנראית כך:

http://www.example.com/RetrieveToken?token=yourAuthToken

ערך האסימון הזה מייצג אסימון AuthSub לשימוש יחיד. בדוגמה הזו, מאחר שצוין session = true, אפשר להחליף את האסימון הזה באסימון סשן של AuthSub באופן הבא:

SessionsessionToken = AuthSubUtil.exchangeForSessionToken(Request.QueryStringtoken, null);

כלומר, מעבירים את האסימון לשימוש חד-פעמי לשיטה exchangeForSessionToken, יחד עם null (למצב לא רשום) או מפתח פרטי (למצב רשום), וממשק AuthSub מחזיר אסימון סשן. מידע נוסף על אפליקציות רשומות ומפתחות פרטיים זמין בקטע חתימה על בקשות במסמכי העזרה של AuthSub.

לאחר מכן, האפליקציה שלכם יכולה להשתמש בערך של אסימון הסשן באינטראקציות הבאות עם Blogger. כדי להורות לספריית הלקוח של ‎ .NET לשלוח באופן אוטומטי את כותרת ההרשאה (שמכילה את אסימון הסשן) עם כל בקשה, מבצעים את הפעולות הבאות:

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("blogger", "BloggerSampleApp");
authFactory.Token = SessionsessionToken.ToString();
Service service = new Service(authFactory.ApplicationName);
service.RequestFactory = authFactory;

אימות באמצעות שם משתמש/סיסמה ב-ClientLogin

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

Service service = new Service("blogger", "exampleCo-exampleApp-1");
service.Credentials = new GDataCredentials("user@example.com", "secretPassword");
GDataGAuthRequestFactory factory = (GDataGAuthRequestFactory) service.RequestFactory;
factory.AccountType = "GOOGLE";

בקטע הקוד שלמעלה, אנחנו מעבירים שני פרמטרים למבנה Service. הפרמטר הראשון הוא שם השירות שאנחנו רוצים לבצע איתו אינטראקציה. הפרמטר השני הוא שם האפליקציה שלנו בפורמט companyName-applicationName-versionID. אנחנו גם מגדירים את Service.RequestFactory כך שישתמש רק בסוג חשבון GOOGLE כדי לאפשר אימות תקין למשתמשים ב-G Suite.

למידע נוסף על אימות ClientLogin, כולל בקשות ותגובות לדוגמה, אפשר לעיין במאמר אימות לאפליקציות מותקנות.

הערה: צריך להשתמש באותו אסימון לכל הבקשות בסשן נתון, ולא לקבל אסימון חדש לכל בקשה ב-Blogger.

הערה: כפי שמתואר במסמכי העזרה של ClientLogin, ייתכן שבקשת האימות תיכשל ותתבקש השלמת אתגר CAPTCHA. אם רוצים ש-Google תיצור את האתגר של CAPTCHA ותטפל בו, צריך לשלוח את המשתמש אל https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (במקום לכתובת ה-URL לטיפול ב-CAPTCHA שמופיעה במסמכי העזרה של ClientLogin).

אחזור רשימת בלוגים

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

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

query.Uri = new Uri("http://www.blogger.com/feeds/default/blogs");
AtomFeed feed = null;
try
{
  feed = service.Query(query);
  foreach (AtomEntry entry in feed.Entries)
  {
    Console.WriteLine("Blog Title: " + entry.Title.Text);
  }
}

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

יצירת פוסטים

באמצעות Blogger Data API אפשר ליצור ולפרסם רשומות חדשות בבלוג, וגם ליצור טיוטות של רשומות.

בכל הדוגמאות הבאות מניחים שיש לכם אובייקט Service מאומת.

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

פרסום פוסט בבלוג

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

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

AtomEntry newPost = new AtomEntry();
newPost.Title.Text = "Marriage!";
newPost.Content = new AtomContent();
newPost.Content.Content = "<div xmlns='http://www.w3.org/1999/xhtml'>" +
  "<p>Mr. Darcy has <em>proposed marriage</em> to me!</p>" +
  "<p>He is the last man on earth I would ever desire to marry.</p>" +
  "<p>Whatever shall I do?</p>" +
  "</div>";
newPost.Content.Type = "xhtml";

Uri blogFeedUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
AtomEntry createdEntry = service.Insert(blogFeedUri, newPost);

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

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

יצירת טיוטה של פוסט בבלוג

טיוטות של פוסטים נוצרות באותו אופן שבו נוצרים פוסטים ציבוריים, אבל צריך להגדיר את המאפיין draft של האובייקט AtomEntry. כדי ליצור טיוטה של הפוסט שלמעלה, צריך להוסיף את השורה המודגשת:

AtomEntry newPost = new AtomEntry();
newPost.Title.Text = "Marriage!";
newPost.Content = new AtomContent();
newPost.Content.Content = "<div xmlns='http://www.w3.org/1999/xhtml'>" +
    "<p>Mr. Darcy has <em>proposed marriage</em> to me!</p>" +
    "<p>He is the last man on earth I would ever desire to marry.</p>" +
    "<p>Whatever shall I do?</p>" +
    "</div>";
newPost.Content.Type = "xhtml";
newPost.IsDraft = true;

Uri blogFeedUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
AtomEntry createdEntry = service.Insert(blogFeedUri, newPost);

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

אחזור פוסטים

בקטעים הבאים מוסבר איך לאחזר רשימה של פוסטים בבלוג, עם ובלי פרמטרים של שאילתות.

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

אחזור כל פוסטי הבלוג

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

query.Uri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
feed = service.Query(query);
Console.WriteLine(feed.Title.Text);
foreach (AtomEntry entry in feed.Entries)
{
  Console.WriteLine("Entry Title: " + entry.Title.Text);
}

אחזור פוסטים באמצעות פרמטרים של שאילתה

באמצעות Blogger Data API אפשר לבקש קבוצה של רשומות שתואמות לקריטריונים מסוימים, למשל לבקש פוסטים בבלוג שפורסמו או עודכנו בטווח תאריכים נתון. כדי לעשות זאת, יוצרים אובייקט FeedQuery ומעבירים אותו ל-method‏ Service.Query().

לדוגמה, כדי לשלוח שאילתה לפי טווח תאריכים, מגדירים את המאפיינים MinPublication ו-MaxPublication של האובייקט FeedQuery. קטע הקוד הבא מדפיס את השם של כל פוסט בבלוג שפורסם בין שעת ההתחלה לשעת הסיום שצוינו:

FeedQuery query = new FeedQuery();
query.Uri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
query.MinPublication = new DateTime(2006, 1, 1);
query.MaxPublication = new DateTime(2007, 4, 12);
AtomFeed feed = service.Query(query);
foreach (AtomEntry entry in feed.Entries)
{
  Console.WriteLine("  Entry Title: " + entry.Title.Text);
}

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

Blogger Data API תומך בפרמטרים הבאים של שאילתות:

alt
סוג הפיד שיוחזר, למשל atom (ברירת המחדל) או rss.
/category
מציינים קטגוריות (שנקראות גם תוויות) כדי לסנן את תוצאות הפיד. לדוגמה, http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie מחזירה רשומות עם התווית Fritz וגם עם התווית Laurie.
max-results
המספר המקסימלי של הרשומות להחזרה.
orderby
הסדר שבו המערכת מחזירה את הרשומות, למשל lastmodified (ברירת המחדל), starttime או updated.
published-min, ‏ published-max
הגבלות על תאריכי פרסום של רשומות.
start-index
האינדקס שמתחיל ב-1 של התוצאה הראשונה שאוחזרה (לצורך דפדוף).
updated-min, ‏ updated-max
הגבולות של תאריכי העדכון של הרשומות. המערכת מתעלמת מהפרמטרים האלה של השאילתה, אלא אם הפרמטר orderby מוגדר כ-updated.

מידע נוסף על פרמטרים של שאילתות זמין במדריך למפתחים של Blogger Data API ובמדריך למפתחים של Google Data APIs.

עדכון פוסטים

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

static AtomEntry EditEntry(AtomEntry toEdit)
{
  // Edit the entry by changing the Title and calling Update().
  if (toEdit != null)
  {
    toEdit.Title.Text = "Marriage Woes!";
    toEdit = toEdit.Update();
  }
  return toEdit;
}

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

הערה: בשלב הזה אין תמיכה בשינוי נתוני המחבר שמשויכים לפוסטים.

מחיקת פוסטים

כדי למחוק פוסט, קוראים ל-method‏ Delete באובייקט AtomEntry קיים, כך:

static void DeleteEntry(AtomEntry toDelete)
{
  // Delete the edited entry
  if (toDelete != null)
  {
    toDelete.Delete();
  }
}

תגובות

Blogger Data API מאפשר ליצור, לאחזר ולמחוק תגובות. אין תמיכה בעדכון תגובות (והאפשרות הזו לא זמינה בממשק האינטרנט).

יצירת תגובות

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

AtomEntry comment;
comment = new AtomEntry();
comment.Title.Text = "This is my first comment";
comment.Content.Content = "This is my first comment";
Uri commentPostUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/" + entryId + "/comments/default");
postedComment = service.Insert(commentPostUri, comment);

הערה: בשלב הזה אפשר לפרסם תגובות רק בבלוג שבבעלות המשתמש המאומת.

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

אחזור תגובות

אפשר לאחזר את התגובות לפוסט מסוים מכתובת ה-URL של פיד התגובות של הפוסט:

static void ListEntryComments(Service service, Uri commentUri)
{
  if (commentUri != null)
  {
    // Retrieve all comments on a blog entry
    FeedQuery query = new FeedQuery();
    query.Uri = commentUri;
    AtomFeed feed = service.Query(query);
    foreach (AtomEntry entry in feed.Entries)
    {
      Console.WriteLine("  Comment Title: " + entry.Title.Text);
    }
  }
}

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

http://www.blogger.com/feeds/blogID/comments/default

מחיקת תגובות

כדי למחוק תגובה, צריך לבצע קריאה ל-method‏ Delete() על אובייקט AtomEntry קיים של תגובה, באופן הבא:

static void DeleteComment(AtomEntry commentEntry)
{
  if (commentEntry != null)
  {
    // Delete the comment.
    commentEntry.Delete();
  }
}

חזרה למעלה