راهنمای توسعه دهنده: پایتون

Blogger Data API به برنامه های مشتری اجازه می دهد تا محتوای Blogger را در قالب فیدهای Google Data API مشاهده و به روز کنند.

برنامه مشتری شما می تواند از Blogger Data API برای ایجاد پست های وبلاگ جدید، ویرایش یا حذف پست های وبلاگ موجود و پرس و جو برای پست های وبلاگی که با معیارهای خاصی مطابقت دارند استفاده کند.

این سند علاوه بر ارائه پیش‌زمینه‌ای در مورد قابلیت‌های Blogger Data API، نمونه‌هایی از تعاملات پایه داده API را با استفاده از کتابخانه کلاینت پایتون ارائه می‌کند. اگر علاقه مند به درک بیشتر در مورد پروتکل اساسی که کتابخانه استفاده می کند، به بخش پروتکل این راهنمای توسعه دهنده مراجعه کنید.

مطالب

  1. مخاطب
  2. شروع کردن
    1. ایجاد حساب بلاگر
    2. اجرای کد نمونه
  3. احراز هویت در سرویس بلاگر
    1. احراز هویت OAuth
    2. احراز هویت پروکسی AuthSub
    3. احراز هویت نام کاربری/گذرواژه ClientLogin
  4. بازیابی لیستی از وبلاگ ها
  5. ایجاد پست ها
    1. انتشار پست وبلاگ
    2. ایجاد پیش نویس پست وبلاگ
  6. در حال بازیابی پست ها
    1. بازیابی همه پست های وبلاگ
    2. بازیابی پست ها با استفاده از پارامترهای پرس و جو
  7. به روز رسانی پست ها
  8. حذف پست ها
  9. نظرات
    1. ایجاد نظرات
    2. بازیابی نظرات
    3. حذف نظرات

مخاطب

این سند برای برنامه نویسانی در نظر گرفته شده است که می خواهند برنامه های کلاینت پایتون بنویسند که می توانند با بلاگر تعامل داشته باشند.

این سند فرض می‌کند که شما ایده‌های کلی پشت پروتکل Google Data APIs را درک می‌کنید.

برای اطلاعات عمومی مرجع Blogger Data API، به راهنمای مرجع پروتکل مراجعه کنید.

شروع کردن

برای راهنمایی در تنظیم کتابخانه سرویس گیرنده، به راهنمای شروع مراجعه کنید.

کتابخانه کلاینت پایتون به پایتون 2.2 یا جدیدتر نیاز دارد. پس از دانلود کتابخانه مشتری ، باید بسته ElementTree را نیز دانلود و نصب کنید.

ایجاد یک حساب کاربری بلاگر

ممکن است بخواهید برای اهداف آزمایشی برای یک حساب 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 Data API می توانید به فیدهای عمومی و خصوصی دسترسی داشته باشید. فیدهای عمومی نیازی به احراز هویت ندارند، اما فقط خواندنی هستند. اگر می‌خواهید وبلاگ‌ها را اصلاح کنید، مشتری شما باید قبل از درخواست فیدهای خصوصی، احراز هویت کند. این می تواند با استفاده از هر یک از سه روش احراز هویت کند: احراز هویت OAuth ، احراز هویت پروکسی AuthSub یا احراز هویت نام کاربری/گذرواژه ClientLogin .

برای اطلاعات بیشتر در مورد احراز هویت با APIهای Google Data به طور کلی، به مستندات احراز هویت مراجعه کنید.

اکثر نمونه‌های موجود در بخش‌های بعدی این سند فرض می‌کنند که شما یک نمونه GDataService تأیید شده دارید.

احراز هویت OAuth

برای مستندات مربوط به احراز هویت OAuth با استفاده از کتابخانه Python GData، لطفاً OAuth را در کتابخانه های سرویس گیرنده پروتکل داده Google مشاهده کنید.

احراز هویت پروکسی AuthSub

احراز هویت پراکسی AuthSub توسط برنامه‌های کاربردی وب استفاده می‌شود که باید کاربران خود را در حساب‌های Google احراز هویت کنند. اپراتور وب سایت و کد مشتری به نام کاربری و رمز عبور کاربر بلاگر دسترسی ندارند. در عوض، کلاینت توکن های AuthSub ویژه ای را دریافت می کند که به مشتری اجازه می دهد از طرف یک کاربر خاص عمل کند. برای اطلاعات بیشتر، به مستندات AuthSub مراجعه کنید.

وقتی کاربر برای اولین بار از برنامه شما بازدید می کند، هنوز احراز هویت نشده است. در این مورد، شما باید برخی از اطلاعات و لینکی را نمایش دهید که کاربر را به صفحه Google هدایت می کند تا درخواست شما برای دسترسی به وبلاگ خود را تأیید کند. کتابخانه کلاینت پایتون تابعی را برای ایجاد 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):

