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

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

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

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

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

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

תוכן עניינים

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

Audience

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

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

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

איך מתחילים

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

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

יצירת חשבון Blogger

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

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

לקוח לדוגמה שעובד באופן מלא ומכיל את כל הקוד לדוגמה שמוצג במסמך הזה, זמין בהפצה של ספריות לקוח ב-Java, תחת הספרייה gdata/java/sample/blogger/BloggerClient.java. הוראות לבנייה והפעלה מופיעות באותה ספרייה בקובץ 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.

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

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

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

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

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

הבא: כתובת ה-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 הוא כתובת האתר ש-AuthSub מצורף אליה:

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

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

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

GoogleService.setAuthSubToken(sessionToken, null);

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

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

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

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

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

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

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

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

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

ממשק ה-API של Blogger Data מספק עדכון שמפרט את הבלוגים של משתמש מסוים; העדכון הזה נקרא "metafeed."

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

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

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

מתבצע עדכון פוסטים

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

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

חזרה למעלה