دليل المطوّر: JavaScript

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

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

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

المحتويات

  1. الجمهور
  2. بنود الاستخدام
  3. لمحة عن البيئات المتوافقة
  4. البدء
    1. إنشاء حساب على Blogger
    2. الحصول على المكتبة
  5. المصادقة على خدمة Blogger
    1. مصادقة الخادم الوكيل AuthSub

الجمهور

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

للحصول على معلومات مرجعية حول Blogger Data API، راجِع الدليل المرجعي للبروتوكولات. يفترض هذا المستند أنّك تفهم الأفكار العامة وراء بروتوكول Google Data APIs ونموذج البيانات وتدفّق التحكّم المستخدَمين في مكتبة برامج JavaScript. كما يفترض أيضًا أنك تعرف كيفية البرمجة باستخدام JavaScript.

للحصول على معلومات مرجعية حول الفئات والطرق التي تقدّمها مكتبة العملاء، راجِع مرجع واجهة برمجة التطبيقات لمكتبة برامج JavaScript.

تم تصميم هذا المستند لتتم قراءته بالترتيب؛ يعتمد كل مثال على الأمثلة السابقة.

بنود الاستخدام

أنت توافق على الالتزام ببنود استخدام مكتبة عملاء JavaScript من Google عند استخدام مكتبة برامج JavaScript.

لمحة عن البيئات المتوافقة

لا نتيح حاليًا سوى تطبيقات عميل JavaScript التي يتم تشغيلها في صفحة ويب في المتصفّح. المتصفحات المعتمدة حاليًا هي Firefox 1.5 والإصدارات الأحدث، وInternet Explorer 6.0 والإصدارات الأعلى.

تتعامل مكتبة برامج JavaScript مع جميع الاتصالات مع خادم الخدمة. إذا كنت من المطوّرين المتمرّسين في JavaScript، قد تخطر في بالك "ولكن ماذا عن سياسة المصدر نفسها؟" تسمح مكتبة برامج JavaScript للعميل بإرسال طلبات البيانات من Google Data API من أي نطاق مع الحفاظ على التوافق مع نموذج أمان المتصفّح.

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

قبل أن تتمكن من كتابة تطبيق عميل بلغة JavaScript، عليك إجراء عملية الإعداد للحصول على المكتبة.

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

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

الحصول على المكتبة

قبل أن يتمكن العميل من استخدام مكتبة البرامج، يجب أن يطلب العميل رمز مكتبة البرامج من الخادم.

ابدأ باستخدام علامة <script> في القسم <head> من مستند HTML لجلب برنامج تحميل Google AJAX API:

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

للحصول على مكتبة برامج Google Data API بعد جلب برنامج التحميل، استخدِم السطر التالي في رمز إعداد JavaScript، والذي يجب استدعاؤه من قسم <head> في مستند HTML (أو من ملف JavaScript تم تضمينه باستخدام علامة <script> في قسم <head> من مستند HTML):

google.load("gdata", "1.x");

المعلمة الثانية لـ google.load() هي رقم الإصدار المطلوب من مكتبة برامج JavaScript.تم تصميم نظام ترقيم الإصدارات لدينا على غرار المخطط الذي تستخدمه واجهة برمجة تطبيقات خرائط Google. وإليك أرقام الإصدارات المحتملة ومعنى كل منها:

"1"
النسخة الثانية إلى الأخيرة من الإصدار الرئيسي 1.
"1.x"
أحدث نسخة من الإصدار الرئيسي 1.
"1.s"
أحدث نسخة ثابتة من الإصدار الرئيسي 1. سنعلن أحيانًا عن أنّ إصدار معيّن من مكتبة العملاء "ثابت"، استنادًا إلى الملاحظات التي نتلقّاها من المطوّرين. ومع ذلك، قد لا يتضمّن هذا الإصدار أحدث الميزات.
"1.0" أو "1.1 أو غير ذلك
نسخة معيّنة من المكتبة، تتضمّن رقم مراجعة رئيسي وثانوي محدّد

بعد الاتصال بالرقم google.load()، يجب إعلام برنامج التحميل بالانتظار حتى ينتهي تحميل الصفحة، ثم الاتصال بالرمز التالي:

google.setOnLoadCallback(getMyBlogFeed);

حيث getMyBlogFeed() هي دالة سنحددها في قسم لاحق من هذا المستند. يمكنك استخدام هذه الطريقة بدلاً من إرفاق معالج onload بعنصر <body>.

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

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

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

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

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

إليك نظرة عامة مختصرة على ما يحدث أثناء عملية المصادقة في برنامج JavaScript مستند إلى الويب:

  1. يطلب تطبيق العميل الطريقة google.accounts.user.login() التي تقدّمها مكتبة البرامج، ويمررها قيمة "نطاق" تشير إلى خدمة Google التي يجب استخدامها. أما بالنسبة إلى Blogger، فيكون النطاق هو "http://www.blogger.com/feeds/".
  2. ترسل مكتبة البرامج المتصفّح إلى صفحة "طلب الوصول" من Google، حيث يمكن للمستخدم إدخال بيانات الاعتماد لتسجيل الدخول إلى الخدمة.
  3. إذا سجَّل المستخدم الدخول بنجاح، يُرسِل نظام AuthSub المتصفِّح مرة أخرى إلى عنوان URL لبرنامج الويب، وتمرير الرمز المميّز للمصادقة.
  4. تخزِّن مكتبة برامج JavaScript الرمز المميّز في ملفّ تعريف ارتباط وتعرض عنصر التحكّم في وظيفة تطبيق العميل التي تُعرف باسم google.accounts.user.login().
  5. عندما يستدعي تطبيق العميل في وقت لاحق طرق مكتبة العميل التي تتفاعل مع Blogger، ترفق مكتبة البرامج تلقائيًا الرمز المميّز في جميع الطلبات.

