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

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

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

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

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

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

תוכן עניינים

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

קהל

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

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

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

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

השיטה 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%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);

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

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

GoogleService.setAuthSubToken(sessionToken, null);

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

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

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

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

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

לדוגמה, כדי לשלוח שאילתה לפי טווח תאריכים, משתמשים בשיטות 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 הבאות:

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

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

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

עדכון פוסטים

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

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

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

מחיקת תגובות

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

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

חזרה למעלה