Azure Mobile Apps Cordova 插件使用指南

本指南介绍如何使用适用于 Azure Mobile Apps 的最新 Apache Cordova 插件执行常见任务。如果您不熟悉 Azure Mobile Apps，建议先完成 Azure Mobile Apps 快速入门，以建立后端、创建数据表并下载预构建的 Apache Cordova 项目。本指南重点介绍客户端 Apache Cordova 插件。

支持的平台

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

• Android API 19 及以上。
• iOS 8.0 及以上版本。

警告：本文基于即将淘汰的 v4.2.0 库版本。该库不再更新，包括安全更新。建议考虑迁移到 .NET 客户端，如 .NET MAUI，以获得持续支持。

设置和先决条件

本指南假设您已使用数据表建立后端。示例使用快速入门中的 TodoItem 数据表。要将 Azure Mobile Apps 插件添加到您的项目，请使用以下命令：

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 的语言。要返回表中的所有数据，请使用以下代码：

/**
 * 处理通过调用 table.read() 接收到的结果
 *
 * @param {Object} results 作为伪数组的结果
 * @param {int} results.length 结果数组的长度
 * @param {Object} results[] 单个结果
 */
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);
}

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

成功函数会使用结果调用。不要在成功函数中使用 for (var i in results)，因为这会遍历结果中包含的其他信息，当使用其他查询函数如 .includeTotalCount() 时。有关查询语法的详细信息，请参阅 Query 对象文档。

在服务器上筛选数据

可以在数据表引用上使用 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;
// 步骤 1 - 获取总记录数
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 字段添加到结果对象，该字段填充了如果不使用分页将返回的记录总数。然后，可以使用 pages 变量和一些 UI 按钮提供页面列表，并通过 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 支持动态架构以供开发，允许在插入或更新操作中指定列，但建议在将应用程序移至生产环境之前关闭动态架构。

修改数据

创建 Update 对象并调用 .update() 来修改数据，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

注意：iOS 和 Android 中最近的安全变更可能使服务器流程验证无法使用，此时必须使用客户端流程。支持两种验证流程：服务器流程和客户端流程。服务器流程依赖提供者的 Web 验证界面，提供简单体验；客户端流程允许更深入地集成设备特定功能（如单点登录），依赖提供者特定的 SDK。

向提供者进行验证（服务器流程）

要让 Mobile Apps 管理验证过程，需向身份提供者注册应用程序并在 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'。注意：某些提供者可能无法使用服务器流程，需改用客户端流程。服务器流程中，Azure App Service 管理 OAuth 2.0 流程，显示登录页面并生成验证令牌；登录函数返回包含 userId 和 authenticationToken 的 JSON 对象，令牌可缓存至到期。

向提供者进行验证（客户端流程）

应用程序可独立联系身份提供者，然后将令牌提供给 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);
});

假设令牌存储在变量中，具体格式因提供者而异，请参阅 Azure App Service 验证文档 了解详细信息。

获取已验证用户的相关信息

通过 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 获取，数据以 JSON 对象形式返回。

为外部重定向 URL 配置您的移动 App Service

Apache Cordova 应用程序常使用回环地址处理 OAuth UI 流程（如 Ripple 模拟器、Ionic 实时重载、本地运行后端等），但验证服务默认不知如何处理 localhost。需配置 allowedExternalRedirectUrls 以添加回环 URL。

1. 登录 Azure 门户。
2. 选择 所有资源 或 应用服务，点击移动应用程序名称。
3. 点击 工具。
4. 在 观察 菜单中点击 资源管理器，然后点击 Go 打开新窗口。
5. 展开左侧导航中 配置、authsettings 站点的验证设置。
6. 点击 编辑。
7. 找到 "allowedExternalRedirectUrls" 元素，将其值更改为包含服务 URL 的数组，例如：

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

替换 URL 为您的实际服务地址（如 Node.js 服务的 http://localhost:3000 或 Ripple 服务的 http://localhost:4400）。
8. 点击 读/写 按钮，然后点击绿色 PUT 按钮保存设置。

同时，将这些回环 URL 添加到 App Service 的 CORS 设置：

1. 在 Azure 门户中，选择移动应用程序。
2. 打开 设置 边栏，或点击 所有设置。
3. 在 API 菜单下点击 CORS。
4. 输入 URL 并按 Enter，视需添加更多。
5. 点击 保存。

新设置需约 10-15 秒生效。