ملاحظة: لتتمكن مكتبة برامج JavaScript من إجراء طلبات Blogger تمت مصادقتها في متصفّح ويب، يجب أن تحتوي صفحتك على صورة تتم استضافتها على النطاق نفسه مثل صفحتك. يمكن أن تكون أي صورة، حتى صورة شفافة بوحدة بكسل واحدة، ولكن يجب أن تكون هناك صورة على الصفحة. إذا كنت تريد ألا تظهر الصورة على صفحتك، يمكنك استخدام السمة style للعلامة <img> لوضع الصورة خارج منطقة العرض. مثلاً: style="position:absolute; top: -1000px;"

إليك رمز تطبيق العميل الذي يعالج تسجيل الدخول. سنسمي الدالة setupMyService() من رمز آخر لاحقًا.

function logMeIn() {
  scope = "http://www.blogger.com/feeds/";
  var token = google.accounts.user.login(scope);
}

function setupMyService() {
  var myService =
    new google.gdata.blogger.BloggerService('exampleCo-exampleApp-1');
  logMeIn();
  return myService;
}

ملاحظة: ننصح بشدّة بتوفير زر تسجيل الدخول أو آلية إدخال أخرى للمستخدم كي تطلب من المستخدم بدء عملية تسجيل الدخول يدويًا. وبدلاً من ذلك، إذا طلبتَ google.accounts.user.login() مباشرةً بعد التحميل، بدون انتظار تفاعل المستخدِم، فإن أول ما يظهر للمستخدم عند وصوله إلى صفحتكَ هو صفحة تسجيل الدخول إلى Google. إذا قرر المستخدم عدم تسجيل الدخول، لن يوجِّهه Google إلى صفحتك مرة أخرى، لذلك من وجهة نظر المستخدم، حاول زيارة صفحتك ولكن تم إبعاده ولم يتم إعادته مطلقًا. قد يكون هذا السيناريو مربكًا ومحبطًا للمستخدمين. في نموذج الرمز البرمجي بهذا المستند، سنطلق على الرمز google.accounts.user.login() مباشرةً بعد التحميل لتبسيط المثال، لكننا لا ننصح بهذا الأسلوب مع تطبيقات العملاء الواقعية.

يُرجى العِلم أنّه لا حاجة إلى اتّخاذ أي إجراء باستخدام المتغيّر المسمى token، لأنّ مكتبة البرامج تتتبّع الرمز المميّز ولن تكون مضطرًا لإجراء ذلك.

ملاحظة: عند إنشاء كائن BloggerService جديد، تستدعي مكتبة البرامج طريقة تُسمّى google.gdata.client.init() للتحقّق من توافق المتصفّح الذي يشغّله العميل. إذا كان هناك خطأ، فستعرض مكتبة العملاء رسالة خطأ للمستخدم. إذا كنت تريد التعامل مع هذا النوع من الأخطاء بنفسك، يمكنك استدعاء google.gdata.client.init(handleInitError) بوضوح قبل إنشاء الخدمة، حيث تكون handleInitError() هي دالتك. إذا حدث خطأ init، فستتلقّى الدالة كائن "Error" قياسي؛ يمكنك أن تفعل أي شيء تريده مع هذا الكائن.

يظل الرمز المميّز صالحًا إلى أن يتم إبطاله من خلال طلب الرقم google.accounts.user.logout():

function logMeOut() {
  google.accounts.user.logout();
}

في حال عدم استدعاء logout()، سيظل ملف تعريف الارتباط الذي يخزِّن الرمز المميّز صالحًا لمدة عامين، ما لم يحذفه المستخدم. ويتم الاحتفاظ بملف تعريف الارتباط في جميع جلسات المتصفّح، حتى يتمكّن المستخدم من إغلاق المتصفّح ثم إعادة فتحه ثم العودة إلى البرنامج وسيظلّ مسجِّلاً الدخول.

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

هناك طريقتان أخريان AuthSub قد تجدهما مفيدين في سياقات مختلفة:

  • توضِّح لك google.accounts.user.checkLogin(scope) ما إذا كان المتصفّح يتضمّن حاليًا رمزًا مميّزًا للمصادقة للنطاق المحدّد.
  • توفّر google.accounts.user.getInfo() معلومات مفصّلة حول الرمز المميّز الحالي من أجل تصحيح الأخطاء المتعلّقة بالاستخدام.

للاطّلاع على تفاصيل حول استخدام JavaScript للتفاعل مع AuthSub، بما في ذلك معلومات عن إدارة الرموز المميّزة وعلى checkLogin() وgetInfo()، يمكنك الاطّلاع على المستند استخدام مصادقة AuthSub مع مكتبة عميل JavaScript.

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