مشاركة عبر

كيفية استخدام مكتبة عميل JavaScript لتطبيقات Azure Mobile

  • مقالة

نظرة عامة

يعلمك هذا الدليل تنفيذ سيناريوهات شائعة باستخدام أحدث JavaScript SDK لتطبيقات Azure Mobile. إذا كنت جديدا على Azure Mobile Apps، فأكمل أولا Azure Mobile Apps Quick Start لإنشاء خلفية وإنشاء جدول. في هذا الدليل، نركز على استخدام الواجهة الخلفية للأجهزة المحمولة في تطبيقات ويب HTML/JavaScript.

الأنظمة الأساسية المدعومة

نقتصر دعم المستعرض على الإصدارات الحالية والأخيرة من المستعرضات الرئيسية: Google Chrome وMicrosoft Edge وMicrosoft Internet Explorer وMozilla Firefox. نتوقع أن تعمل SDK مع أي مستعرض حديث نسبيا.

يتم توزيع الحزمة كوحدة JavaScript عامة، لذلك تدعم تنسيقات globals وAMD و CommonJS.

الإعداد والمتطلبات الأساسية

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

يمكن تثبيت Azure Mobile Apps JavaScript SDK عبر npm الأمر:

npm install azure-mobile-apps-client --save

يمكن أيضا استخدام المكتبة كوحدة ES2015، داخل بيئات CommonJS مثل Browserify وWebpack وك مكتبة AMD. على سبيل المثال:

// For ECMAScript 5.1 CommonJS
var WindowsAzure = require('azure-mobile-apps-client');
// For ES2015 modules
import * as WindowsAzure from 'azure-mobile-apps-client';

يمكنك أيضا استخدام إصدار تم إنشاؤه مسبقا من SDK عن طريق التنزيل مباشرة من CDN الخاص بنا:

<script src="https://zumo.blob.core.windows.net/sdk/azure-mobile-apps-client.min.js"></script>

إنشاء اتصال عميل

إنشاء اتصال عميل عن طريق إنشاء كائن WindowsAzure.MobileServiceClient . استبدل appUrl بعنوان URL لتطبيق الأجهزة المحمولة.

var client = WindowsAzure.MobileServiceClient(appUrl);

العمل باستخدام الجداول

للوصول إلى البيانات أو تحديثها، قم بإنشاء مرجع إلى الجدول الخلفي. استبدال tableName باسم الجدول الخاص بك

var table = client.getTable(tableName);

بمجرد أن يكون لديك مرجع جدول، يمكنك العمل بشكل أكبر مع الجدول الخاص بك:

كيفية: الاستعلام عن مرجع جدول

بمجرد أن يكون لديك مرجع جدول، يمكنك استخدامه للاستعلام عن البيانات على الخادم. يتم إجراء الاستعلامات بلغة "تشبه LINQ". لإرجاع جميع البيانات من الجدول، استخدم التعليمات البرمجية التالية:

/**
 * Process the results that are received by a call to table.read()
 *
 * @param {Object} results the results as a pseudo-array
 * @param {int} results.length the length of the results array
 * @param {Object} results[] the individual results
 */
function success(results) {
   var numItemsRead = results.length;

   for (var i = 0 ; i < results.length ; i++) {
       var row = results[i];
       // Each row is an object - the properties are the columns
   }
}

function failure(error) {
    throw new Error('Error loading data: ', error);
}

table
    .read()
    .then(success, failure);

يتم استدعاء دالة النجاح مع النتائج. لا تستخدم for (var i in results) في دالة النجاح لأن ذلك سيتكرر عبر المعلومات المضمنة في النتائج عند استخدام دالات الاستعلام الأخرى (مثل .includeTotalCount()).

لمزيد من المعلومات حول بناء جملة الاستعلام، راجع [وثائق عنصر الاستعلام].

تصفية البيانات على الخادم

يمكنك استخدام عبارة where في مرجع الجدول:

