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

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

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

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

المحتويات

الجمهور

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

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

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

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

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

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

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

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

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

البدء

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

إنشاء حساب Blogger

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

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

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

يمكنك البدء باستخدام علامة <script> في القسم <head> من مستند HTML لجلب برنامج واجهة برمجة تطبيقات Google AJAX:

<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. إليك أرقام الإصدار المحتملة ومعنى كلٍّ منها:

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

بعد الاتصال بالنشاط التجاري google.load()، يجب أن تطلب من القائم بالتحميل الانتظار حتى انتهاء تحميل الصفحة، ثم الاتصال بالرمز الخاص بك:

google.setOnLoadCallback(getMyBlogFeed);

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

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

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

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

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

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

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

  1. يستدعي تطبيق العميل طريقة google.accounts.user.login() التي توفّرها مكتبة العملاء، مع تمريره "scope"## قيمة تشير إلى خدمة Google التي يجب استخدامها. بالنسبة إلى Blogger، النطاق هو "http://www.blogger.com/feeds/".
  2. ترسل مكتبة العميل المتصفّح إلى صفحة Google's"Access"طلب&quot، حيث يمكن للمستخدم إدخال بيانات اعتماده لتسجيل الدخول إلى الخدمة.
  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، لأنّ مكتبة العميل تسجّل الرمز المميّز بحيث لا تحتاج إلى تنفيذ أي إجراء.

ملاحظة: عند إنشاء عنصر جديد في خدمة Blogger، تطلب مكتبة العميل طريقة باسم 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.

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