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

تتيح Blogger Data API لتطبيقات العميل عرض محتوى 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 المتمرّسين، قد تسأل نفسك: "ماذا عن سياسة ملفّات js المنشأ؟" تسمح مكتبة برامج 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 Maps API. في ما يلي أرقام الإصدارات المحتملة ومعانيها:

"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() هو الدالة. في حال حدث خطأ في الإعداد، تتلقّى الدالة عنصر خطأ عاديًا، ويمكنك تنفيذ أي إجراء تريده مع هذا العنصر.

يظل الرمز المميّز صالحًا إلى أن تبطله من خلال استدعاء 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 Client Library.

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