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

项目
06/25/2019

概述

本指南介绍如何使用最新的适用于 Azure 移动应用的 JavaScript SDK 执行常见任务。对于 Azure 移动应用的新手，请先完成 Azure 移动应用快速入门创建后端和表。本指南着重介绍如何在 HTML/JavaScript Web 应用程序中使用移动后端。

受支持的平台

我们将浏览器支持限制为主要浏览器的当前最新版本：Google Chrome、Microsoft Edge、Microsoft Internet Explorer 和 Mozilla Firefox。我们期望 SDK 能与任何相对新式的浏览器一起运作。

由于包已被分发为通用 JavaScript 模块，因此它支持 globals、AMD 和 CommonJS 格式。

安装与先决条件

本指南假设已创建了包含表的后端。本指南假设该表的架构与这些教程中的表相同。

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

npm install azure-mobile-apps-client --save

也可将库用作 CommonJS 环境（例如 Browserify 和 Webpack）中的 ES2015 模块，或者用作 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);

随结果调用 success 函数。请勿在 success 函数中使用 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);

有关查询对象的详细信息，请参阅 [查询对象文档]。

如何：插入数据

使用相应日期创建 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 Server SDK 支持用于开发的动态架构。使用动态架构可将列添加到表中，在插入或更新操作中指定这些列即可。建议先关闭动态架构，再将应用程序迁移到生产。

如何：修改数据

类似于 .insert() 方法，应创建 Update 对象，并调用 .update()。 update 对象必须包含要更新的记录的 ID，此 ID 在读取记录或调用 .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() 方法。在对象引用中传递 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 App Service 中配置提供者提供的应用程序 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 身份验证流。它显示所选提供者的登录页，并在使用标识提供者成功登录后生成应用服务身份验证令牌。 login 函数在完成时会返回一个 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 库使用 HTTP 调用，从 /.auth/me 终结点检索身份验证信息。确保将 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
    });

提取的内容以 npm 包的形式提供，或者可以通过浏览器从 CDNJS 下载。也可以使用 jQuery 或其他 AJAX API 提取信息。数据作为 JSON 对象接收。

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

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

在本地运行服务
搭配使用实时重载和 Ionic 框架
重定向至应用服务进行身份验证。

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

登录到 Azure 门户
导航到移动应用后端。
在“开发工具”菜单中，选择“资源浏览器”。
单击“开始”在新选项卡或窗口中打开移动应用后端的资源管理器。
展开应用的“config”>“authsettings”节点。
单击“编辑”按钮可对资源进行编辑。
查找应为 null 的“allowedExternalRedirectUrls”元素。在数组中添加 URL：
```
  "allowedExternalRedirectUrls": [
      "https://localhost:3000",
      "https://localhost:3000"
  ],
```
将数组中的 URL 替换为服务的 URL，在本示例中为本地 Node.js 示例服务的 https://localhost:3000。对于 Ripple 服务，也可以根据应用的配置方式，使用 https://localhost:4400 或其他某个 URL。
在页面顶部，单击“读/写”，并单击“PUT”保存更新。

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

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

后端更新后，可以在应用中使用新的环回 URL。