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

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

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

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

תוכן עניינים

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

קהל

המסמך הזה מיועד למתכנתים שרוצים לכתוב אפליקציות לקוח ב-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.

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

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

אימות OAuth

למסמכי עזרה בנושא אימות OAuth באמצעות ספריית GData של Python, תוכלו לעיין במאמר OAuth בספריות הלקוח של Google Data Protocol.

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

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

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

בדוגמת הקוד הבאה נעשה שימוש במכונה מאומתת של 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 ומזהה הבלוג מוגדר ב-constructor כדי לאפשר גישה נוחה אליו מאוחר יותר. ברוב הדוגמאות הבאות במסמך הזה, הערך 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
המספר המקסימלי של הרשומות להחזרה.
published_min, ‏ published_max
הגבלות על תאריכי פרסום של רשומות.
start_index
האינדקס שמתחיל ב-1 של התוצאה הראשונה שאוחזרה (לצורך דפדוף).
updated_min, updated_max
הגבולות של תאריכי העדכון של הרשומות. המערכת מתעלמת מהפרמטרים האלה של השאילתה, אלא אם הפרמטר orderby מוגדר כ-updated.

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

עדכון פוסטים

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

חזרה למעלה