מדריך למפתחים: Java

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

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

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

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

תוכן עניינים

  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. מחיקת תגובות

קהל

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

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

מידע נוסף על המחלקות וה-methods שמסופקות על ידי ספריית הלקוח מופיע במאמרי העזרה של API של ספריית הלקוח של Java. במדריך העזר לפרוטוקול יש מידע כללי על השימוש ב-Blogger Data API.

איך מתחילים

לקבלת עזרה בהגדרה של ספריית הלקוח, מומלץ לעיין במדריך לתחילת העבודה.

כדי להשתמש בספריית הלקוח של Java צריך להשתמש ב-Java 1.5. אחרי שמורידים את ספריית הלקוח, קובץ java/lib/gdataclient-1.0.jar מכיל את הכיתות שצריך כדי להתחיל להשתמש בהן.

יצירת חשבון Blogger

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

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

קובץ הלקוח לדוגמה שפועל במלואו, שמכיל את כל הקוד לדוגמה שמוצג במסמך הזה, זמין בהפצה של ספריית הלקוח של Java, בספרייה gdata/java/sample/blogger/BloggerClient.java. הוראות ה-build וההפעלה נכללות באותה ספרייה בקובץ README.txt.

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

כדי לקבץ את הדוגמאות במסמך הזה בקוד משלכם, אתם צריכים את הצהרות ה-import הבאות:

import com.google.gdata.client.*;
import com.google.gdata.data.*;
import com.google.gdata.util.*;
import java.io.IOException;
import java.net.URL;

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

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

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

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

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

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

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

String next = "http://www.example.com/welcome.html";
String scope = "http://www.blogger.com/feeds/";
boolean secure = false;
boolean session = true;
String authSubLogin = AuthSubUtil.getRequestUrl(next, scope, secure, session);

ה-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%2Fwelcome.html

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

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

http://www.example.com/welcome.html?token=yourAuthToken

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

String token = AuthSubUtil.getTokenFromReply(urlFromAuthSub);
String sessionToken = AuthSubUtil.exchangeForSessionToken(token, null);

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

לאחר מכן האפליקציה יכולה להשתמש באסימון הסשן באינטראקציות הבאות עם Blogger. כדי להורות לספריית הלקוח של Java לשלוח באופן אוטומטי את אסימון הסשן עם כל בקשה, קוראים ל-method setAuthSubToken של האובייקט GoogleService:

GoogleService.setAuthSubToken(sessionToken, null);

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

אימות שם משתמש/סיסמה של ClientLogin

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

GoogleService myService = new GoogleService("blogger", "exampleCo-exampleApp-1");
myService.setUserCredentials("user@example.com", "secretPassword");

בקטע הקוד שלמעלה, אנחנו מעבירים שני פרמטרים ל-constructor של GoogleService. הפרמטר הראשון הוא שם השירות שאנחנו רוצים להשתמש בו. הפרמטר השני הוא שם האפליקציה, בפורמט הבא: companyName-applicationName-versionID.

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

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

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

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

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

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

public static void printUserBlogs(GoogleService myService)
    throws ServiceException, IOException {

  // Request the feed
  final URL feedUrl = new URL("http://www.blogger.com/feeds/default/blogs");
  Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

  // Print the results
  System.out.println(resultFeed.getTitle().getPlainText());
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
  }
}

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

יצירת פוסטים

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

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

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

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

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

public static Entry createPost(
    GoogleService myService, String blogID, String title,
    String content, String userName)
    throws ServiceException, IOException {
  // Create the entry to insert
  Entry myEntry = new Entry();
  myEntry.setTitle(new PlainTextConstruct(title));
  myEntry.setContent(new PlainTextConstruct(content));

  // Ask the service to insert the new entry
  URL postUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  return myService.insert(postUrl, myEntry);
}

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

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

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

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

public static Entry createPost(GoogleService myService, String blogId,
    String title, String content, String userName,
    Boolean isDraft)
    throws ServiceException, IOException {
  // Create the entry to insert
  Entry myEntry = new Entry();
  myEntry.setTitle(new PlainTextConstruct(title));
  myEntry.setContent(new PlainTextConstruct(content));
  myEntry.setDraft(isDraft);

  // Ask the service to insert the new entry
  URL postUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  return myService.insert(postUrl, myEntry);
}

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

אחזור פוסטים

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

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

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

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

public static void printAllPosts(
    GoogleService myService, String blogId)
    throws ServiceException, IOException {
  // Request the feed
  URL feedUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

  // Print the results
  System.out.println(resultFeed.getTitle().getPlainText());
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
  }
  System.out.println();
}

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