table
    .where({ userId: user.userId, complete: false })
    .read()
    .then(success, failure);

يمكنك أيضا استخدام دالة تقوم بتصفية العنصر. في هذه الحالة، this يتم تعيين المتغير إلى الكائن الحالي الذي تتم تصفيته. التعليمات البرمجية التالية مكافئة وظيفيا للمثال السابق:

function filterByUserId(currentUserId) {
    return this.userId === currentUserId && this.complete === false;
}

table
    .where(filterByUserId, user.userId)
    .read()
    .then(success, failure);

الترحيل عبر البيانات

استخدام الأسلوبين take() و skip() . على سبيل المثال، إذا كنت ترغب في تقسيم الجدول إلى سجلات من 100 صف:

var totalCount = 0, pages = 0;

// Step 1 - get the total number of records
table.includeTotalCount().take(0).read(function (results) {
    totalCount = results.totalCount;
    pages = Math.floor(totalCount/100) + 1;
    loadPage(0);
}, failure);

function loadPage(pageNum) {
    let skip = pageNum * 100;
    table.skip(skip).take(100).read(function (results) {
        for (var i = 0 ; i < results.length ; i++) {
            var row = results[i];
            // Process each row
        }
    }
}

.includeTotalCount() يتم استخدام الأسلوب لإضافة حقل totalCount إلى كائن النتائج. يتم تعبئة حقل totalCount بإجمالي عدد السجلات التي سيتم إرجاعها إذا لم يتم استخدام ترحيل الصفحات.

يمكنك بعد ذلك استخدام متغير الصفحات وبعض أزرار واجهة المستخدم لتوفير قائمة صفحات؛ استخدم loadPage() لتحميل السجلات الجديدة لكل صفحة. تنفيذ التخزين المؤقت للوصول السريع إلى السجلات التي تم تحميلها بالفعل.

كيفية: إرجاع البيانات التي تم فرزها

.orderBy() استخدم أساليب الاستعلام أو .orderByDescending() :

table
    .orderBy('name')
    .read()
    .then(success, failure);

لمزيد من المعلومات حول عنصر الاستعلام، راجع [وثائق عنصر الاستعلام].

كيفية: إدراج بيانات

إنشاء كائن JavaScript بالتاريخ المناسب واستدعاء table.insert() بشكل غير متزامن:

var newItem = {
    name: 'My Name',
    signupDate: new Date()
};

table
    .insert(newItem)
    .done(function (insertedItem) {
        var id = insertedItem.id;
    }, failure);

عند الإدراج الناجح، يتم إرجاع العنصر المدرج مع الحقول الإضافية المطلوبة لعمليات المزامنة. قم بتحديث ذاكرة التخزين المؤقت الخاصة بك بهذه المعلومات للتحديثات اللاحقة.

تدعم Azure Mobile Apps Node.js Server SDK المخطط الديناميكي لأغراض التطوير. يسمح لك المخطط الديناميكي بإضافة أعمدة إلى الجدول عن طريق تحديدها في عملية إدراج أو تحديث. نوصي بإيقاف تشغيل المخطط الديناميكي قبل نقل التطبيق الخاص بك إلى الإنتاج.

كيفية: تعديل البيانات

على .insert() غرار الأسلوب ، يجب إنشاء كائن تحديث ثم استدعاء .update(). يجب أن يحتوي كائن التحديث على معرف السجل المراد تحديثه - يتم الحصول على المعرف عند قراءة السجل أو عند استدعاء .insert().

var updateItem = {
    id: '7163bc7a-70b2-4dde-98e9-8818969611bd',
    name: 'My New Name'
};

table
    .update(updateItem)
    .done(function (updatedItem) {
        // You can now update your cached copy
    }, failure);

كيفية: حذف البيانات

لحذف سجل، قم باستدعاء .del() الأسلوب . مرر المعرف في مرجع كائن:

table
    .del({ id: '7163bc7a-70b2-4dde-98e9-8818969611bd' })
    .done(function () {
        // Record is now deleted - update your cache
    }, failure);

كيفية: مصادقة المستخدمين

تدعم Azure App Service مصادقة مستخدمي التطبيق وتخويلهم باستخدام موفري هوية خارجيين مختلفين: Facebook وGoogle وحساب Microsoft وTwitter. يمكنك تعيين أذونات على الجداول لتقييد الوصول لعمليات معينة للمستخدمين المصادق عليهم فقط. يمكنك أيضا استخدام هوية المستخدمين المصادق عليهم لتنفيذ قواعد التخويل في البرامج النصية للخادم. لمزيد من المعلومات، راجع البرنامج التعليمي بدء استخدام المصادقة .

يتم دعم تدفقي مصادقة: تدفق خادم وتدفق عميل. يوفر تدفق الخادم أبسط تجربة مصادقة، لأنه يعتمد على واجهة مصادقة الويب الخاصة بالموفر. يسمح تدفق العميل بتكامل أعمق مع الإمكانات الخاصة بالجهاز مثل تسجيل الدخول الأحادي لأنه يعتمد على SDKs الخاصة بالموفر.

كيفية: المصادقة مع موفر (Server Flow)

لجعل تطبيقات الأجهزة المحمولة تدير عملية المصادقة في تطبيقك، يجب عليك تسجيل تطبيقك مع موفر الهوية الخاص بك. ثم في Azure App Service، تحتاج إلى تكوين معرف التطبيق والبيانات السرية التي يوفرها موفر الخدمة. لمزيد من المعلومات، راجع البرنامج التعليمي إضافة مصادقة إلى تطبيقك.

بمجرد تسجيل موفر الهوية الخاص بك، اتصل بالأسلوب .login() باسم الموفر الخاص بك. على سبيل المثال، لتسجيل الدخول باستخدام Facebook، استخدم التعليمات البرمجية التالية:

client.login("facebook").done(function (results) {
     alert("You are now signed in as: " + results.userId);
}, function (err) {
     alert("Error: " + err);
});

القيم الصالحة للموفر هي "aad" و"facebook" و"google" و"microsoftaccount" و"twitter".

ملاحظة

لا تعمل مصادقة Google حاليا عبر Server Flow. للمصادقة مع Google، يجب عليك استخدام أسلوب تدفق العميل.

في هذه الحالة، تدير Azure App Service تدفق مصادقة OAuth 2.0. يعرض صفحة تسجيل الدخول للموفر المحدد وينشئ رمز مصادقة App Service المميز بعد تسجيل الدخول الناجح مع موفر الهوية. ترجع دالة تسجيل الدخول، عند اكتمالها، كائن JSON الذي يعرض كل من معرف المستخدم ورمز مصادقة App Service المميز في حقلي userId و authenticationToken، على التوالي. يمكن تخزين هذا الرمز المميز مؤقتا وإعادة استخدامه حتى تنتهي صلاحيته.

كيفية: المصادقة مع موفر (تدفق العميل)

يمكن لتطبيقك أيضا الاتصال بموفر الهوية بشكل مستقل ثم توفير الرمز المميز الذي تم إرجاعه إلى App Service للمصادقة. يمكنك تدفق العميل هذا من توفير تجربة تسجيل دخول واحدة للمستخدمين أو استرداد بيانات مستخدم إضافية من موفر الهوية.

مثال أساسي للمصادقة الاجتماعية

يستخدم هذا المثال SDK لعميل Facebook للمصادقة:

client.login(
     "facebook",
     {"access_token": token})
.done(function (results) {
     alert("You are now signed in as: " + results.userId);
}, function (err) {
     alert("Error: " + err);
});

يفترض هذا المثال أن الرمز المميز الذي يوفره موفر SDK المعني مخزن في متغير الرمز المميز.

كيفية: الحصول على معلومات حول المستخدم المصادق عليه

يمكن استرداد معلومات المصادقة من /.auth/me نقطة النهاية باستخدام استدعاء HTTP مع أي مكتبة AJAX. تأكد من X-ZUMO-AUTH تعيين العنوان إلى رمز المصادقة المميز. يتم تخزين الرمز المميز للمصادقة في client.currentUser.mobileServiceAuthenticationToken. على سبيل المثال، لاستخدام واجهة برمجة تطبيقات الإحضار:

var url = client.applicationUrl + '/.auth/me';
var headers = new Headers();
headers.append('X-ZUMO-AUTH', client.currentUser.mobileServiceAuthenticationToken);
fetch(url, { headers: headers })
    .then(function (data) {
        return data.json()
    }).then(function (user) {
        // The user object contains the claims for the authenticated user
    });

يتوفر الإحضار كحزمة npm أو لتنزيل المستعرض من CDNJS. يمكنك أيضا استخدام jQuery أو واجهة برمجة تطبيقات AJAX أخرى لجلب المعلومات. يتم تلقي البيانات ككائن JSON.

كيفية: تكوين خدمة تطبيقات الأجهزة المحمولة لعناوين URL لإعادة التوجيه الخارجية.

تستخدم عدة أنواع من تطبيقات JavaScript إمكانية الحفظ مع التحديث للتعامل مع تدفقات واجهة مستخدم OAuth. وتشمل قدراته ما يلي:

  • تشغيل الخدمة محليا
  • استخدام Live Reload مع Ionic Framework
  • إعادة التوجيه إلى App Service للمصادقة.

يمكن أن يتسبب التشغيل محليا في حدوث مشاكل لأنه، بشكل افتراضي، يتم تكوين مصادقة App Service فقط للسماح بالوصول من الخلفية لتطبيق الأجهزة المحمولة. استخدم الخطوات التالية لتغيير إعدادات App Service لتمكين المصادقة عند تشغيل الخادم محليا:

  1. سجّل الدخول إلى مدخل Azure

  2. انتقل إلى الواجهة الخلفية لتطبيق الأجهزة المحمولة.

  3. حدد Resource explorer في قائمة DEVELOPMENT TOOLS .

  4. انقر فوق Go لفتح مستكشف الموارد للواجهة الخلفية لتطبيق الأجهزة المحمولة في علامة تبويب أو نافذة جديدة.

  5. قم بتوسيع عقدة config>authsettings لتطبيقك.

  6. انقر فوق الزر تحرير لتمكين تحرير المورد.

  7. ابحث عن عنصر allowedExternalRedirectUrls ، والذي يجب أن يكون خاليا. أضف عناوين URL في صفيف:

      "allowedExternalRedirectUrls": [
      "https://localhost:3000",
      "https://localhost:3000"
  ],

    استبدل عناوين URL في الصفيف بعناوين URL للخدمة الخاصة بك، والتي في هذا المثال مخصصة https://localhost:3000 لخدمة عينة Node.js المحلية. يمكنك أيضا استخدام https://localhost:4400 لخدمة "النسخ المموج" أو بعض عناوين URL الأخرى، اعتمادا على كيفية تكوين تطبيقك.

  8. في أعلى الصفحة، انقر فوق قراءة/كتابة، ثم انقر فوق PUT لحفظ التحديثات.

تحتاج أيضا إلى إضافة نفس عناوين URL للتراجع إلى إعدادات قائمة السماح CORS:

  1. انتقل مرة أخرى إلى مدخل Microsoft Azure.
  2. انتقل إلى الواجهة الخلفية لتطبيق الأجهزة المحمولة.
  3. انقر فوق CORS في قائمة واجهة برمجة التطبيقات .
  4. أدخل كل عنوان URL في مربع النص "Allowed Origins" الفارغ. يتم إنشاء مربع نص جديد.
  5. انقر فوق حفظ

بعد تحديثات الواجهة الخلفية، ستتمكن من استخدام عناوين URL الجديدة للتراجع في تطبيقك.