دليل المطوّر: 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 والإصدارات الأحدث، الإصدار 6.0 من Internet Explorer والإصدارات الأحدث.

وتتعامل مكتبة برامج 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. إليك الخيارات الممكنة أرقام الإصدارات ومعناها:

"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 بشكل عام، يمكنك الاطلاع على مصادقة ذات الصلة.

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

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

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

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

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

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

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

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