ה-API של נתוני Blogger מאפשר לבקש קבוצת רשומות שתואמות לקריטריונים מסוימים, כמו בקשה לפרסום פוסטים בבלוג או לעדכון בטווח תאריכים נתון. כדי לעשות את זה, יוצרים אובייקט Query ומעבירים אותו ל-method GoogleService.getQuery.

לדוגמה, כדי לשלוח שאילתה עם טווח תאריכים, משתמשים ב-methods setPublishedMin ו-setPublishedMax של האובייקט Query. קטע הקוד הבא מדפיסה את הכותרת של כל פוסט בבלוג שמתפרסם בין שעת ההתחלה לבין שעת הסיום:

public static void printDateRangeQueryResults(
    GoogleService myService, String blogId,
    DateTime startTime, DateTime endTime)
    throws ServiceException, IOException {
  // Create query and submit a request
  URL feedUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  Query myQuery = new Query(feedUrl);
  myQuery.setPublishedMin(startTime);
  myQuery.setPublishedMax(endTime);
  Feed resultFeed = myService.query(myQuery, Feed.class);

  // Print the results
  System.out.println(resultFeed.getTitle().getPlainText() +
      " posts between " + startTime + " and " + endTime);
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
    System.out.println("\t" + entry.getUpdated().toStringRfc822());
  }
  System.out.println();
}

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

ב-Blogger Data API יש תמיכה ב-Query methods הבאות:

addCategoryFilter
ציון קטגוריות (שנקראות גם תוויות) לסינון תוצאות הפיד. לדוגמה, הפונקציה http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie מחזירה רשומות עם התוויות Fritz וגם עם Laurie.
setMaxResults
מגדירים את מספר הרשומות המקסימלי שיוחזרו.
set publishedMin, setPublishedMax
הגדרת גבולות לתאריכי פרסום של רשומה.
setStartIndex
מגדירים אינדקס שמבוסס על 1 של התוצאה הראשונה שיש לאחזר (לחלוקה לדפים).
setUpdatedMin, setUpdatedMax
הגדרת גבולות לתאריכי עדכון של רשומות. המערכת מתעלמת מהפרמטרים האלה של שאילתות, אלא אם הפרמטר orderby מוגדר ל-updated.

הערה: בשלב זה אין הגדרות קבועות לפרמטר השאילתה orderby. אבל אם אתם צריכים להגדיר אותה, אתם עדיין יכולים להשתמש ב-method Query.addCustomParameter().

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

עדכון פוסטים

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

public static Entry updatePostTitle(
    GoogleService myService, Entry entryToUpdate, String newTitle)
    throws ServiceException, IOException {
  entryToUpdate.setTitle(new PlainTextConstruct(newTitle));
  URL editUrl = new URL(entryToUpdate.getEditLink().getHref());
  return myService.update(editUrl, entryToUpdate);
}

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

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

מחיקת פוסטים

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

public static void deletePost(
    GoogleService myService, String editLinkHref)
    throws ServiceException, IOException {
  URL deleteUrl = new URL(editLinkHref);
  myService.delete(deleteUrl);
}

תגובות

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

יצירת תגובות

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

public static Entry createComment(
    GoogleService myService, String blogID, String postId,
    String commentText)
    throws ServiceException, IOException {
  // Build the comment feed URI
  String commentsFeedUri = "http://www.blogger.com/feeds/" + blogID + "/" + postId + "/comments/default";
  URL feedUrl = new URL(commentsFeedUri);

  // Create a new entry for the comment and submit it to the GoogleService
  Entry myEntry = new Entry();
  myEntry.setContent(new PlainTextConstruct(commentText));
  return myService.insert(feedUrl, myEntry);
}

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

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

המערכת מאחזרת תגובות

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

public static void printAllComments(
    GoogleService myService, String blogID, String postId)
    throws ServiceException, IOException {
  // Build comment feed URI and request comments on the specified post
  String commentsFeedUri = "http://www.blogger.com/feeds/" + blogID + "/" + postId + "/comments/default";
  URL feedUrl = new URL(commentsFeedUri);
  Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

  // Display the results
  System.out.println(resultFeed.getTitle().getPlainText());
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" +
        ((TextContent) entry.getContent()).getContent().getPlainText());
    System.out.println("\t" + entry.getUpdated().toStringRfc822());
  }
  System.out.println();
}

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

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

מחיקת תגובות

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

public static void deleteComment(GoogleService myService, String editLinkHref)
    throws ServiceException, IOException {
  URL deleteUrl = new URL(editLinkHref);
  myService.delete(deleteUrl);
}

חזרה למעלה