Azure移动应用Cordova插件使用指南

本指南介绍如何使用适用于 Azure 移动应用的最新 Apache Cordova 插件执行常见方案。如果你不熟悉 Azure 移动应用，建议先完成 Azure 移动应用快速入门，创建后端、表并下载预生成的 Apache Cordova 项目。本指南重点介绍客户端 Apache Cordova 插件。

支持的平台

此 SDK 支持 iOS、Android 和 Windows 设备上的 Apache Cordova v6.0.0 及更高版本，具体平台支持如下：

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

注意：本文基于已停用的 v4.2.0 库版本，不会再有更新，包括安全更新。建议考虑迁移到 .NET 客户端（如 .NET MAUI）以获取持续支持。

设置和先决条件

本指南假设你已使用表创建了后端，例如快速入门中的 TodoItem 表。要将 Azure 移动应用插件添加到项目，请使用以下命令：

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 移动应用 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()）时，它会遍历额外信息。有关查询语法的详细信息，请参阅 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;
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 按钮来导航，并通过 loadPage() 加载每页记录，建议实现缓存以加速访问。

返回已排序的数据

使用 .orderBy() 或 .orderByDescending() 查询方法进行排序：

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

更多细节请参考 Query 对象文档。

插入数据

创建 JavaScript 对象并异步调用 table.insert()：

var newItem = {
    name: 'My Name',
    signupDate: new Date()
};
table.insert(newItem).done(function (insertedItem) {
    var id = insertedItem.id;
}, failure);

成功插入后，返回的插入项包含额外字段，可用于更新本地缓存。Azure 移动应用 Node.js 服务器 SDK 支持动态架构，允许在插入或更新时添加列，但建议在生产环境中关闭动态架构。

修改数据

类似插入操作，创建更新对象并调用 .update()，更新对象必须包含记录的 ID（从读取记录或插入操作获取）：

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

删除数据

调用 .del() 方法删除记录，传递包含 ID 的对象引用：

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

对用户进行身份验证

Azure 应用服务支持使用外部标识提供者（如 Facebook、Google、Microsoft 帐户和 Twitter）进行身份验证和授权。可以设置表权限限制仅允许认证用户访问特定操作，或在服务器脚本中使用认证用户标识实现授权规则。详细信息请参阅身份验证入门教程。

在 Apache Cordova 应用中使用身份验证时，必须安装以下 Cordova 插件：cordova-plugin-device 和 cordova-plugin-inappbrowser。注意，由于 iOS 和 Android 的安全更改，服务器流身份验证可能不可用，此时需使用客户端流。

支持两种身份验证流：服务器流和客户端流。服务器流依赖提供商的 Web 身份验证接口，体验简单；客户端流集成特定于设备的功能（如单一登录），依赖提供商的设备 SDK。

使用提供程序进行身份验证（服务器流）

要让移动应用管理身份验证过程，需将应用注册到标识提供者，并在 Azure 应用服务中配置应用程序 ID 和机密。注册后，使用提供者名称调用 .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 应用服务管理 OAuth 2.0 身份验证流，显示登录页并生成身份验证令牌。登录完成后返回 JSON 对象，包含 userId 和 authenticationToken 字段，令牌可缓存使用直到过期。

使用提供程序进行身份验证（客户端流）

应用可以独立联系标识提供者，然后将返回的令牌提供给应用服务进行身份验证，实现单一登录或获取额外用户数据。例如使用 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 提供的令牌，具体格式请参阅 Azure 应用服务身份验证文档。

获取有关经过身份验证的用户的信息

通过 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 对象包含认证用户的声明信息
});

可以使用 npm 包或 CDNJS 下载 fetch，数据以 JSON 对象形式返回。

为外部重定向 URL 配置移动应用服务

某些 Apache Cordova 应用程序使用环回功能处理 OAuth UI 流，但 localhost 的 OAuth 流可能导致问题，因为身份验证服务默认不了解服务。有问题的场景包括波纹仿真器、Ionic 实时重载、本地运行移动后端或在不同 Azure 应用服务中运行后端。

按照以下步骤添加本地设置到配置：

1. 登录 Azure 门户，选择移动应用资源。
2. 在工具菜单中点击资源资源管理器，然后转到。
3. 展开站点的配置、身份验证节点，点击编辑。
4. 找到 "allowedExternalRedirectUrls" 元素，将其设置为包含环回 URL 的数组，例如：

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

   根据你的服务 URL 进行调整。
5. 点击读/写按钮，然后点击 PUT 按钮保存设置。

同时，将这些环回 URL 添加到应用服务的 CORS 设置：

1. 在 Azure 门户中，选择移动应用，点击所有设置下的 CORS。
2. 输入 URL 并保存。

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