دليل مطوّري البرامج: Python

تتيح واجهة برمجة التطبيقات Blogger Data API لتطبيقات العملاء عرض محتوى Blogger وتحديثه على شكل خلاصات Google Data API.

يمكن أن يستخدم تطبيق العميل واجهة برمجة التطبيقات Blogger Blogger لإنشاء مشاركات مدونة جديدة، وتعديل مشاركات المدونة الحالية أو حذفها، وإجراء طلب بحث عن مشاركات المدونة التي تطابق معايير معينة.

بالإضافة إلى تقديم بعض المعلومات الأساسية حول إمكانات واجهة برمجة التطبيقات لواجهة برمجة تطبيقات Blogger، يقدّم هذا المستند أمثلة على تفاعلات "واجهة برمجة التطبيقات للبيانات" الأساسية باستخدام مكتبة برامج Python. إذا كنت مهتمًا بمعرفة المزيد عن البروتوكول الأساسي الذي تستخدمه المكتبة، ارجع إلى قسم البروتوكول في دليل مطوّر البرامج هذا.

المحتويات

  1. الجمهور
  2. البدء
    1. إنشاء حساب Blogger
    2. تشغيل نموذج الرمز
  3. المصادقة على خدمة Blogger
    1. مصادقة OAuth
    2. مصادقة الخادم الوكيل AuthSub
    3. مصادقة اسم المستخدم أو كلمة مرور ClientLogin
  4. استرداد قائمة بالمدونات
  5. إنشاء مشاركات
    1. نشر مشاركة مدونة
    2. إنشاء مسودة مشاركة مدونة
  6. استرداد المشاركات
    1. استرداد كل مشاركات المدونة
    2. استرداد المشاركات باستخدام معلَمات طلب البحث
  7. تعديل المشاركات
  8. حذف المشاركات
  9. التعليقات
    1. إنشاء تعليقات
    2. استرداد التعليقات
    3. حذف التعليقات

الجمهور

هذا المستند مخصّص للمبرمجين الذين يريدون كتابة تطبيقات عميل Python يمكنها التفاعل مع Blogger.

يفترض هذا المستند أنك تفهم الأفكار العامة وراء بروتوكول Google Data APIs.

للحصول على معلومات عامة بشأن واجهة برمجة التطبيقات لبيانات Blogger، راجع الدليل المرجعي للبروتوكول.

البدء

للحصول على مساعدة في إعداد مكتبة العميل، يمكنك الاطّلاع على دليل البدء.

تتطلّب مكتبة برامج Python الإصدار 2.2 أو إصدار أحدث من Python. بعد تنزيل مكتبة العميل، ستحتاج أيضًا إلى تنزيل حزمة ElementTree وتثبيتها.

إنشاء حساب Blogger

ننصحك بالاشتراك في حساب Blogger لأغراض الاختبار. تستخدم خدمة Blogger حسابات Google، لذلك إذا كان لديك حساب Google، ستكون جاهزًا.

جارٍ تنفيذ نموذج الرمز

يتوفّر نموذج عميل كامل يحتوي على كل نموذج الرمز المعروض في هذا المستند في ملف BloggerExample.py، ضمن الدليلgdata-python-client/samples/blogger/.

يجري نموذج العميل عمليات متعددة على المدونة المتوفرة لعرض كيفية استخدام واجهة برمجة التطبيقات لبيانات Blogger.

يمكنك تنفيذ النموذج باستخدام الوسيطات التالية:

python BloggerExample.py --email [email_address] --password [password]

لاستخدام الأمثلة الواردة في هذا المستند في رمزك الخاص، ستحتاج إلى العبارات التالية التالية: import

from gdata import service
import gdata
import atom

المصادقة مع خدمة Blogger

يمكنك الوصول إلى كلٍّ من الخلاصات العامة والخاصة باستخدام واجهة برمجة التطبيقات Data Blogger. ولا تتطلب الخلاصات العلنية أي مصادقة، ولكنها للقراءة فقط. وإذا كنت تريد تعديل المدونات، فيجب على العميل المصادقة قبل طلب الخلاصات الخاصة. ويمكنه المصادقة باستخدام أي من الطرق الثلاث التالية: مصادقة OAuth أو مصادقة الخادم الوكيل AuthSub أو مصادقة اسم المستخدم/كلمة مرور ClientLogin.

ولمزيد من المعلومات عن المصادقة باستخدام واجهات برمجة التطبيقات للبيانات في Google بشكل عام، يمكنك الاطّلاع على مستندات المصادقة.

تفترض معظم النماذج في الأقسام اللاحقة من هذا المستند أن لديك مثال GDataService تمت مصادقته.

مصادقة OAuth

للاطّلاع على مستندات حول مصادقة OAuth باستخدام مكتبة Python GData، يُرجى الاطّلاع على OAuth في مكتبات برامج بروتوكول بيانات البيانات من Google.

مصادقة الخادم الوكيل AuthSub

