如何使用適用於 Azure Mobile Apps 的 JavaScript 用戶端程式庫

  • 發行項

概觀

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

支援的平台

我們將瀏覽器支援限制在下列主要瀏覽器的當前最新版本︰Google Chrome、Microsoft Edge、Microsoft Internet Explorer 和 Mozilla Firefox。 我們預期 SDK 可與任何相對近期的瀏覽器搭配運作。

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

設定和必要條件

本指南假設您已建立包含資料表的後端。 本指南假設資料表的結構描述與這些教學課程中的資料表相同。

安裝 Azure Mobile Apps JavaScript SDK 可透過 npm 命令完成︰

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 物件來建立用戶端連接。 以您行動應用程式的 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);

搭配 results 呼叫 success 函式。 請勿在 success 函式中使用 for (var i in results)，因為當使用其他查詢函式時 (例如 .includeTotalCount())，這樣會反覆檢查結果中包含的資訊。

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

篩選伺服器上的資料

您可以在資料表參考上使用 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 欄位加入至 results 物件。 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 驗證權杖。 login 函式完成時會傳回 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 所提供的權杖儲存在 token 變數中。

作法：取得已驗證使用者的相關資訊

您可以使用 HTTP 呼叫搭配任何 AJAX 程式庫，從 /.auth/me 端點擷取驗證資訊。 請確定您設定 X-ZUMO-AUTH 標頭至您的驗證 Token。 驗證 Token 儲存於 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 設定行動裝置App Service。

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

  • 在本機執行服務
  • 搭配 Ionic 架構使用即時重新載入
  • 重新導向至 App Service 以進行驗證。

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

  1. 登入 Azure 入口網站

  2. 瀏覽至行動裝置應用程式後端。

  3. 選取 [開發工具] 功能表中的 [資源總管]。

  4. 按一下 [執行] ，在新的索引標籤或視窗中開啟行動裝置應用程式後端的資源總管。

  5. 展開應用程式的組> 態驗證節點。

  6. 按一下 [編輯] 按鈕來啟用資源的編輯。

  7. 尋找 allowedExternalRedirectUrls 元素，此元素應該是 null。 在陣列中新增 URL：

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

    使用您服務的 URL 取代陣列中的 URL，在此範例中為本機 Node.js 範例服務的 https://localhost:3000 。 根據您應用程式的設定方式而定，您也可以使用 Ripple 服務的 https://localhost:4400 或一些其他的 URL。

  8. 在頁面頂端，按一下 [讀取/寫入]，然後按一下 [PUT] 以儲存您的更新。

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

  1. 流覽回Azure 入口網站。
  2. 瀏覽至行動裝置應用程式後端。
  3. 按一下[API] 功能表中的[CORS]。
  4. 在空的 [允許的原點] 文字方塊中輸入每一個 URL。 隨即會建立新的文字方塊。
  5. 按一下 [儲存]

後端更新之後，您就可以在應用程式中使用新的回送 URL。