如何使用適用於 Azure Mobile Apps 的 Apache Cordova 外掛程式

發行項
12/13/2023

本指南會教導您使用適用於 Azure Mobile Apps 的最新 Apache Cordova 外掛程式來執行常見案例。如果您不熟悉 Azure Mobile Apps，請先完成 Azure Mobile Apps 快速入門來建立後端、建立數據表，以及下載預先建置的 Apache Cordova 專案。在本指南中，我們將焦點放在用戶端 Apache Cordova 外掛程式。

支援的平台

此 SDK 支援 iOS、Android 和 Windows 裝置上的 Apache Cordova v6.0.0 和更新版本。平台支援如下所示：

Android API 19+。
iOS 8.0 版和更新版本。

警告

本文涵蓋即將淘汰的 v4.2.0 連結庫版本資訊。不會對此連結庫進行進一步的更新，包括安全性問題的更新。請考慮移至 .NET 用戶端，例如 .NET MAUI 以取得持續支援。

設定和必要條件

本指南假設您已使用數據表建立後端。範例會 TodoItem 使用快速入門中的數據表。若要將 Azure Mobile Apps 外掛程式新增至您的專案，請使用下列命令：

cordova plugin add cordova-plugin-ms-azure-mobile-apps

如需建立第一個 Apache Cordova 應用程式的詳細資訊，請參閱其檔。

設定仿生 v2 應用程式

若要正確設定 Balancer v2 專案，請先建立基本應用程式並新增 Cordova 外掛程式：

ionic start projectName --v2
cd projectName
ionic plugin add cordova-plugin-ms-azure-mobile-apps

將下列幾行新增至 app.component.ts 以建立客戶端物件：

declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");

您現在可以在瀏覽器中建置並執行專案：

ionic platform add browser
ionic run browser

Azure Mobile Apps Cordova 外掛程式同時支援仿生 v1 和 v2 應用程式。只有仿生 v2 應用程式需要對象的額外宣告 WindowsAzure 。

建立客戶端連線

藉由建立物件來建立 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);

成功函式會使用結果呼叫。請勿在 for (var i in results) 成功函式中使用，因為它會在使用其他查詢函式時 .includeTotalCount()逐一查看結果中包含的資訊。

如需查詢語法的詳細資訊，請參閱 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 字段新增至結果物件。 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 服務支援使用各種外部身分識別提供者驗證和授權應用程式使用者：Facebook、Google、Microsoft 帳戶和 Twitter。您可以設定資料表的許可權，將特定作業的存取限制為僅限已驗證的使用者。您也可以使用已驗證使用者的身分識別，在伺服器腳本中實作授權規則。如需詳細資訊，請參閱開始使用驗證教學課程。

在 Apache Cordova 應用程式中使用驗證時，必須提供下列 Cordova 外掛程式：

注意

iOS 和 Android 中最近的安全性變更可能會使伺服器流程驗證無法使用。在這些情況下，您必須使用用戶端流程。

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

向提供者進行驗證（伺服器流程）

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

註冊識別提供者之後，請使用提供者的名稱呼叫 .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』。

注意

基於安全性考慮，某些驗證提供者可能無法使用伺服器流程。在這些情況下，您必須使用用戶端流程方法。

在此情況下，Azure App 服務管理 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 提供的令牌會儲存在令牌變數中。每個提供者所需的詳細數據稍有不同。請參閱 Azure App 服務驗證和授權檔，以判斷承載的確切形式。

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

您可以使用 HTTP 呼叫搭配任何 HTTP/REST 連結庫，從 /.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 下載瀏覽器。數據會以 JSON 物件的形式接收。

為外部重新導向 URL 設定您的行動 App Service。

數種類型的 Apache Cordova 應用程式會使用回送功能來處理 OAuth UI 流程。 localhost 上的 OAuth UI 流程會造成問題，因為驗證服務預設只會知道如何使用您的服務。有問題的 OAuth UI 流程範例包括：

波紋模擬器。
即時重載與仿生。
在本機執行行動後端
以與提供驗證的不同 Azure App 服務執行行動後端。

請遵循下列指示，將本機設定新增至組態：

登入 Azure 入口網站
選取 [所有資源 ] 或 [應用程式服務 ]，然後按兩下行動應用程式的名稱。
點選 「工具]
單擊 [觀察] 功能表中的 [ 資源總管 ]，然後按兩下 [ 移至]。隨即開啟新的視窗或索引標籤。
展開左側導覽中網站的設定、驗證節點。
按一下 [編輯]
尋找 “allowedExternalRedirectUrls” 元素。它可以設定為 null 或值的陣列。將值變更為下列值：
```
"allowedExternalRedirectUrls": [
    "http://localhost:3000",
    "https://localhost:3000"
],
```
將 URL 取代為服務的 URL。範例包括 http://localhost:3000 （針對 Node.js 範例服務），或 http://localhost:4400 （針對波紋服務）。不過，這些 URL 是範例 - 您的情況，包括範例中所提及的服務，可能不同。
按兩下畫面右上角的 [ 讀取/寫入 ] 按鈕。
按兩下綠色 PUT 按鈕。

此時會儲存這些設定。在設定完成儲存之前，請勿關閉瀏覽器視窗。此外，將這些回送 URL 新增至 App Service 的 CORS 設定：

登入 Azure 入口網站
選取 [所有資源 ] 或 [應用程式服務 ]，然後按兩下行動應用程式的名稱。
[設定] 刀鋒視窗會自動開啟。如果沒有，請按兩下 [所有設定]。
單擊 [API] 功能表下的 [CORS ]。
輸入您想要在提供的方塊中新增的 URL，然後按 Enter 鍵。
視需要輸入更多 URL。
按兩下 [ 儲存 ] 以儲存設定。

新設定需要大約 10-15 秒才會生效。

如何使用適用於 Azure Mobile Apps 的 Apache Cordova 外掛程式

支援的平台

設定和必要條件

設定仿生 v2 應用程式

建立客戶端連線

使用表格

查詢數據表參考

篩選伺服器上的數據

分頁數據

傳回已排序的數據

插入資料

修改資料

刪除資料

驗證使用者

向提供者進行驗證（伺服器流程）

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

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

為外部重新導向 URL 設定您的行動 App Service。

意見反應

意見反應

其他資源

如何使用適用於 Azure Mobile Apps 的 Apache Cordova 外掛程式

支援的平台

設定和必要條件

設定 仿生 v2 應用程式

建立客戶端連線

使用表格

查詢數據表參考

篩選伺服器上的數據

分頁數據

傳回已排序的數據

插入資料

修改資料

刪除資料

驗證使用者

向提供者進行驗證 （伺服器流程）

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

社交驗證基本範例

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

為外部重新導向 URL 設定您的行動 App Service。

意見反應

意見反應

其他資源

設定仿生 v2 應用程式

向提供者進行驗證（伺服器流程）

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