如何使用适用于 Azure 移动应用的 JavaScript 客户端库How to Use the JavaScript client library for Azure Mobile Apps

Note

Visual Studio App Center 正在投资于对移动应用开发至关重要的新集成服务。Visual Studio App Center is investing in new and integrated services central to mobile app development. 开发人员可以使用生成测试分发服务来设置持续集成和交付管道。Developers can use Build, Test and Distribute services to set up Continuous Integration and Delivery pipeline. 部署应用后,开发人员可以使用分析诊断服务监视其应用的状态和使用情况,并使用推送服务与用户互动。Once the app is deployed, developers can monitor the status and usage of their app using the Analytics and Diagnostics services, and engage with users using the Push service. 开发人员还可以利用 Auth 对用户进行身份验证,利用数据服务在云中持久保存和同步应用数据。Developers can also leverage Auth to authenticate their users and Data service to persist and sync app data in the cloud. 立即查看 App CenterCheck out App Center today.

概述Overview

本指南介绍如何使用最新的 Azure 移动应用 JavaScript SDK执行常见任务。This guide teaches you to perform common scenarios using the latest JavaScript SDK for Azure Mobile Apps. 对于 Azure 移动应用的新手,请先完成 Azure Mobile Apps Quick Start (Azure 移动应用快速入门)创建后端和表。If you are new to Azure Mobile Apps, first complete Azure Mobile Apps Quick Start to create a backend and create a table. 本指南着重介绍如何在 HTML/JavaScript Web 应用程序中使用移动后端。In this guide, we focus on using the mobile backend in HTML/JavaScript Web applications.

支持的平台Supported platforms

我们将浏览器支持限制为主要浏览器的当前版本和过去版本:Google Chrome、Microsoft Edge、Microsoft Internet Explorer 和 Mozilla Firefox。We limit browser support to the current and last versions of the major browsers: Google Chrome, Microsoft Edge, Microsoft Internet Explorer, and Mozilla Firefox. 我们预期 SDK 可与任何相对现代的浏览器搭配使用。We expect the SDK to function with any relatively modern browser.

由于包已被分发为通用 JavaScript 模块,因此它支持全局、AMD 和 CommonJS 格式。The package is distributed as a Universal JavaScript Module, so it supports globals, AMD, and CommonJS formats.

安装与先决条件Setup and prerequisites

本指南假设已创建了包含表的后端。This guide assumes that you have created a backend with a table. 本指南假设该表的架构与这些教程中的表相同。This guide assumes that the table has the same schema as the tables in those tutorials.

可以通过 npm 命令安装 Azure 移动应用 JavaScript SDK:Installing the Azure Mobile Apps JavaScript SDK can be done via the npm command:

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

也可将库用作 CommonJS 环境(例如 Browserify 和 Webpack)中的 ES2015 模块,或者用作 AMD 库。The library can also be used as an ES2015 module, within CommonJS environments such as Browserify and Webpack and as an AMD library. 例如:For example:

// 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:You can also use a pre-built version of the SDK by downloading directly from our CDN:

<script src="https://zumo.blob.core.chinacloudapi.cn/sdk/azure-mobile-apps-client.min.js"></script>

创建客户端连接Create a client connection

通过创建 WindowsAzure.MobileServiceClient 对象创建客户端连接。Create a client connection by creating a WindowsAzure.MobileServiceClient object. appUrl 替换为到移动应用的 URL。Replace appUrl with the URL to your Mobile App.

var client = WindowsAzure.MobileServiceClient(appUrl);

使用表Work with tables

若要访问或更新数据,请创建到后端表的引用。To access or update data, create a reference to the backend table. tableName 替换为表名称Replace tableName with the name of your table

var table = client.getTable(tableName);

拥有表格引用后,可进一步使用表格:Once you have a table reference, you can work further with your table:

如何:查询表格引用How to: Query a table reference

