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

本指南介绍如何使用最新的 Azure 移动应用 JavaScript SDK 执行常见任务。对于 Azure 移动应用的新手,请先完成 Azure Mobile Apps Quick Start(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

也可将库用作 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.chinacloudapi.cn/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 应用服务支持使用各种外部标识提供者(包括 Microsoft 帐户)对应用用户进行身份验证和授权。你可以在表中设置权限,以便将特定操作的访问权限限制给已经过身份验证的用户。还可以在服务器脚本中使用已经过身份验证的用户的标识来实施授权规则。有关详细信息,请参阅 Get started with authentication(身份验证入门)教程。

支持两种身份验证流:服务器流和客户端流。服务器流依赖于提供者的 Web 身份验证界面,因此可提供最简便的身份验证体验。客户端流依赖于提供程序特定的 SDK,因此允许与设备特定的功能(例如单一登录)进行更深入的集成。

如何:使用提供程序(服务器流)进行身份验证

若要让移动应用管理应用中的身份验证过程,必须向标识提供者注册应用。然后,需要在 Azure App Service 中配置提供者提供的应用程序 ID 和机密。有关详细信息,请参阅向应用程序添加身份验证教程。

注册标识提供者后,只需使用提供者的名称调用 .login() 方法即可。例如,若要使用 microsoftaccount 登录,请使用以下代码。

client.login("microsoftaccount").done(function (results) {
     alert("You are now logged in as: " + results.userId);
}, function (err) {
     alert("Error: " + err);
});

如果使用的标识提供程序不是 microsoftaccount,请将传递给上述 login 方法的值更改为 aad

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

如何:使用提供程序(客户端流)进行身份验证

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

Microsoft 帐户示例

以下示例使用 Live SDK,该 SDK 使用 Microsoft 帐户来支持 Windows 应用商店应用程序的单一登录:

WL.login({ scope: "wl.basic"}).then(function (result) {
      client.login(
            "microsoftaccount",
            {"authenticationToken": result.session.authentication_token})
      .done(function(results){
            alert("You are now logged in as: " + results.userId);
      },
      function(error){
            alert("Error: " + err);
      });
});

这个示例将从 Live Connect 获取一个令牌,并通过调用 login 函数将该令牌提供给你的应用服务。

如何:获取已经过身份验证的用户相关信息

可以使用具有任何 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 框架
  • 重定向至应用服务进行身份验证。

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

  1. 登录到 Azure 门户
  2. 导航到移动应用后端。
  3. 在“开发工具”菜单中,选择“资源浏览器”。
  4. 单击“转到” ,在新选项卡或窗口中打开移动应用后端的资源浏览器。
  5. 展开应用的“config” > “authsettings”节点。
  6. 单击“编辑” 按钮启用对资源的编辑。
  7. 查找 allowedExternalRedirectUrls 元素,此元素应为 null。 在数组中添加 URL:

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

    将数组中的 URL 替换为服务的 URL,在本示例中为本地 Node.js 示例服务的 http://localhost:3000。对于 Ripple 服务,也可以根据应用的配置方式,使用 http://localhost:4400 或其他某个 URL。

  8. 在页面顶部,单击“读/写”,然后单击“PUT”保存更新。

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

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

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