كيفية استخدام مكتبة عميل Apache Cordova لتطبيقات Azure للأجهزة المحمولة

مقالة
06/25/2019

نظرة عامة

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

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

تدعم حزمة SDK هذه الإصدار من Apache Cordova v6.0.0 والإصدارات الأحدث على أجهزة iOS و Android و Windows. دعم المنصة هو كما يلي:

الروبوت API 19-24 (كيت كات من خلال نوجا).
إصدارات iOS 8.0 والإصدارات الأحدث.
Windows Phone 8.1.
النظام الأساسي العام لـ Windows.

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

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

cordova plugin add cordova-plugin-ms-azure-mobile-apps

لمزيد من المعلومات حول إنشاء أول تطبيق Apache Cordova ، راجع وثائقهم.

إعداد تطبيق ionic v2

لتكوين مشروع Ionic v2 بشكل صحيح ، قم أولا بإنشاء تطبيق أساسي وإضافة المكون الإضافي Cordova:

ionic start projectName --v2
cd projectName
ionic plugin add cordova-plugin-ms-azure-mobile-apps

إضافة الأسطر التالية لإنشاء app.component.ts كائن العميل:

declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");

يمكنك الآن إنشاء المشروع وتشغيله في المستعرض:

ionic platform add browser
ionic run browser

يدعم المكون الإضافي Azure Mobile Apps Cordova كلا من تطبيقات Ionic v1 و v2. تتطلب تطبيقات الإصدار 2 الأيونية فقط الإعلان الإضافي للكائن WindowsAzure .

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

إنشاء اتصال عميل عن طريق إنشاء 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);

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

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

قم بإنشاء كائن جافا سكريبت بالتاريخ المناسب واتصل table.insert() بشكل غير متزامن:

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

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

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

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

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

على غرار الطريقة .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 Account وTwitter. يمكنك تعيين أذونات على الجداول لتقييد الوصول لعمليات معينة للمستخدمين المصادق عليهم فقط. يمكنك أيضا استخدام هوية المستخدمين المصادق عليهم لتنفيذ قواعد التخويل في البرامج النصية للخادم. لمزيد من المعلومات، راجع البرنامج التعليمي لبدء استخدام المصادقة .

عند استخدام المصادقة في تطبيق Apache Cordova ، يجب أن تتوفر مكونات Cordova الإضافية التالية:

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

كيفية القيام بما يلي: المصادقة باستخدام موفر (Flow الخادم)

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

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

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 حاليا عبر Flow الخادم. للمصادقة باستخدام Google، يجب عليك استخدام طريقة تدفق العميل.

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

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

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

يستخدم هذا المثال حزمة SDK الخاصة بعميل فيسبوك للمصادقة:

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 الخارجية لإعادة التوجيه.

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

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

اتبع هذه الإرشادات لإضافة إعداداتك المحلية إلى التكوين:

سجّل الدخول إلى مدخل Azure
حدد جميع الموارد أو خدمات التطبيق ، ثم انقر على اسم تطبيق الجوال.
انقر على الأدوات
انقر على مستكشف الموارد في القائمة OBSERV، ثم انقر على انتقال. يتم فتح نافذة أو علامة تبويب جديدة.
قم بتوسيع عقد التهيئة و authsettings لموقعك في التنقل الأيمن.
انقر فوق Edit
ابحث عن عنصر "allowedExternalRedirectUrls". قد يتم تعيينه إلى فارغ أو مجموعة من القيم. تغيير القيمة إلى القيمة التالية:
```
  "allowedExternalRedirectUrls": [
      "https://localhost:3000",
      "https://localhost:3000"
  ],
```
استبدل عناوين URL بعناوين URL الخاصة بخدمتك. تتضمن https://localhost:3000 الأمثلة (لخدمة عينة Node.js) أو https://localhost:4400 (لخدمة Ripple). ومع ذلك ، فإن عناوين URL هذه هي أمثلة - قد يكون موقفك ، بما في ذلك الخدمات المذكورة في الأمثلة ، مختلفا.
انقر فوق الزر قراءة/كتابة في الزاوية العلوية اليسرى من الشاشة.
انقر فوق الزر PUT الأخضر.

