ממשק ה-API של Blogger Data מאפשר לאפליקציות לקוח להציג ולעדכן תוכן של Blogger בצורת פידים של Google Data API.
בעזרת אפליקציית הלקוח שלכם ב-Blogger Data API תוכלו ליצור פוסטים חדשים בבלוג, לערוך או למחוק פוסטים בבלוגים קיימים ולהגיש שאילתות על פוסטים בבלוג שתואמים לקריטריונים מסוימים.
בנוסף להסבר על היכולות של ה-Blogger API, המסמך הזה מספק דוגמאות לאינטראקציות בסיסיות ב-Data API באמצעות ספריית הלקוחות של Python. אם אתם רוצים לקבל מידע נוסף על הפרוטוקול שבו הספרייה משתמשת, עיינו בקטע 'פרוטוקול' במדריך הזה.
תוכן עניינים
Audience
המסמך הזה מיועד למתכנתים שרוצים לכתוב אפליקציות לקוח ב-Python שיכולות לתקשר עם Blogger.
ההנחה היא שהבנת את הרעיונות הכלליים שמאחורי פרוטוקול Google Data APIs.
לקבלת מידע כללי על קובצי עזר של Blogger Data API, ניתן לעיין במדריך העזר לפרוטוקול.
איך מתחילים
לקבלת עזרה בהגדרת ספריית הלקוח, אפשר לעיין במדריך לתחילת העבודה.
ספריית הלקוח ב-Python מחייבת Python 2.2 ואילך. אחרי שמורידים את ספריית הלקוחות, צריך גם להוריד ולהתקין את החבילה ElementTree.
יצירת חשבון Blogger
ייתכן שתרצו להירשם לחשבון Blogger למטרות בדיקה. Blogger משתמש בחשבונות Google, כך שאם כבר יש לכם חשבון Google, אתם מוכנים.
הרצת הקוד לדוגמה
קובץ לדוגמה מלא ופעיל, הכולל את כל הקוד לדוגמה המוצג במסמך זה, זמין בקובץ BloggerExample.py שבספרייה
gdata-python-client/samples/blogger/.
הלקוח לדוגמה מבצע מספר פעולות בבלוג שסופק כדי להדגים את השימוש ב-Blogger Data API.
תוכלו להריץ את הדוגמה עם הארגומנטים הבאים:
python BloggerExample.py --email [email_address] --password [password]
כדי להשתמש בדוגמאות במסמך זה בקוד שלכם, עליכם לספק את
ההצהרות הבאות import:
from gdata import service import gdata import atom
מתבצע אימות לשירות Blogger
ניתן לגשת גם לפיד ציבורי וגם לפיד פרטי באמצעות Blogger Data API. אין צורך באימות כלשהו עבור פידים ציבוריים, אבל הם לקריאה בלבד. אם אתם רוצים לשנות בלוגים, הלקוח שלכם צריך לבצע אימות לפני שיבקש פידים פרטיים. ניתן לאמת אותה באמצעות אחת משלוש גישות: אימות OAuth, אימות שרת proxy של AuthSub או אימות שם משתמש/סיסמה של ClientLogin.
למידע נוסף על אימות באמצעות ממשקי API של נתוני Google באופן כללי, ניתן לעיין במסמכי התיעוד.
רוב הדוגמאות בסעיפים הבאים במסמך הזה מבוססות על ההנחה שיש לך מופע GDataService מאומת.
אימות OAuth
לקבלת מידע על אימות OAuth באמצעות ספריית Python GData, ניתן לעיין ב-OAuth בספריות הלקוח של פרוטוקול Google Data.
אימות שרת proxy של AuthSub
אימות שרת proxy של AuthSub משמש את אפליקציות האינטרנט שצריכים לאמת את המשתמשים שלהן לחשבונות Google. למפעיל האתר ולקוד הלקוח אין גישה לשם המשתמש ולסיסמה של משתמש Blogger, אלא הלקוח מקבל אסימוני AuthSub מיוחדים שמאפשרים ללקוח לפעול בשם המשתמש. למידע מפורט יותר, ניתן לעיין בתיעוד של OAuthSub.
כשמשתמש מבקר באפליקציה שלכם לראשונה, הוא עדיין לא אומת. במקרה כזה, תצטרכו להציג חלק מהמידע וקישור שמפנה את המשתמש לדף Google כדי לאמת את הבקשה שלכם לגישה לבלוגים שלו. ספריית הלקוח ב-Python מספקת פונקציה ליצירת כתובת URL של דף Google. הקוד שבהמשך מאחזר את כתובת ה-URL של הדף AuthSubRequest:
def GetAuthSubUrl(): next = 'http://www.example.com/welcome.pyc' scope = 'http://www.blogger.com/feeds/' secure = False session = True blogger_service = service.GDataService() return blogger_service.GenerateAuthSubURL(next, scope, secure, session); authSubUrl = GetAuthSubUrl(); print '<a href="%s">Login to your Google account</a>' % authSubUrl
השיטה GenerateAuthSubURL מקבלת את הפרמטרים הבאים (בהתאם לפרמטרים של השאילתה שבהם נעשה שימוש ב-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.pyc
המשתמש לוחץ על הקישור לאתר של Google ומאמת את חשבון Google שלו.
אחרי שהמשתמש מאמת, מערכת AuthSub מפנה אותם לכתובת ה-URL שציינתם בפרמטר השאילתה next של כתובת ה-URL של AuthSubRequest. מערכת AuthSub מצרפת אסימון אימות לכתובת ה-URL הזו כערך של פרמטר השאילתה token. למשל:
http://www.example.com/welcome.pyc?token=yourAuthToken
יש כמה דרכים לאחזר את ערך האסימון מכתובת ה-URL. לדוגמה:
import cgi parameters = cgi.FieldStorage() authsub_token = parameters['token']
ערך האסימון הזה מייצג אסימון AuthSub לשימוש חד-פעמי. בדוגמה הזו, מכיוון ש-session = True צוין, ניתן להחליף את האסימון באסימון מסוג AuthSub בשיטה UpgradeToSessionToken, שמפעילה את השירות AuthSubSessionToken:
blogger_service = service.GDataService() blogger_service.auth_token = authsub_token blogger_service.UpgradeToSessionToken()
כלומר, אתם מעבירים את האסימון החד-פעמי לשיטה
UpgradeToSessionToken, וממשק AuthSub מחזיר אסימון סשן.
לאחר מכן, האפליקציה שלכם תוכל להשתמש בערך של אסימון הסשן במהלך האינטראקציות הבאות עם Blogger. ספריית הלקוח שולחת את האסימון באופן אוטומטי יחד עם בקשות.
אימות שם משתמש/סיסמה של ClientLogin
השתמש באימות ClientLogin אם הלקוח שלך הוא לקוח עצמאי ויחיד עבור משתמש יחיד (כגון אפליקציה למחשב). כל מה שצריך לעשות הוא לקרוא בשיטה ProgrammaticLogin() במכונה GDataService, וכל האינטראקציות הבאות עם Blogger יאומתו:
blogger_service = service.GDataService('user@example.com', 'secretPassword')
blogger_service.source = 'exampleCo-exampleApp-1.0'
blogger_service.service = 'blogger'
blogger_service.account_type = 'GOOGLE'
blogger_service.server = 'www.blogger.com'
blogger_service.ProgrammaticLogin()
בקטע הקוד שלמעלה, הגדרנו שלושה נכסים במכונה GDataService. הראשון הוא שם האפליקציה שלנו בפורמט companyName-applicationName-versionID.
השני הוא שם השירות שאנחנו רוצים לנהל איתו אינטראקציה. השלישי הוא כתובת השרת'.
חשוב לזכור שהמדיניות account_type מוגדרת באופן מפורש כ-GOOGLE. אם לא תגדירו את הפרמטר הזה, משתמשי G Suite לא יוכלו להשתמש בהצלחה ב-Blogger API.
למידע נוסף על אימות ClientLogin, כולל בקשות ותגובות לדוגמה, ניתן לעיין בתיעוד של אימות עבור יישומים מותקנים.
הערה: יש להשתמש באותו אסימון לכל הבקשות בסשן נתון; אין לרכוש אסימון חדש לכל בקשה ב-Blogger.
הערה: כפי שמתואר בתיעוד של ClientLogin, ייתכן שבקשת האימות תיכשל ותישלח בקשה לאימות CAPTCHA. אם אתם רוצים ש-Google תריץ את אתגר ה-CAPTCHA ומטפלת בו, שלחו את המשתמש אל
https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger
(ולא אל כתובת ה-URL לטיפול ב-CAPTCHA שצוינה במסמכי התיעוד של ClientLogin).
מתבצע אחזור של רשימת בלוגים
ממשק ה-API של Blogger Data מספק עדכון שמפרט את הבלוגים של משתמש מסוים; העדכון הזה נקרא "metafeed."
הקוד לדוגמה משתמש במופע GDataService מאומת כדי לאחזר את המטא-נתונים ולאחר מכן מדפיס את הכותרת של כל בלוג.
def PrintUserBlogTitles(blogger_service):
query = service.Query()
query.feed = '/feeds/default/blogs'
feed = blogger_service.Get(query.ToUri())
print feed.title.text
for entry in feed.entry:
print "\t" + entry.title.text
חשוב לשים לב לכתובת ה-URL שמשמשת את השיטה Get. זוהי ברירת המחדל של כתובת ה-URL של הפיד, והיא מחזירה רשימה של בלוגים למשתמש המאומת כרגע.
כדי לקבל גישה למשתמש אחר, אפשר לציין את מזהה המשתמש במקום default בכתובת ה-URL של המטא-פיד. מזהה המשתמש הוא מחרוזת הספרות שבסוף כתובת ה-URL של פרופיל המשתמש.
קטע הקוד שלמטה מראה איך לחלץ מזהה בלוג מהפיד. כדי לבצע פעולות יצירה, עדכון ומחיקה של פוסטים ותגובות, צריך להזין את מזהה הבלוג. קטע הקוד הבא בוחר את הבלוג הראשון שאוחזר למשתמש.
blog_id = feed.entry[0].GetSelfLink().href.split("/")[-1]
בדוגמה BloggerExample.py, נוצר כיתה BloggerExample, ומזהה הבלוג מוגדר בבנייה כדי לאפשר גישה נוחה בהמשך. ברוב הדוגמאות הבאות במסמך הזה, הפונקציה blog_id מועברת כמשתנה.
יצירת פוסטים
ה-Blogger Data API מאפשר ליצור ולפרסם רשומות חדשות בבלוג, וגם ליצור טיוטות של רשומות.
הערה: כרגע אין תמיכה בהגדרת מחבר מותאם אישית לפוסטים. כל הפוסטים החדשים יופיעו כאילו נוצרו על ידי המשתמש שאומת כרגע.
פרסום פוסט בבלוג
אפשר להשתמש בספריית הלקוחות ב-Python כדי לפרסם רשומות חדשות בבלוג.
קודם כל, עליך ליצור מופע של GDataEntry לייצוג הפוסט בבלוג.
לאחר מכן תוכלו להגדיר את הכותרת, התוכן ומאפיינים אחרים של הפוסט בבלוג.
לבסוף, יש להשתמש במופע GDataService כדי להוסיף את הפוסט. הנה דוגמה לאופן שבו אפשר לפרסם פוסט חדש בבלוג:
def CreatePublicPost(blogger_service, blog_id, title, content):
entry = gdata.GDataEntry()
entry.title = atom.Title('xhtml', title)
entry.content = atom.Content(content_type='html', text=content)
return blogger_service.Post(entry, '/feeds/%s/posts/default' % blog_id)
blogEntry = CreatePublicPost(blogger_service, blog_id,
title='I have the answer', content='Eureka! It is 42!')
יצירת טיוטה של פוסט בבלוג
טיוטות של פוסטים נוצרות באותו אופן כמו פוסטים ציבוריים, אבל עליכם להגדיר את רכיב התוסף draft במופע של GDataEntry. כדי ליצור את הפוסט בבלוג כטיוטה, מוסיפים את השורות המודגשות:
def CreateDraftPost(blogger_service, blog_id, title, content):
entry = gdata.GDataEntry()
entry.title = atom.Title('xhtml', title)
entry.content = atom.Content(content_type='html', text=content)
control = atom.Control()
control.draft = atom.Draft(text='yes')
entry.control = control
return blogger_service.Post(entry, '/feeds/%s/posts/default' % blog_id)
draftEntry = CreateDraftPost(blogger_service, blog_id,
title='I have the question',
content='What do you get if you multiply six by nine?')
אפשר להפוך פוסט של טיוטת פוסט לפוסט קיים על ידי אחזור
הטיוטה של הפוסט, הגדרה של מאפיין הטיוטה ל-no ואז
עדכון הפוסט. נטפל באחזור ובעדכון של הפוסטים בשני הקטעים הבאים.
המערכת מאחזרת פוסטים
בקטעים הבאים מתואר איך לאחזר רשימה של פוסטים בבלוג עם או בלי פרמטרים של שאילתה.
אתם יכולים ליצור שאילתה בפיד גלוי לכול של Blogger ללא אימות. לכן, אין צורך להגדיר פרטי כניסה או לבצע אימות AuthSub לפני אחזור פוסטים מבלוג ציבורי.
מתבצע אחזור של כל הפוסטים בבלוג
כדי לאחזר את הפוסטים של המשתמש, מתקשרים לשיטה GetFeed עם כתובת ה-URL של הפיד בפוסט בבלוג:
def PrintAllPosts(blogger_service, blog_id):
feed = blogger_service.GetFeed('/feeds/' + blog_id + '/posts/default')
print feed.title.text
for entry in feed.entry:
print "\t" + entry.title.text
print "\t" + entry.content.text
print "\t" + entry.updated.text
print
אחזור פוסטים באמצעות פרמטרים של שאילתה
בעזרת Blogger Data API תוכלו לבקש קבוצה של רשומות שתואמות לקריטריונים מסוימים, כגון בקשת פוסטים בבלוג שפורסמו או עודכנו בטווח תאריכים נתון. לשם כך, צריך ליצור מופע של Query ואז לקרוא לשיטה Get().
לדוגמה, כדי לשלוח שאילתה בטווח תאריכים, צריך להגדיר את המאפיינים published_min ו-published_min של המופע Query.
קטע הקוד הבא מדפיס את הכותרת ואת התוכן של כל פוסט בבלוג שמתפרסם בין שעת ההתחלה לבין שעת הסיום.
def PrintPostsInDateRange(blogger_service, blog_id, start_time='2007-04-01', end_time='2007-04-25'):
query = service.Query()
query.feed = '/feeds/' + blog_id + '/posts/default'
query.published_min = start_time
query.published_max = end_time
feed = blogger_service.Get(query.ToUri())
print feed.title.text + " posts between " + start_time + " and " + end_time
for entry in feed.entry:
print "\t" + entry.title.text
print "\t" + entry.content.text
print "\t" + entry.updated.text
print
שימו לב שהאובייקט Query נבנה באמצעות אותה כתובת URL של פיד פוסט המשמשת לאחזור פוסטים.
ה-Blogger Data API תומך ב-Query הנכסים הבאים:
- קטגוריות
- קביעת קטגוריות (נקראות גם תוויות) לסינון תוצאות הפיד. לדוגמה, הפונקציה
http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurieמחזירה רשומות עם התוויותFritzו-Laurie. כדי לציין את שאילתת הקטגוריה בספריית הלקוחות ב-Python, אפשר להשתמש ב-query.categories = ['Fritz','Laurie',] - max_results
- המספר המרבי של ערכים להחזרה.
- פורסם_מינ', פורסם_max
- הגבולות של תאריכי הפרסום.
- start_index
- האינדקס מבוסס-1 של התוצאה הראשונה שאוחזר (להחלפה).
- updated_min, updated_max
- הגבולות בתאריכי עדכון הרשומות. המערכת תתעלם מהפרמטרים של השאילתות האלה, אלא אם הפרמטר
orderbyמוגדר כ-updated.
למידע נוסף על פרמטרים של שאילתות, ניתן לעיין במדריך העזר לממשקי API של Blogger Data ובמדריך העזר לממשקי API של Google Data.
מתבצע עדכון פוסטים
כדי לעדכן פוסט קיים בבלוג, קודם צריך לאחזר את הרשומה שאתם רוצים לעדכן, ואז לשנות אותה ואז לשלוח אותה ל-Blogger בשיטה Put. קטע הקוד הבא משנה את הכותרת של רשומת בלוג, בהנחה שכבר אחזרת את הרשומה מהשרת.
def UpdatePostTitle(blogger_service, entry_to_update, new_title='The REAL answer'):
entry_to_update.title = atom.Title('xhtml', new_title)
return blogger_service.Put(entry_to_update, entry_to_update.GetEditLink().href)
הקוד שלמעלה מחזיר GDataEntry שמכיל את כל הפוסט המעודכן לאחרונה. כדי לעדכן נכסים אחרים, פשוט צריך להגדיר אותם במופע GDataEntry לפני שמתקשרים אל Put.
הערה: כרגע אין תמיכה בשינוי נתוני המחבר המשויכים לפוסטים.
מחיקת פוסטים
כדי למחוק פוסט, הוסיפו את כתובת ה-URL של עריכת הפוסט לשיטה Delete
באובייקט GDataService, כך:
def DeletePost(blogger_service, edit_link_href): blogger_service.Delete(edit_link_href)
תגובות
ה-Blogger Data API מאפשר ליצור, לאחזר ולמחוק תגובות. אין תמיכה בעדכון תגובות (וגם לא זמין בממשק האינטרנט).
יצירת תגובות
כדי לפרסם תגובה, צריך ליצור אובייקט GDataEntry ולהוסיף אותו באופן הבא:
def CreateComment(blogger_service, blog_id, post_id, comment_text='Mostly harmless'): feed_uri = '/feeds/' + blog_id + '/' + post_id + '/comments/default' entry = gdata.GDataEntry() entry.content = atom.Content(content_type='xhtml', text=comment_text) return blogger_service.Post(entry, feed_uri)
הערה: כרגע אפשר לפרסם תגובות רק בבלוג שבבעלות המשתמש המאומת.
הערה: בשלב זה אין תמיכה בהגדרת מחבר מותאם אישית לתגובות. כל התגובות החדשות יופיעו כאילו הן נוצרו על ידי המשתמש המאומת הנוכחי.
מתבצע אחזור של התגובות
ניתן לאחזר את התגובות לפוסט ספציפי דרך כתובת ה-URL של פיד התגובות:
def PrintAllComments(blogger_service, blog_id, post_id):
feed_url = '/feeds/' + blog_id + '/' + post_id + '/comments/default'
feed = blogger_service.Get(feed_url)
print feed.title.text
for entry in feed.entry:
print "\t" + entry.title.text
print "\t" + entry.updated.text
print
לחלופין, אפשר לקבל את התגובות מכל הפוסטים באמצעות כתובת ה-URL של פיד התגובות בבלוג:
http://www.blogger.com/feeds/blogID/comments/default
מחיקת תגובות
כדי למחוק תגובה, צריך להעביר את כתובת ה-URL לעריכת התגובה לשיטה Delete
באובייקט GDataService באופן הבא:
def DeleteComment(blogger_service, post_id, comment_id): feed_url = '/feeds/' + post_id + '/comments/default/' + comment_id blogger_service.Delete(feed_url)