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

ملاحظات مهمّة: سنوقف نهائيًا الإصدار 2.0 من Google Data API في 30 أيلول (سبتمبر) 2024. لضمان استمرار الوظائف، عليك تحديث تطبيقاتك التي تعتمد على الإصدار 2.0 من Google. Data API على أحدث إصدار لواجهة برمجة التطبيقات للحصول على أحدث إصدار، استخدِم الروابط في شريط القوائم العلوي على يمين الصفحة. ملاحظة: على الرغم من أنّه سيستمر السماح ببعض طلبات GET (مثل إدراج المشاركات) كعناوين URL لخلاصة ، هناك اختلافات طفيفة في سلوكها. للحصول على معلومات مفصّلة، يُرجى الرجوع إلى مستندات مساعدة Blogger.

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

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

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

يقوم العميل النموذجي بتنفيذ عدة عمليات على المدونة المقدمة توضيح استخدام واجهة برمجة تطبيقات 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 لـ 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 لـ AuthSubRequest عنوان URL. يضيف نظام AuthSub رمزًا مميزًا للمصادقة إلى عنوان URL هذا، حيث قيمة معلَمة طلب البحث 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 إرسال ملف header Authorization (الذي يحتوي على رمز مميّز للجلسة) تلقائيًا مع كل طلب، عليك تنفيذ ما يلي:

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 خلاصة تسرد المدونات الإلكترونية التي user; تُعرف هذه الخلاصة باسم "الخلاصة".

يستخدم نموذج الرمز البرمجي التالي عنصر 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 استخدام معلَمات طلب البحث التالية:

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

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

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

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

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