بعدی
آدرس صفحه ای که گوگل باید پس از احراز هویت کاربر را به آن هدایت کند.
دامنه
نشان می دهد که برنامه برای دسترسی به فیدهای Blogger درخواست یک رمز می کند. رشته scope مورد استفاده http://www.blogger.com/feeds/ است (البته با URL-encoded).
امن
نشان می دهد که آیا مشتری یک توکن امن درخواست می کند یا خیر.
جلسه
نشان می دهد که آیا رمز برگشتی را می توان با یک توکن چند منظوره (جلسه) مبادله کرد یا خیر.

مثال بالا تماسی را نشان می دهد که توکن ایمن درخواست نمی کند (مقدار 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 آنها را به آدرس اینترنتی که در پارامتر پرس و جو next URL AuthSubRequest مشخص کرده اید هدایت می کند. سیستم AuthSub یک نشانه احراز هویت را به عنوان مقدار پارامتر کوئری token به آن URL اضافه می کند. به عنوان مثال:

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 یک نشانه جلسه را برمی‌گرداند.

سپس برنامه شما می تواند از مقدار نشانه جلسه در تعاملات بعدی با بلاگر استفاده کند. کتابخانه مشتری به طور خودکار توکن را همراه با درخواست ها ارسال می کند.

احراز هویت نام کاربری/گذرواژه 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، از جمله درخواست‌ها و پاسخ‌های نمونه، به مستندات احراز هویت برای برنامه‌های نصب‌شده مراجعه کنید.

توجه : برای همه درخواست ها در یک جلسه معین از یک نشانه استفاده کنید. برای هر درخواست بلاگر یک نشانه جدید دریافت نکنید.

توجه : همانطور که در مستندات ClientLogin توضیح داده شده است، درخواست احراز هویت ممکن است با شکست مواجه شود و یک چالش CAPTCHA درخواست کند. اگر می‌خواهید Google چالش CAPTCHA را صادر و رسیدگی کند، کاربر را به https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger بفرستید (به جای URL مربوط به CAPTCHA که در اسناد ClientLogin ارائه شده است).

بازیابی لیستی از وبلاگ ها

Blogger Data API خوراکی را ارائه می دهد که وبلاگ ها را برای یک کاربر خاص فهرست می کند. آن خوراک به عنوان "متافید" شناخته می شود.

کد نمونه زیر از یک نمونه 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 به شما امکان ایجاد و انتشار مطالب جدید وبلاگ و همچنین ایجاد پیش نویس ورودی ها را می دهد.

توجه : تنظیم یک نویسنده سفارشی برای پست ها در حال حاضر پشتیبانی نمی شود. همه پست های جدید به گونه ای ظاهر می شوند که گویی توسط کاربر تأیید شده فعلی ایجاد شده اند.

انتشار پست وبلاگ

می توانید از کتابخانه مشتری پایتون برای انتشار مطالب جدید وبلاگ استفاده کنید.

ابتدا یک نمونه 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 با نشانی اینترنتی فید وبلاگ-پست تماس بگیرید: 

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 feed post که برای بازیابی پست ها استفاده می شود ساخته شده است.

Blogger Data API از ویژگی های Query زیر پشتیبانی می کند:

دسته بندی ها
دسته بندی ها (همچنین به عنوان برچسب شناخته می شود) را برای فیلتر کردن نتایج فید مشخص می کند. برای مثال، http://www.blogger.com/feeds/ blogID /posts/default/-/Fritz/Laurie ورودی‌هایی را با هر دو برچسب Fritz و Laurie برمی‌گرداند. برای تعیین پرس و جوی دسته بندی در کتابخانه مشتری پایتون، می توانید از query.categories = ['Fritz','Laurie',] استفاده کنید.
حداکثر_نتایج
حداکثر تعداد ورودی برای بازگشت.
منتشر شده_دقیقه، انتشار_حداکثر
محدوده تاریخ انتشار ورودی.
start_index
ایندکس بر اساس 1 اولین نتیجه ای که بازیابی می شود (برای صفحه بندی).
updated_min، updated_max
محدودیت در تاریخ های به روز رسانی ورودی. این پارامترهای پرس و جو نادیده گرفته می شوند مگر اینکه پارامتر orderby روی updated تنظیم شود.

برای اطلاعات بیشتر در مورد پارامترهای پرس و جو، به راهنمای مرجع API داده Blogger و راهنمای مرجع Google Data APIs مراجعه کنید.

به روز رسانی پست ها

برای به‌روزرسانی یک پست وبلاگ موجود، ابتدا ورودی مورد نظر برای به‌روزرسانی را بازیابی می‌کنید، سپس آن را تغییر می‌دهید و سپس با استفاده از روش Put آن را برای Blogger ارسال می‌کنید. قطعه کد زیر عنوان یک ورودی وبلاگ را تغییر می دهد، با این فرض که شما قبلاً ورودی را از سرور بازیابی کرده اید. 

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)

بازگشت به بالا