دليل المطور: .NET

ملاحظة مهمة: هذه نسخة قديمة من هذه الصفحة. للحصول على أحدث إصدار، استخدِم الروابط في شريط القوائم العلوي على يمين الصفحة.

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

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

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

المحتويات

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

الجمهور

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

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

للحصول على معلومات مرجعية حول الفئات والأساليب التي تقدّمها مكتبة العميل، اطّلِع على مرجع واجهة برمجة التطبيقات لمكتبة العميل لنظام ‎.NET. للحصول على معلومات عامة حول مرجع Blogger Data API، يُرجى الاطّلاع على دليل مرجع البروتوكول.

الخطوات الأولى

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

لاستخدام مكتبة عملاء .NET، ستحتاج إلى وقت تشغيل .NET 1.1، ويجب أيضًا أن تكون مثبّتًا لديك كل الرقع. بعد تنزيل مكتبة العميل، ستجد ملفات DLL التي تحتاج إليها للبدء في الدليل الفرعي lib/Release ضمن التوزيع.

إنشاء حساب على Blogger

ننصحك بإنشاء حساب على Blogger لأغراض الاختبار. يستخدم Blogger حسابات Google، لذا إذا كان لديك حساب على Google، لن تحتاج إلى إجراء أي إعدادات.

تشغيل نموذج الرمز

يتوفّر في مشروع مكتبة برامج العملاء .NET نموذج كامل لعمل العميل يحتوي على كل رمز النموذج المعروض في هذا المستند. يمكن العثور على العيّنة في /trunk/clients/cs/samples/blogger/ConsoleSample.cs ضمن علامة التبويب "المصدر" في مستودع SVN.

قبل تجميع هذا العيّنة وتشغيلها، عدِّل قيم username وpassword وblogName و postId بالقيم المناسبة. تمثّل قيمتَا username و password بيانات الاعتماد المستخدَمة لتسجيل الدخول إلى Blogger. القيمة blogName هي بداية عنوان URL الخاص بمدونتك على blogspot.

ينفِّذ نموذج العميل عدّة عمليات على المدونة المقدَّمة لشرح استخدام Blogger Data API.

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

using Google.GData.Client;
using System.Net;
using System.Xml;
using System.Text.RegularExpressions;

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

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

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

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

تستخدِم تطبيقات الويب المصادقة الوكيلة عبر AuthSub التي تحتاج إلى مصادقة المستخدمين على حسابات Google. لا يمكن لمشغّل الموقع الإلكتروني ورمز العميل الوصول إلى اسم مستخدم Blogger وكلمة مروره، وبدلاً من ذلك، يحصل العميل على رموز AuthSub خاصة تسمح له بالتصرّف نيابةً عن مستخدم معيّن. للحصول على معلومات أكثر تفصيلاً، يُرجى الاطّلاع على مستندات AuthSub.

عندما يزور مستخدم تطبيقك لأول مرة، لا يكون قد تم مصادقته بعد. في هذه الحالة، عليك عرض بعض المعلومات ورابط يؤدي إلى توجيه المستخدم إلى صفحة على Google لمصادقة طلبك للوصول إلى مدوّناته.

لنفترض أنّه تم تحديد الرابط التشعّبي التالي لبرنامج ASP في صفحتك:

<asp:HyperLink ID="GotoAuthSubLink" runat="server"/>

بعد ذلك، لإنشاء عنوان URL لطلب AuthSub لتطبيقك، يمكنك إجراء استدعاء مكتبة عملاء ‎ .NET على النحو التالي:

GotoAuthSubLink.Text = "Login to your Google Account";
GotoAuthSubLink.NavigateUrl =
  AuthSubUtil.getRequestUrl("http://www.example.com/RetrieveToken",
  "http://www.blogger.com/feeds/",
  false,
  true);

