Azure Mobile Apps Cordova 插件完整使用指南

Question

本指南详细介绍了如何使用适用于 Azure Mobile Apps 的最新 Apache Cordova 插件来执行常见开发任务。如果您是 Azure Mobile Apps 的新手，建议先完成快速入门教程，以建立后端、创建数据表并下载预构建的 Apache Cordova 项目。本文将重点放在客户端 Apache Cordova 插件的使用上。

支持平台

该 SDK 支持 Apache Cordova v6.0.0 及以上版本，适用于 iOS、Android 和 Windows 设备。具体平台支持包括：

Android API 19-24（从 KitKat 到 Nougat）。
iOS 8.0 及以上版本。
Windows Phone 8.1。
通用 Windows 平台。

设置和前提条件

本指南假设您已使用数据表创建后端，并且数据表架构与教程中的类似。同时，假设您已将 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 应用，但只有 Ionic v2 应用需要额外声明 WindowsAzure 对象。

创建客户端连接

通过创建 WindowsAzure.MobileServiceClient 对象来建立客户端连接，其中 appUrl 需替换为移动应用的 URL：

var client = WindowsAzure.MobileServiceClient(appUrl);

使用数据表

要访问或更新数据，请创建指向后端数据表的引用，其中 tableName 替换为数据表名称：

var table = client.getTable(tableName);

获得数据表引用后，可以执行以下操作：查询数据、插入数据、修改数据和删除数据。

查询数据表

使用数据表引用查询服务器上的数据，查询语言类似于 LINQ。以下代码返回数据表中的所有数据：

function success(results) {
   var numItemsRead = results.length;
   for (var i = 0 ; i < results.length ; i++) {
       var row = results[i];
       // 每行是一个对象，属性为列
   }
}
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;
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];
            // 处理每一行
        }
    });
}

.includeTotalCount() 方法用于将 totalCount 字段添加到结果对象，该字段表示未使用分页时的总记录数。然后，可以使用页面变量和 UI 按钮加载各页数据，同时建议实现缓存以加速访问已加载记录。

返回排序数据

使用 .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 支持动态架构供开发使用，允许在插入或更新时添加字段，但建议在生产环境中关闭动态架构。

修改数据

类似插入操作，创建更新对象并调用 .update()，更新对象必须包含记录标识符：

var updateItem = {
    id: '7163bc7a-70b2-4dde-98e9-8818969611bd',
    name: 'My New Name'
};
table.update(updateItem).done(function (updatedItem) {
    // 更新缓存副本
}, failure);

删除数据

调用 .del() 方法并传递标识符对象以删除记录：

table.del({ id: '7163bc7a-70b2-4dde-98e9-8818969611bd' }).done(function () {
    // 记录已删除，更新缓存
}, failure);

用户验证

Azure App Service 支持使用外部身份提供者（如 Facebook、Google、Microsoft 帐户和 Twitter）进行用户验证和授权。可以配置数据表权限以限制特定操作仅限已验证用户，或在服务器脚本中使用已验证用户身份实施授权规则。在 Apache Cordova 应用中使用验证时，需安装以下 Cordova 插件：

cordova-plugin-device
cordova-plugin-inappbrowser

支持两种验证流程：服务器流程和客户端流程。服务器流程依赖提供者的 Web 验证界面，体验简单；客户端流程允许更深度的设备集成，如单点登录。

服务器流程验证

向身份提供者注册应用后，在 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 验证目前无法通过服务器流程工作，需使用客户端流程。登录成功后，函数返回 JSON 对象，包含 userId 和 authenticationToken 字段，令牌可缓存并重复使用直至过期。

客户端流程验证

应用可独立联系身份提供者，然后将返回的令牌提供给 App Service 进行验证。例如，使用 Facebook 客户端 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 提供并存储在变量中。

获取已验证用户信息

通过 HTTP 调用从 /.auth/me 端点获取验证信息，需设置 X-ZUMO-AUTH 标头为验证令牌（存储在 client.currentUser.mobileServiceAuthenticationToken 中）。例如，使用 Fetch API：

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) {
        // user 对象包含已验证用户的声明
    });

Fetch 可作为 npm 包或从 CDNJS 下载，也可以使用 jQuery 或其他 AJAX 库。数据以 JSON 对象形式返回。

配置外部重定向 URL

某些 Apache Cordova 应用使用回送功能处理 OAuth UI 流程，但 localhost 可能引发问题。需将本地 URL 添加到允许的外部重定向 URL 列表。通过 Azure 门户进行操作：

登录 Azure 门户，选择移动应用。
在工具菜单中打开资源浏览器，导航至配置下的验证设置。
编辑 "allowedExternalRedirectUrls" 元素，添加服务 URL（如 https://localhost:3000）。
保存设置并更新 CORS 设置以包含相同 URL。
新设置生效需要约 10-15 秒。

注册推送通知

安装 phonegap-plugin-push 处理推送通知，可通过命令行或 Visual Studio 添加。以下代码注册设备以接收推送通知：

var pushOptions = {
    android: { senderId: '' },
    ios: { alert: true, badge: true, sound: true },
    windows: {}
};
pushHandler = PushNotification.init(pushOptions);
pushHandler.on('registration', function (data) {
    registrationId = data.registrationId;
    var name = 'gcm'; // 默认 Android
    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) {
    // 处理来自 PNS 的通知数据
});
pushHandler.on('error', function (error) {
    // 处理错误
});

注意：推送通知应从服务器通过通知中心 SDK 发送，避免直接从客户端发送以防止阻斷服務攻击。

有关更多 API 详细信息，请参考官方文档。