דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

תוכן עניינים

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

קהל

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

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

מידע נוסף על המחלקות וה-methods שמסופקות על ידי ספריית הלקוח מופיע בחומר העזר בנושא 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

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

ה-method getRequestUrl משתמשת בפרמטרים הבאים (בהתאם לפרמטרים של השאילתה שבהם משתמש ה-handler של AuthSubRequest):

הבא: כתובת ה-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);

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

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

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 של הפוסט של השירות כפרמטר. לאחר מכן, ה-method מחזירה את הרשומה כפי שהיא אוחסנה על ידי 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);
}

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

ה-API של נתוני Blogger מאפשר לבקש קבוצת רשומות שתואמות לקריטריונים מסוימים, כמו בקשה לפרסום פוסטים בבלוג או לעדכון בטווח תאריכים נתון. כדי לעשות את זה, יוצרים אובייקט 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: המספר המקסימלי של רשומות שצריך להחזיר.
סידור לפי: הסדר שבו יש להחזיר רשומות, למשל lastmodified (ברירת המחדל), starttime או updated.
פרסום מינימלי, פרסום מקסימלי: הגבולות לתאריכי פרסום הרשומה.
start-index: האינדקס מבוסס 1 של התוצאה הראשונה שיש לאחזר (לחלוקה לדפים).
מעודכן דקות, מעודכן-מקסימום: הגבולות לתאריכי עדכון של רשומות. המערכת מתעלמת מהפרמטרים האלה של שאילתות, אלא אם הפרמטר orderby מוגדר ל-updated.

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

עדכון פוסטים

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

חזרה למעלה