يتم حفظ الإعدادات في هذه المرحلة. لا تغلق نافذة المتصفح حتى تنتهي الإعدادات من الحفظ. أضف أيضا عناوين URL الاسترجاعية هذه إلى إعدادات CORS لخدمة التطبيق:

سجّل الدخول إلى مدخل Azure
حدد جميع الموارد أو خدمات التطبيق ، ثم انقر على اسم تطبيق الجوال.
تفتح شفرة الإعدادات تلقائيا. إذا لم يحدث ذلك، فانقر على الكل الإعدادات.
انقر على CORS ضمن قائمة واجهة برمجة التطبيقات.
أدخل عنوان URL الذي ترغب في إضافته في المربع المتوفر واضغط على مفتاح الإدخال Enter.
أدخل عناوين URL إضافية حسب الحاجة.
انقر فوق حفظ لحفظ الإعدادات.

يستغرق الأمر ما يقرب من 10-15 ثانية حتى تصبح الإعدادات الجديدة سارية المفعول.

كيفية: التسجيل للحصول على إشعارات الدفع

قم بتثبيت الهاتف المكون الإضافي للتعامل مع إشعارات الدفع. يمكن إضافة هذا المكون الإضافي بسهولة باستخدام الأمر الموجود cordova plugin add في سطر الأوامر ، أو عبر مثبت المكون الإضافي Git داخل Visual Studio. يقوم الرمز التالي في تطبيق Apache Cordova بتسجيل جهازك للحصول على إشعارات الدفع:

var pushOptions = {
    android: {
        senderId: '<from-gcm-console>'
    },
    ios: {
        alert: true,
        badge: true,
        sound: true
    },
    windows: {
    }
};
pushHandler = PushNotification.init(pushOptions);

pushHandler.on('registration', function (data) {
    registrationId = data.registrationId;
    // For cross-platform, you can use the device plugin to determine the device
    // Best is to use device.platform
    var name = 'gcm'; // For android - default
    if (device.platform.toLowerCase() === 'ios')
        name = 'apns';
    if (device.platform.toLowerCase().substring(0, 3) === 'win')
        name = 'wns';
    client.push.register(name, registrationId);
});

pushHandler.on('notification', function (data) {
    // data is an object and is whatever is sent by the PNS - check the format
    // for your particular PNS
});

pushHandler.on('error', function (error) {
    // Handle errors
});

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

مزيد من المعلومات

يمكنك العثور على تفاصيل مفصلة لواجهة برمجة التطبيقات في وثائق واجهة برمجة التطبيقات الخاصة بنا.

مشاركة عبر

كيفية استخدام مكتبة عميل Apache Cordova لتطبيقات Azure للأجهزة المحمولة

نظرة عامة

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

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

إعداد تطبيق ionic v2

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

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

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

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

الترحيل من خلال البيانات

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

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

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

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

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

كيفية القيام بما يلي: المصادقة باستخدام موفر (Flow الخادم)

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

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

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

كيفية: التسجيل للحصول على إشعارات الدفع

مزيد من المعلومات

الموارد الإضافية

مشاركة عبر

كيفية استخدام مكتبة عميل Apache Cordova لتطبيقات Azure للأجهزة المحمولة

نظرة عامة

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

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

إعداد تطبيق ionic v2

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

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

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

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

الترحيل من خلال البيانات

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

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

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

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

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

كيفية القيام بما يلي: المصادقة باستخدام موفر (Flow الخادم)

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

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

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

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

كيفية: التسجيل للحصول على إشعارات الدفع

مزيد من المعلومات

الموارد الإضافية