تأخذ الطريقة getRequestUrl المَعلمات التالية (المتوافقة مع مَعلمات طلب البحث المستخدَمة من قِبل معالِج 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%2FRetrieveToken

يتّبع المستخدم الرابط المؤدي إلى موقع Google الإلكتروني ويُثبِّت هويته في حسابه على Google.

بعد مصادقة المستخدم، يعيد نظام AuthSub توجيهه إلى عنوان URL الذي حدّدته في مَعلمة طلب البحث next لعنوان URL AuthSubRequest. يُلحق نظام AuthSub رمزًا مميّزًا للمصادقة بهذا العنوان، وذلك بصفته قيمة مَعلمة طلب البحث token. لذلك، يمكن الوصول إلى الرمز المميّز كمتغيّر في عنصر Request.QueryString لصفحة ASP. تتم إعادة توجيه المستخدِم إلى عنوان URL على النحو التالي:

http://www.example.com/RetrieveToken?token=yourAuthToken

تمثّل قيمة الرمز المميّز هذا رمزًا مميزًا لبروتوكول AuthSub صالحًا لمرة واحدة. في هذا المثال، بما أنّه تم تحديد session = true، يمكن تبادل هذا الرمز المميّز مقابل رمز مميّز لجلسة AuthSub، على النحو التالي:

SessionsessionToken = AuthSubUtil.exchangeForSessionToken(Request.QueryStringtoken, null);

وهذا يعني أنّك تُمرِّر رمز التفعيل المخصّص للاستخدام لمرة واحدة إلى exchangeForSessionToken، مع null (للوضع غير المسجَّل) أو مفتاح خاص (للوضع المسجَّل)، وتُعرِض واجهة AuthSub رمز تمييز جلسة. لمزيد من المعلومات حول التطبيقات المسجَّلة والمفاتيح الخاصة، اطّلِع على قسم توقيع الطلبات في مستندات AuthSub.

يمكن لتطبيقك بعد ذلك استخدام قيمة رمز الجلسة في التفاعلات التالية مع Blogger. لطلب من مكتبة برامج ‎ .NET إرسال عنوان التفويض (الذي يحتوي على رمز مميّز للجلسة) تلقائيًا مع كل طلب، عليك اتّباع الخطوات التالية:

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("blogger", "BloggerSampleApp");
authFactory.Token = SessionsessionToken.ToString();
Service service = new Service(authFactory.ApplicationName);
service.RequestFactory = authFactory;

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

استخدِم مصادقة ClientLogin إذا كان برنامجك هو برنامج مستقل ومُثبَّت لمستخدم واحد (مثل تطبيق مخصّص لأجهزة الكمبيوتر المكتبي). اضبط بيانات اعتماد عنصر الخدمة على النحو التالي:

Service service = new Service("blogger", "exampleCo-exampleApp-1");
service.Credentials = new GDataCredentials("user@example.com", "secretPassword");
GDataGAuthRequestFactory factory = (GDataGAuthRequestFactory) service.RequestFactory;
factory.AccountType = "GOOGLE";

في المقتطف أعلاه، نمرر مَعلمتَين إلى الدالة الإنشائية Service. المعلمة الأولى هي اسم الخدمة التي نريد التفاعل معها. المَعلمة الثانية هي اسم تطبيقنا في التنسيق companyName-applicationName-versionID. ولقد أعددنا Service.RequestFactory أيضًا لاستخدام نوع حسابGOOGLE فقط للسماح بالمصادقة المناسبة لمستخدمي G Suite.

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

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

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

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

توفّر Blogger Data API خلاصة تسرد المدونات الخاصة بمستخدم معيّن، وتُعرف هذه الخلاصة باسم "الخلاصة الوصفية".

يستخدم نموذج الرمز البرمجي التالي عنصر Service تم مصادقةه لاسترداد الخلاصة الوصفية ثم يطبع عنوان كل مدونة.

query.Uri = new Uri("http://www.blogger.com/feeds/default/blogs");
AtomFeed feed = null;
try
{
  feed = service.Query(query);
  foreach (AtomEntry entry in feed.Entries)
  {
    Console.WriteLine("Blog Title: " + entry.Title.Text);
  }
}

سجِّل عنوان URL المستخدَم من خلال طريقة getFeed. هذا هو عنوان URL التلقائي للخلاصة الوصفية، ويعرض قائمة بالمدوّنات للمستخدم الذي تمّت المصادقة عليه حاليًا. للوصول إلى خلاصة لمستخدم مختلف، يمكنك وضع معرّف المستخدم بدلاً من default في عنوان URL للخلاصة الوصفية. معرّف المستخدم هو سلسلة الأرقام التي تظهر في نهاية عنوان URL الخاص بملفه الشخصي.

إنشاء المشاركات

تتيح لك Blogger Data API إنشاء إدخالات مدوّنة جديدة ونشرها، بالإضافة إلى إنشاء مسودات للإدخالات.

تفترض جميع النماذج التالية أنّ لديك عنصر Service تمّت مصادقته.

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

نشر مشاركة في مدوّنة

يمكنك استخدام مكتبة عملاء ‎ .NET لنشر إدخالات مدوّنة جديدة.

أولاً، أنشئ عنصرًا من النوع AtomEntry لتمثيل مشاركة المدونة. يمكنك بعد ذلك ضبط العنوان والمحتوى والسمات الأخرى لمشاركة المدونة. أخيرًا، استخدِم العنصر Service لإدراج المشاركة. في ما يلي مثال على كيفية نشر مشاركة جديدة في مدوّنة:

AtomEntry newPost = new AtomEntry();
newPost.Title.Text = "Marriage!";
newPost.Content = new AtomContent();
newPost.Content.Content = "<div xmlns='http://www.w3.org/1999/xhtml'>" +
  "<p>Mr. Darcy has <em>proposed marriage</em> to me!</p>" +
  "<p>He is the last man on earth I would ever desire to marry.</p>" +
  "<p>Whatever shall I do?</p>" +
  "</div>";
newPost.Content.Type = "xhtml";

Uri blogFeedUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
AtomEntry createdEntry = service.Insert(blogFeedUri, newPost);

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

إذا تعذّر إكمال طلبك لسبب ما، قد يعرض Blogger رمز حالة مختلفًا. للحصول على معلومات عن رموز الحالة، يُرجى الاطّلاع على مستند مرجعي لبروتوكول Google Data API.

إنشاء مسودة لمشاركة مدونة

يتم إنشاء مسودّات المشاركات بالطريقة نفسها التي يتم بها إنشاء المشاركات العلنية، ولكن عليك ضبطسمة draft لكائن AtomEntry. يمكن إنشاء تدوينة المذكورة أعلاه كمسودة من خلال إضافة السطر المميّز:

AtomEntry newPost = new AtomEntry();
newPost.Title.Text = "Marriage!";
newPost.Content = new AtomContent();
newPost.Content.Content = "<div xmlns='http://www.w3.org/1999/xhtml'>" +
    "<p>Mr. Darcy has <em>proposed marriage</em> to me!</p>" +
    "<p>He is the last man on earth I would ever desire to marry.</p>" +
    "<p>Whatever shall I do?</p>" +
    "</div>";
newPost.Content.Type = "xhtml";
newPost.IsDraft = true;

Uri blogFeedUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
AtomEntry createdEntry = service.Insert(blogFeedUri, newPost);

يمكنك تحويل مسودة حالية لمشاركة مدونة إلى مشاركة منشورة من خلال استرداد مسودة المشاركة وضبط سمة المسودة على false (خطأ)، ثم تعديل المشاركة. سنتناول استرداد المشاركات وتعديلها في القسمَين التاليَين.

استرداد المشاركات

توضّح الأقسام التالية كيفية استرداد قائمة بمشاركات المدونة، باستخدام ومعلمات طلب البحث بدونها.

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

استرداد جميع مشاركات المدونة

لاسترداد مشاركات المستخدم، استخدِم طريقة getFeed نفسها المستخدَمة لاسترداد خلاصة الميتا للمدوّنات، ولكن أرسِل هذه المرة عنوان URL لخلاصة المشاركات في المدوّنة:

query.Uri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
feed = service.Query(query);
Console.WriteLine(feed.Title.Text);
foreach (AtomEntry entry in feed.Entries)
{
  Console.WriteLine("Entry Title: " + entry.Title.Text);
}

استرداد المشاركات باستخدام مَعلمات طلب البحث

تتيح لك Blogger Data API طلب مجموعة من الإدخالات التي تتطابق مع معايير محدّدة، مثل طلب منشورات مدونة تم نشرها أو تعديلها في نطاق تاريخ معيّن. لإجراء ذلك، يمكنك إنشاء عنصر FeedQuery ونقله إلى الطريقة Service.Query().

على سبيل المثال، لإرسال طلب بحث عن النطاق الزمني، اضبط العنصرَين MinPublication وMaxPublication من العنصر FeedQuery. يطبع المقتطف التالي من الرمز البرمجي عنوان كل مشاركة مدوّنة منشورة بين وقت البدء والوقت المُحدَّدَين للانتهاء:

FeedQuery query = new FeedQuery();
query.Uri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
query.MinPublication = new DateTime(2006, 1, 1);
query.MaxPublication = new DateTime(2007, 4, 12);
AtomFeed feed = service.Query(query);
foreach (AtomEntry entry in feed.Entries)
{
  Console.WriteLine("  Entry Title: " + entry.Title.Text);
}

يُرجى ملاحظة أنّه تمّ إنشاء عنصر FeedQuery باستخدام عنوان URL نفسه لخلاصة المشاركات المستخدَم لاسترداد المشاركات.

تتيح Blogger Data API مَعلمات طلب البحث التالية:

alt
نوع الخلاصة التي سيتم عرضها، مثل atom (الإعداد التلقائي) أو rss
/category
حدِّد الفئات (المعروفة أيضًا باسم التصنيفات) لفلترة نتائج الخلاصة. على سبيل المثال، يعرض http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie الإدخالات التي تحتوي على الملصقين Fritz وLaurie.
max-results
الحد الأقصى لعدد الإدخالات التي سيتم عرضها
orderby
الترتيب الذي يتم به عرض الإدخالات، مثل lastmodified (الترتيب التلقائي) أو starttime أو updated
published-min وpublished-max
الحدّ الأدنى والأعلى لتاريخ نشر الإدخال
start-index
فهرس يستند إلى 1 للنتيجة الأولى التي سيتم استرجاعها (لصفحة البيانات).
updated-min وupdated-max
الحدّ الأقصى لتواريخ تعديل الإدخالات يتم تجاهل مَعلمات طلب البحث هذه ما لم يتم ضبط المَعلمة orderby على updated.

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

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

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

static AtomEntry EditEntry(AtomEntry toEdit)
{
  // Edit the entry by changing the Title and calling Update().
  if (toEdit != null)
  {
    toEdit.Title.Text = "Marriage Woes!";
    toEdit = toEdit.Update();
  }
  return toEdit;
}

يعرض الرمز أعلاه AtomEntry يحتوي على المحتوى بالكامل للمشاركة التي تم تعديلها مؤخرًا. لتعديل أيّ سمات أخرى، ما عليك سوى ضبطها في كائن AtomEntry قبل استدعاء Update().

ملاحظة: لا يمكن حاليًا تعديل بيانات المؤلف المرتبطة بالمواد المتوفّرة في المشاركات.

حذف المشاركات

لحذف مشاركة، استخدِم الطريقة Delete مع عنصر AtomEntry حالي، على النحو التالي:

static void DeleteEntry(AtomEntry toDelete)
{
  // Delete the edited entry
  if (toDelete != null)
  {
    toDelete.Delete();
  }
}

التعليقات

تتيح Blogger Data API إنشاء التعليقات واستردادها وحذفها. لا يمكن تعديل التعليقات (ولا تتوفّر هذه الميزة في واجهة الويب).

إنشاء التعليقات

لنشر تعليق، أنشئ عنصرًا من النوع AtomEntry وأدرِجه على النحو التالي:

AtomEntry comment;
comment = new AtomEntry();
comment.Title.Text = "This is my first comment";
comment.Content.Content = "This is my first comment";
Uri commentPostUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/" + entryId + "/comments/default");
postedComment = service.Insert(commentPostUri, comment);

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

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

استرداد التعليقات

يمكنك استرداد تعليقات مشاركة معيّنة من عنوان URL لخلاصة التعليقات الخاصة بالمشاركة:

static void ListEntryComments(Service service, Uri commentUri)
{
  if (commentUri != null)
  {
    // Retrieve all comments on a blog entry
    FeedQuery query = new FeedQuery();
    query.Uri = commentUri;
    AtomFeed feed = service.Query(query);
    foreach (AtomEntry entry in feed.Entries)
    {
      Console.WriteLine("  Comment Title: " + entry.Title.Text);
    }
  }
}

يمكنك أيضًا الحصول على التعليقات من جميع المشاركات باستخدام عنوان URL لخلاصة التعليقات في المدونة:

http://www.blogger.com/feeds/blogID/comments/default

حذف التعليقات

لحذف تعليق، يمكنك استدعاء الطريقة Delete() على عنصر تعليق AtomEntry حالي على النحو التالي:

static void DeleteComment(AtomEntry commentEntry)
{
  if (commentEntry != null)
  {
    // Delete the comment.
    commentEntry.Delete();
  }
}

الرجوع إلى الأعلى