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

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

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

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

المحتويات

الجمهور

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

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

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

البدء

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

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

إنشاء حساب Blogger

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بعد ذلك، يمكنك إنشاء عنوان URL لـ AuthSubRequest لتطبيقك، وإجراء طلب مكتبة مكتبة .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 رمزًا مميزًا للمصادقة بعنوان URL هذا، باعتباره قيمة معلمة طلب البحث token. لذلك، يمكن الوصول إلى الرمز المميّز كمتغيّر في كائن Request.QueryString في صفحة ASP. تتم إعادة توجيه المستخدم إلى عنوان URL يبدو كما يلي:

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

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

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

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

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

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

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

استخدام مصادقة ClientLogin إذا كان البرنامج عميلاً مستقلاً لمستخدم واحد "installed;quot;; (مثل تطبيق سطح مكتب). اضبط بيانات اعتماد عنصر الخدمة كما يلي:

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 خلاصة تسرد المدونات لمستخدم محدد، وتُعرف هذه الخلاصة باسم "metafeed.&quot.

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

تفترض جميع النماذج التالية أن لديك كائن 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 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);

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

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

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

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

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

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

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

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

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();
  }
}

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