如何使用适用于 Azure 移动应用的 JavaScript 客户端库

2019-06-25

概述

本指南介绍如何使用适用于 Azure 移动应用的最新 JavaScript SDK 执行常见方案。如果不熟悉 Azure 移动应用，请先完成 Azure 移动应用快速入门以创建后端并创建表。本指南重点介绍如何在 HTML/JavaScript Web 应用程序中使用移动后端。

支持的平台

我们将浏览器支持限制为当前和最新版本的主要浏览器：Google Chrome、Microsoft Edge、Microsoft Internet Explorer 和 Mozilla Firefox。我们希望 SDK 能够使用任何相对现代的浏览器运行。

该包作为通用 JavaScript 模块分发，因此它支持全局、AMD 和 CommonJS 格式。

设置和先决条件

本指南假定你已使用表创建了后端。本指南假定该表的架构与这些教程中的表具有相同的架构。

可以通过 npm 以下命令安装 Azure 移动应用 JavaScript SDK：

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';

还可以通过直接从 CDN 下载来使用预生成的 SDK 版本：

<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 字段填充了不使用分页时将返回的记录总数。

然后，可以使用页面变量和某些 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 支持用于开发的动态架构。动态模式允许你通过在插入或更新操作中指定列来向表中添加列。建议在将应用程序移动到生产环境之前关闭动态架构。

如何：修改数据

与 .insert() 方法类似，应创建 Update 对象，然后调用 .update()。 update 对象必须包含要更新的记录的 ID - 读取记录或调用 .insert()时获取 ID。

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() 方法。在对象引用中传递 ID：

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

如何：对用户进行身份验证

Azure 应用服务支持使用各种外部标识提供者对应用用户进行身份验证和授权：Facebook、Google、Microsoft 帐户和 Twitter。可以在表中设置权限，以便将特定操作的访问权限限制给已经过身份验证的用户。还可以使用经过身份验证的用户的标识在服务器脚本中实现授权规则。有关详细信息，请参阅身份验证入门教程。

支持两个身份验证流：服务器流和客户端流。服务器流提供最简单的身份验证体验，因为它依赖于提供程序的 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”。

注释

Google 身份验证当前无法通过服务器流工作。若要使用 Google 进行身份验证，必须使用客户端流方法。

在这种情况下，Azure 应用服务管理 OAuth 2.0 身份验证流。它显示所选提供程序的登录页，并在与标识提供者成功登录后生成应用服务身份验证令牌。登录函数完成后返回一个 JSON 对象，该对象分别在 userId 和 authenticationToken 字段中公开用户 ID 和应用服务身份验证令牌。此令牌可以缓存并重复使用，直到它过期。

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

应用还可以独立联系标识提供者，然后将返回的令牌提供给应用服务进行身份验证。通过此客户端流，可以为用户提供单一登录体验，或从标识提供者检索其他用户数据。

此示例使用 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 提供的令牌存储在令牌变量中。

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

可以使用具有任何 AJAX 库的 /.auth/me HTTP 调用从终结点检索身份验证信息。确保将 X-ZUMO-AUTH 标头设置为身份验证令牌。身份验证令牌存储在 client.currentUser.mobileServiceAuthenticationToken中。例如，若要使用提取 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) {
        // The user object contains the claims for the authenticated user
    });

Fetch 可以作为 npm 包获取，或者从 CDNJS 下载以用于浏览器。还可以使用 jQuery 或其他 AJAX API 提取信息。数据作为 JSON 对象接收。

如何配置移动应用服务以支持外部重定向的网址。

多种 JavaScript 应用程序使用环回功能来处理 OAuth UI 流。这些功能包括：

在本地运行服务
将 Live Reload 与 Ionic 框架配合使用
重定向到应用服务进行身份验证。

在本地运行可能会导致问题，因为默认情况下，应用服务身份验证仅配置为允许从移动应用后端进行访问。使用以下步骤更改应用服务设置，以便在本地运行服务器时启用身份验证：

登录到 Azure 门户
导航到移动应用后端。
在“开发工具”菜单中选择“资源资源管理器”。
单击 “转到 ”，在新选项卡或窗口中打开移动应用后端的资源资源管理器。
展开应用的配置>身份验证设置 节点。
单击“ 编辑 ”按钮以启用资源编辑。
查找 allowedExternalRedirectUrls 元素，该元素应为 null。将你的 URLs 添加到数组中：
```
  "allowedExternalRedirectUrls": [
      "https://localhost:3000",
      "https://localhost:3000"
  ],
```
将数组中的 URL 替换为您服务的 URL，在此示例中，本地 Node.js 示例服务的 URL 用 https://localhost:3000 表示。您还可以将 https://localhost:4400 用于 Ripple 服务或其他 URL，具体取决于应用程序的配置方式。
在页面顶部，单击“ 读/写”，然后单击 PUT 保存更新。

您还需要将相同的回环 URL 添加到 CORS 允许列表设置中：

导航回 Azure 门户。
导航到移动应用后端。
在 API 菜单中单击 CORS。
在空的“允许来源”文本框中输入每个 URL。将创建新的文本框。
单击“保存”

后端更新后，你将能够在应用中使用新的环回 URL。

通过