拥有表格引用后,可用其查询服务器上的数据。Once you have a table reference, you can use it to query for data on the server. 查询使用了“类 LINQ”语言。Queries are made in a "LINQ-like" language. 若要返回表中的所有数据,请使用以下代码:To return all data from the table, use the following code:

/**
 * 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 函数。The success function is called with the results. 请勿在 success 函数中使用 for (var i in results),因为这会在使用其他查询函数(如 .includeTotalCount())时循环访问结果中所含的信息。Do not use for (var i in results) in the success function as that will iterate over information that is included in the results when other query functions (such as .includeTotalCount()) are used.

有关查询语法的详细信息,请参阅 [查询对象文档]。For more information on the Query syntax, see the [Query object documentation].

在服务器上筛选数据Filtering data on the server

可在表格引用上使用 where 子句:You can use a where clause on the table reference:

table
    .where({ userId: user.userId, complete: false })
    .read()
    .then(success, failure);

也可使用筛选对象的函数。You can also use a function that filters the object. 该情况下, this 变量被分配给经过筛选的当前对象。In this case, the this variable is assigned to the current object being filtered. 以下代码在功能上等效于上个示例:The following code is functionally equivalent to the prior example:

function filterByUserId(currentUserId) {
    return this.userId === currentUserId && this.complete === false;
}

table
    .where(filterByUserId, user.userId)
    .read()
    .then(success, failure);

分页浏览数据Paging through data

利用 take()skip() 方法。Utilize the take() and skip() methods. 例如,如想要将表拆分为 100 行记录:For example, if you wish to split the table into 100-row records:

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 字段添加到结果对象。The .includeTotalCount() method is used to add a totalCount field to the results object. 如果不分页,totalCount 字段会填充要返回的记录总数。The totalCount field is filled with the total number of records that would be returned if no paging is used.

然后可使用页变量和某些 UI 按钮提供页列表;使用 loadPage() 为每页加载新记录。You can then use the pages variable and some UI buttons to provide a page list; use loadPage() to load the new records for each page. 实现缓存以加快对已加载记录的访问速度。Implement caching to speed access to records that have already been loaded.

如何:返回排序后的数据How to: Return sorted data

使用 .orderBy().orderByDescending() 查询方法:Use the .orderBy() or .orderByDescending() query methods:

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

有关查询对象的详细信息,请参阅 [查询对象文档]。For more information on the Query object, see the [Query object documentation].

如何:插入数据How to: Insert data

使用相应日期创建 JavaScript 对象并异步调用 table.insert()Create a JavaScript object with the appropriate date and call table.insert() asynchronously:

var newItem = {
    name: 'My Name',
    signupDate: new Date()
};

table
    .insert(newItem)
    .done(function (insertedItem) {
        var id = insertedItem.id;
    }, failure);

成功插入后,插入项随同步操作所需的其他字段一并返回。On successful insertion, the inserted item is returned with the additional fields that are required for sync operations. 使用此信息更新自己的缓存,便于后续更新。Update your own cache with this information for later updates.

Azure 移动应用 Node.js Server SDK 支持用于开发的动态架构。The Azure Mobile Apps Node.js Server SDK supports dynamic schema for development purposes. 在动态架构中,可通过在插入或更新操作中指定列,以将这些列添加到表中。Dynamic Schema allows you to add columns to the table by specifying them in an insert or update operation. 建议先关闭动态架构,再将应用程序迁移到生产。We recommend that you turn off dynamic schema before moving your application to production.

如何:修改数据How to: Modify data

类似于 .insert() 方法,应创建 Update 对象,然后调用 .update()Similar to the .insert() method, you should create an Update object and then call .update(). Update 对象必须包含要更新的记录的 ID,此 ID 在读取记录或调用 .insert()时获取。The update object must contain the ID of the record to be updated - the ID is obtained when reading the record or when calling .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);

如何:删除数据How to: Delete data

若要删除记录,请调用 .del() 方法。To delete a record, call the .del() method. 在对象引用中传递 ID:Pass the ID in an object reference:

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

如何:对用户进行身份验证How to: Authenticate users

Azure 应用服务支持使用各种外部标识提供者对应用用户进行身份验证和授权:百度、和 Microsoft 帐户。Azure App Service supports authenticating and authorizing app users using various external identity providers: Baidu and Microsoft Account. 可以在表中设置权限,以便将特定操作的访问权限限制给已经过身份验证的用户。You can set permissions on tables to restrict access for specific operations to only authenticated users. 还可以在服务器脚本中使用已经过身份验证的用户的标识来实施授权规则。You can also use the identity of authenticated users to implement authorization rules in server scripts. 有关详细信息,请参阅 身份验证入门 教程。For more information, see the Get started with authentication tutorial.

支持两种身份验证流:服务器流和客户端流。Two authentication flows are supported: a server flow and a client flow. 服务器流依赖于提供者的 Web 身份验证界面,因此可提供最简便的身份验证体验。The server flow provides the simplest authentication experience, as it relies on the provider's web authentication interface. 客户端流依赖于提供程序特定的 SDK,因此允许与设备特定的功能(例如单一登录)进行更深入的集成。The client flow allows for deeper integration with device-specific capabilities such as single-sign-on as it relies on provider-specific SDKs.

如何:使用提供程序(服务器流)进行身份验证How to: Authenticate with a provider (Server Flow)

若要让移动应用管理应用中的身份验证过程,必须向标识提供者注册应用。To have Mobile Apps manage the authentication process in your app, you must register your app with your identity provider. 然后,需要在 Azure 应用服务中配置提供者提供的应用程序 ID 和机密。Then in your Azure App Service, you need to configure the application ID and secret provided by your provider. 有关详细信息,请参阅 向应用程序添加身份验证教程。For more information, see the tutorial Add authentication to your app.

注册标识提供者后,使用提供者的名称调用 .login() 方法。Once you have registered your identity provider, call the .login() method with the name of your provider. 例如,若要使用 Facebook 登录,请使用以下代码:For example, to sign in with Facebook use the following code:

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

提供者的有效值为“aad”和“microsoftaccount”。The valid values for the provider are 'aad' and 'microsoftaccount'.

在这种情况下,由 Azure 应用服务管理 OAuth 2.0 身份验证流程。In this case, Azure App Service manages the OAuth 2.0 authentication flow. 它显示所选提供者的登录页,并在使用标识提供者成功登录后生成应用服务身份验证令牌。It displays the sign-in page of the selected provider and generates an App Service authentication token after successful sign-in with the identity provider. login 函数在完成时返回一个 JSON 对象,该对象分别在 userId 和 authenticationToken 字段中公开用户 ID 和应用服务身份验证令牌。The login function, when complete, returns a JSON object that exposes both the user ID and App Service authentication token in the userId and authenticationToken fields, respectively. 可以缓存此令牌,并在它过期之前重复使用。This token can be cached and reused until it expires.

如何:使用提供程序(客户端流)进行身份验证How to: Authenticate with a provider (Client Flow)

用户的应用还能够独立联系标识提供者,并将返回的令牌提供给应用服务以进行身份验证。Your app can also independently contact the identity provider and then provide the returned token to your App Service for authentication. 使用此客户端流可为用户提供单一登录体验,或者从标识提供者中检索其他用户数据。This client flow enables you to provide a single sign-in experience for users or to retrieve additional user data from the identity provider.

社交身份验证基本示例Social Authentication basic example

此示例使用 Facebook 客户端 SDK 进行身份验证:This example uses Facebook client SDK for authentication:

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

此示例假定由相应的提供程序 SDK 提供的令牌存储在令牌变量中。This example assumes that the token provided by the respective provider SDK is stored in the token variable.

如何:获取已经过身份验证的用户的相关信息How to: Obtain information about the authenticated user

可以结合任何 AJAX 库使用 HTTP 调用,从 /.auth/me 终结点检索身份验证信息。The authentication information can be retrieved from the /.auth/me endpoint using an HTTP call with any AJAX library. 确保将 X-ZUMO-AUTH 标头设置为身份验证令牌。Ensure you set the X-ZUMO-AUTH header to your authentication token. 身份验证令牌存储在 client.currentUser.mobileServiceAuthenticationToken中。The authentication token is stored in client.currentUser.mobileServiceAuthenticationToken. 例如,若要使用提取 API:For example, to use the 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) {
        // The user object contains the claims for the authenticated user
    });

提取内容以 npm 包的形式提供,或者可以通过浏览器从 CDNJS 下载。Fetch is available as an npm package or for browser download from CDNJS. 也可以使用 jQuery 或其他 AJAX API 提取信息。You could also use jQuery or another AJAX API to fetch the information. 数据作为 JSON 对象接收。Data is received as a JSON object.

如何:为外部重定向 URL 配置移动应用服务。How to: Configure your Mobile App Service for external redirect URLs.

有多种类型的 JavaScript 应用程序使用环回功能来处理 OAuth UI 流。Several types of JavaScript applications use a loopback capability to handle OAuth UI flows. 这些功能包括:These capabilities include:

  • 在本地运行服务Running your service locally
  • 搭配使用实时重载和 Ionic 框架Using Live Reload with the Ionic Framework
  • 重定向至应用服务进行身份验证。Redirecting to App Service for authentication.

在本地运行可能会导致问题产生,因为默认情况下,应用服务身份验证只配置为允许从移动应用后端访问。Running locally can cause problems because, by default, App Service authentication is only configured to allow access from your Mobile App backend. 使用以下步骤更改应用服务设置,允许在本地运行服务器时进行身份验证:Use the following steps to change the App Service settings to enable authentication when running the server locally:

  1. 登录到 Azure 门户Log in to the Azure portal

  2. 导航到移动应用后端。Navigate to your Mobile App backend.

  3. 在“开发工具” 菜单中,选择“资源浏览器” 。Select Resource explorer in the DEVELOPMENT TOOLS menu.

  4. 单击“转到” ,在新选项卡或窗口中打开移动应用后端的资源浏览器。Click Go to open the resource explorer for your Mobile App backend in a new tab or window.

  5. 展开应用的“config” > “authsettings” 节点。Expand the config > authsettings node for your app.

  6. 单击“编辑” 按钮启用对资源的编辑。Click the Edit button to enable editing of the resource.

  7. 查找 allowedExternalRedirectUrls 元素,此元素应为 null。Find the allowedExternalRedirectUrls element, which should be null. 在数组中添加 URL:Add your URLs in an array:

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

    将数组中的 URL 替换为服务的 URL,在本示例中为本地 Node.js 示例服务的 http://localhost:3000Replace the URLs in the array with the URLs of your service, which in this example is http://localhost:3000 for the local Node.js sample service. 对于 Ripple 服务,也可以根据应用的配置方式,使用 http://localhost:4400 或其他某个 URL。You could also use http://localhost:4400 for the Ripple service or some other URL, depending on how your app is configured.

  8. 在页面顶部,单击“读/写” ,然后单击“PUT” 保存更新。At the top of the page, click Read/Write, then click PUT to save your updates.

还需要将相同的环回 URL 添加到 CORS 允许列表设置:You also need to add the same loopback URLs to the CORS whitelist settings:

  1. 导航回到 Azure 门户Navigate back to the Azure portal.
  2. 导航到移动应用后端。Navigate to your Mobile App backend.
  3. 在“API” 菜单中单击“CORS” 。Click CORS in the API menu.
  4. 在空的“允许的来源” 文本框中输入每个 URL。Enter each URL in the empty Allowed Origins text box. 会创建新的文本框。A new text box is created.
  5. 单击“保存” Click SAVE

后端更新后,可以在应用中使用新的环回 URL。After the backend updates, you will be able to use the new loopback URLs in your app.