تستخدم تطبيقات الويب التي تحتاج إلى مصادقة مستخدميها في حسابات Google لمصادقة الخادم الوكيل AuthSub. لا يمكن لعامل الموقع الإلكتروني ورمز العميل الوصول إلى اسم المستخدم وكلمة المرور لمستخدم 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):

التالي
عنوان 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']

تمثّل قيمة الرمز المميّز هذا رمزًا مميّزًا للاستخدام لمرة واحدة. في هذا المثال، بعد تحديد session = True، يمكن استبدال هذا الرمز المميز برمز مميز لجلسة AuthSub باستخدام طريقة UpgradeToSessionToken، التي تطلب خدمة AuthSubSessionToken:

blogger_service = service.GDataService()
blogger_service.auth_token = authsub_token
blogger_service.UpgradeToSessionToken()

وهذا يعني أنّه يتم تمرير الرمز المميَّز لمرة واحدة إلى طريقة UpgradeToSessionToken، وتعرض واجهة AuthSub رمزًا مميَّزًا للجلسة.

يمكن للتطبيق بعد ذلك استخدام قيمة الرمز المميز للجلسة في التفاعلات اللاحقة مع Blogger. وترسل مكتبة العملاء الرمز المميّز تلقائيًا مع الطلبات.

مصادقة اسم المستخدم/كلمة المرور ClientLogin

استخدام مصادقة ClientLogin إذا كان البرنامج عميلاً مستقلاً لمستخدم واحد "installed;quot;; (مثل تطبيق سطح مكتب). ما عليك سوى استدعاء الطريقة 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 بنجاح.

لمزيد من المعلومات حول مصادقة ClientLogin، بما في ذلك نماذج الطلبات والردود، راجع مستندات المصادقة للتطبيقات المثبّتة.

ملاحظة: يمكنك استخدام الرمز المميّز نفسه لجميع الطلبات في جلسة معيّنة، مع عدم الحصول على رمز مميّز جديد لكل طلب من طلبات Blogger.

ملاحظة: كما هو موضّح في مستندات ClientLogin، قد يفشل طلب المصادقة وطلب اختبار CAPTCHA. إذا أردت أن تصدر Google تحدي اختبار CAPTCHA وتعالجه، أرسِل المستخدم إلى https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (بدلاً من إرسال عنوان URL لالتعامل مع اختبار CAPTCHA المذكور في مستندات ClientLogin).

استرداد قائمة المدونات

توفر واجهة برمجة التطبيقات لبيانات Blogger خلاصة تسرد المدونات لمستخدم محدد، وتُعرف هذه الخلاصة باسم "metafeed.&quot.

يستخدم نموذج الرمز التالي مثيل 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 إنشاء إدخالات مدونات جديدة ونشرها، بالإضافة إلى إنشاء مسودات للإدخالات.

ملاحظة: لا يمكن حاليًا تحديد مؤلف مخصّص للمشاركات. ستظهر جميع المشاركات الجديدة كما لو كان قد تم إنشاؤها من قِبل المستخدم الذي تمت مصادقته حاليًا.

نشر مشاركة مدونة

يمكنك استخدام مكتبة برامج 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 طلب مجموعة من الإدخالات التي تطابق معايير محددة، مثل طلب مشاركات المدونات التي تم نشرها أو تعديلها في نطاق زمني محدد. لإجراء ذلك، عليك إنشاء مثيل 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 للبيانات مع خصائص Query التالية:

فئات
يحدد الفئات (المعروفة أيضًا باسم التصنيفات) لفلترة نتائج الخلاصة. على سبيل المثال، تعرض http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie الإدخالات ذات التصنيفين Fritz وLaurie. لتحديد طلب البحث هذا حسب الفئة في مكتبة برامج Python، يمكنك استخدام query.categories = ['Fritz','Laurie',]
.
max_results
الحد الأقصى لعدد الإدخالات التي يمكن عرضها.
انشر_الحدّ الأدنى، تمّ نشره
الحد الأقصى للتواريخ المسموح بها لنشر المشاركات
فهرس_البدء
الفهرس المستند إلى نتيجة واحدة للنتيجة الأولى التي سيتم استردادها (للنقل).
update_min، update_max
الحدّ الأقصى المسموح به لتواريخ تعديل الإدخال. ويتم تجاهل معلَمات طلب البحث هذه ما لم يتم ضبط المعلَمة orderby على updated.

للحصول على مزيد من المعلومات عن معلَمات طلب البحث، يُرجى الاطّلاع على الدليل المرجعي لواجهة برمجة تطبيقات البيانات في Blogger والدليل المرجعي لواجهات برمجة التطبيقات للبيانات في Google.

جارٍ تعديل المشاركات

لتعديل مشاركة مدونة حالية، يجب أولاً استرداد الإدخال الذي تريد تعديله، ثم تعديله بعد ذلك، ثم إرساله إلى 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)

الرجوع إلى أعلى الصفحة