如何使用適用於 Azure Mobile Apps 的 JavaScript 用戶端連結庫

概觀

本指南會教導您使用適用於 Azure Mobile Apps 的最新 JavaScript SDK 來執行常見案例。如果您不熟悉 Azure Mobile Apps，請先完成 Azure Mobile Apps 快速入門來建立後端並建立數據表。在本指南中，我們著重於在 HTML/JavaScript Web 應用程式中使用行動後端。

支援的平臺

我們將瀏覽器支援限制為目前和最新版本的主要瀏覽器：Google Chrome、Microsoft Edge、Microsoft Internet Explorer 和 Mozilla Firefox。我們預期 SDK 會使用任何相對現代化的瀏覽器運作。

套件會以通用 JavaScript 模組的形式散發，因此它支援全域、AMD 和 CommonJS 格式。

設定和必要條件

本指南假設您已使用數據表建立後端。本指南假設數據表與這些教學課程中的數據表具有相同的架構。

您可以透過 npm 命令安裝 Azure Mobile Apps JavaScript SDK：

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

函式庫也可以作為 ES2015 模組，在像是 Browserify 和 Webpack 這樣的 CommonJS 環境中以及作為 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 物件，以建立用戶端連線。使用行動應用程式的 URL 取代 appUrl。

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 欄位會填入在未使用分頁時將返回的記錄總數。

然後，您可以使用 pages 變數和某些 UI 按鈕來提供頁面清單;使用 loadPage() 載入每個頁面的新記錄。實作快取以加速存取已載入的記錄。

如何：傳回已排序的數據

使用 .orderBy() 或 .orderByDescending() 查詢方法：

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

如需 Query 物件的詳細資訊，請參閱 [Query 物件檔]。

如何：插入數據

使用適當的日期建立 JavaScript 物件，並以異步方式呼叫 table.insert()：

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

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

成功插入時，會傳回插入的專案，其中包含同步作業所需的其他欄位。使用此資訊更新您自己的快取，以便日後更新。

Azure Mobile Apps Node.js Server SDK 支援動態架構以供開發之用。動態模式允許您透過在插入或更新操作中指定來向表格添加欄位。建議您先關閉動態架構，再將應用程式移至生產環境。

如何：修改數據

類似於 .insert() 方法，您應該建立 Update 物件，然後呼叫 .update()。 update 對象必須包含要更新的記錄標識碼 - 讀取記錄時或呼叫 .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() 方法。在物件參考中傳遞識別碼：

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

如何：驗證使用者

Azure App Service 支援使用各種外部身分識別提供者來驗證和授權應用程式使用者：Facebook、Google、Microsoft 帳戶和 Twitter。您可以設定資料表的許可權，將特定作業的存取限制為僅限已驗證的使用者。您也可以使用已驗證使用者的身分識別，在伺服器腳本中實作授權規則。如需詳細資訊，請參閱開始使用驗證教學課程。

支援兩個驗證流程：伺服器流程和用戶端流程。伺服器流程提供最簡單的驗證體驗，因為它依賴提供者的 Web 驗證介面。用戶端流程可讓您更深入地整合裝置特定功能，例如單一登錄，因為它依賴提供者特定的 SDK。

如何與提供者進行身份驗證（伺服器端流程）

若要讓Mobile Apps管理應用程式中的驗證程式，您必須向識別提供者註冊您的應用程式。然後在 Azure App Service 中，您必須設定提供者所提供的應用程式識別碼和秘密。如需詳細資訊，請參閱教學課程將驗證新增至您的應用程式。

註冊識別提供者之後，請使用提供者的名稱呼叫 .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 App Service 會管理 OAuth 2.0 驗證流程。它會顯示所選提供者的登入頁面，並在與識別提供者成功登入之後產生App Service 驗證令牌。完成時，登入函式會傳回 JSON 對象，分別在userId和 authenticationToken 字段中公開使用者標識碼和 App Service 驗證令牌。此令牌可以快取並重複使用，直到到期為止。

如何：向提供者進行驗證（用戶端流程）

您的應用程式也可以獨立連絡識別提供者，然後將傳回的令牌提供給 App Service 進行驗證。此用戶端流程可讓您為使用者提供單一登錄體驗，或從識別提供者擷取其他用戶數據。

此範例使用 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 提供的令牌會儲存在令牌變數中。

如何：取得已驗證使用者的相關信息

您可以使用 HTTP 呼叫與任何 AJAX 連結庫，從 /.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
    });

"Fetch可用作npm套件或從CDNJS下載以供瀏覽器使用。" 您也可以使用 jQuery 或其他 AJAX API 來擷取資訊。數據會以 JSON 物件的形式接收。

如何為外部重新導向 URL 設定行動應用程式服務。

數種類型的 JavaScript 應用程式會使用回送功能來處理 OAuth UI 流程。這些功能包括：

在本機執行服務
使用 Ionic 框架的 Live Reload
重新導向至 App Service 以進行驗證。

在本機執行可能會導致問題，因為根據預設，App Service 驗證只會設定為允許從行動應用程式後端存取。使用下列步驟來變更 App Service 設定，以在本機執行伺服器時啟用驗證：

登入 Azure 入口網站
流覽至您的行動應用程式後端。
在 [開發工具] 功能表中選取 [資源瀏覽器]。
按一下移至在新的索引標籤或視窗中開啟行動應用程式後端的資源總管。
展開應用程式的 config>authsettings 節點。
按兩下 [ 編輯] 按鈕以啟用資源的編輯。
尋找 allowedExternalRedirectUrls 元素，其應該是 null。請將您的 URL 加入到陣列中：
```
  "allowedExternalRedirectUrls": [
      "https://localhost:3000",
      "https://localhost:3000"
  ],
```
以您服務的 URL 取代陣列中的 URL，在此範例中，https://localhost:3000 指的是本地 Node.js 範例服務。您也可以針對 Ripple 服務或其他 URL 使用 https://localhost:4400 ，視您的應用程式設定方式而定。
在頁面頂端，按兩下 [ 讀取/寫入]，然後按兩下 [PUT ] 以儲存您的更新。

您也需要將相同的回送 URL 新增至 CORS 允許清單設定：

返回 Azure 入口網站。
流覽至您的行動應用程式後端。
在 API 功能表中點擊 CORS。
在空白的 [允許來源] 文本框中輸入每個 URL。系統會建立新的文字框。
按一下 [儲存]

後端更新之後，您將能夠在應用程式中使用新的回送 URL。

Last updated on 2019-06-25

共用方式為