Azure Mobile Apps 用の Apache Cordova プラグインを使用する方法

[アーティクル]
12/19/2022

手記

この製品は提供終了です。 .NET 8 以降を使用するプロジェクトの代わりに、Community Toolkit Datasync ライブラリを参照してください。

このガイドでは、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 MAUI などの .NET クライアントに移行することを検討してください。

セットアップと前提条件

このガイドでは、テーブルを含むバックエンドを作成していることを前提としています。例では、クイックスタートの TodoItem テーブルを使用します。 Azure Mobile Apps プラグインをプロジェクトに追加するには、次のコマンドを使用します。

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

最初の Apache Cordova アプリ作成する方法の詳細については、そのドキュメントを参照してください。

Ionic v2 アプリの設定

Ionic 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 プラグインは、Ionic v1 アプリと v2 アプリの両方をサポートしています。 WindowsAzure オブジェクトに対して追加の宣言が必要なのは、Ionic v2 アプリだけです。

クライアント接続を作成する

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);

成功関数は結果と共に呼び出されます。他のクエリ関数 (.includeTotalCount()など) が使用されている場合に結果に含まれる情報を反復処理するために、成功関数で for (var i in results) を使用しないでください。

クエリ構文の詳細については、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 フィールドには、ページングが使用されていない場合に返されるレコードの合計数が入力されます。

その後、ページ変数といくつかの UI ボタンを使用して、ページリストを提供できます。loadPage() を使用して、各ページの新しいレコードを読み込みます。既に読み込まれているレコードへのアクセスを高速化するためのキャッシュを実装します。

並べ替えられたデータを返す

.orderBy() または .orderByDescending() クエリメソッドを使用します。

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

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()を呼び出す必要があります。更新オブジェクトには、更新するレコードの 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 App Service では、Facebook、Google、Microsoft アカウント、Twitter など、さまざまな外部 ID プロバイダーを使用したアプリユーザーの認証と承認がサポートされています。特定の操作のアクセスを認証済みユーザーのみに制限するように、テーブルに対するアクセス許可を設定できます。認証されたユーザーの ID を使用して、サーバースクリプトに承認規則を実装することもできます。詳細については、認証の概要に関するチュートリアルを参照してください。

Apache Cordova アプリで認証を使用する場合は、次の Cordova プラグインを使用できる必要があります。

cordova-plugin-device の
cordova-plugin-inappbrowser

手記

iOS と Android の最近のセキュリティ変更により、サーバーフロー認証が使用できなくなる可能性があります。このような場合は、クライアントフローを使用する必要があります。

サーバーフローとクライアントフローの 2 つの認証フローがサポートされています。サーバーフローは、プロバイダーの Web 認証インターフェイスに依存するため、最も単純な認証エクスペリエンスを提供します。クライアントフローを使用すると、プロバイダー固有のデバイス固有の SDK に依存するため、シングルサインオンなどのデバイス固有の機能とのより深い統合が可能になります。

プロバイダーによる認証 (サーバーフロー)

Mobile Apps でアプリの認証プロセスを管理するには、アプリを ID プロバイダーに登録する必要があります。次に、Azure App Service で、プロバイダーによって提供されるアプリケーション ID とシークレットを構成する必要があります。詳細については、チュートリアル「アプリに認証を追加する」を参照してください。

ID プロバイダーを登録したら、プロバイダーの名前で .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 Service は OAuth 2.0 認証フローを管理します。選択したプロバイダーのサインインページが表示され、ID プロバイダーで正常にサインインした後に App Service 認証トークンが生成されます。ログイン関数は、完了すると、userId フィールドと authenticationToken フィールドのユーザー ID と App Service 認証トークンの両方を公開する JSON オブジェクトを返します。このトークンは、有効期限が切れるまでキャッシュして再利用できます。

プロバイダーによる認証 (クライアントフロー)

アプリは、ID プロバイダーに個別に連絡し、返されたトークンを認証のために App Service に提供することもできます。このクライアントフローを使用すると、ユーザーにシングルサインインエクスペリエンスを提供したり、ID プロバイダーから追加のユーザーデータを取得したりできます。

この例では、認証に 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 Service の認証と承認に関するドキュメントを参照してください。

認証されたユーザーに関する情報を取得する

任意の HTTP/REST ライブラリで HTTP 呼び出しを使用して、/.auth/me エンドポイントから認証情報を取得できます。 X-ZUMO-AUTH ヘッダーを認証トークンに設定していることを確認します。認証トークンは、client.currentUser.mobileServiceAuthenticationTokenに格納されます。たとえば、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からブラウザーダウンロードするために使用できます。データは JSON オブジェクトとして受信されます。

外部リダイレクト URL 用に Mobile App Service を構成します。

いくつかの種類の Apache Cordova アプリケーションでは、ループバック機能を使用して OAuth UI フローを処理します。 localhost 上の OAuth UI フローは、認証サービスが既定でサービスを利用する方法のみを認識しているため、問題を引き起こします。問題のある OAuth UI フローの例を次に示します。

Ripple エミュレーター。
Ionic を使用したライブリロード。
モバイルバックエンドをローカルで実行する
認証を提供する Azure App Service とは異なる Azure App Service でモバイルバックエンドを実行する。

次の手順に従って、ローカル設定を構成に追加します。

Azure portal にログインします
[すべてのリソース選択するか、App Services してから、モバイルアプリの名前をクリックします。
[ツール] をクリックします
[監視] メニューリソースエクスプローラーをクリックし、[移動] をクリックします。新しいウィンドウまたはタブが開きます。
構成を展開し、左側のナビゲーションでサイトの認証ノードをします。
[編集] をクリックします
"allowedExternalRedirectUrls" 要素を探します。 null または値の配列に設定できます。値を次の値に変更します。
```
"allowedExternalRedirectUrls": [
    "http://localhost:3000",
    "https://localhost:3000"
],
```
URL をサービスの URL に置き換えます。たとえば、http://localhost:3000 (Node.js サンプルサービスの場合) や http://localhost:4400 (Ripple サービスの場合) などがあります。ただし、これらの URL は例です。例に記載されているサービスを含め、状況は異なる場合があります。
画面の右上隅にある [読み取り/書き込み] ボタンをクリックします。
緑色の [put] ボタンクリックします。

この時点で設定が保存されます。設定の保存が完了するまで、ブラウザーウィンドウを閉じないでください。また、次のループバック URL を App Service の CORS 設定に追加します。

Azure portal にログインします
[すべてのリソース選択するか、App Services してから、モバイルアプリの名前をクリックします。
[設定] ブレードが自動的に開きます。表示されない場合は、[すべての設定]クリックします。
[API] メニュー [CORS] をクリックします。
表示されたボックスに追加する URL を入力し、Enter キーを押します。
必要に応じて、さらに URL を入力します。
[保存クリックして設定を保存します。

新しい設定が有効にするには、約 10 ~ 15 秒かかります。

次の方法で共有

Azure Mobile Apps 用の Apache Cordova プラグインを使用する方法

サポートされているプラットフォーム

セットアップと前提条件

Ionic v2 アプリの設定

クライアント接続を作成する

テーブルの操作

テーブル参照のクエリを実行する

サーバー上のデータのフィルター処理

データのページング

並べ替えられたデータを返す

データの挿入

データの変更

データの削除

ユーザーの認証

プロバイダーによる認証 (サーバーフロー)

プロバイダーによる認証 (クライアントフロー)

認証されたユーザーに関する情報を取得する

外部リダイレクト URL 用に Mobile App Service を構成します。

その他のリソース

次の方法で共有

Azure Mobile Apps 用の Apache Cordova プラグインを使用する方法

サポートされているプラットフォーム

セットアップと前提条件

Ionic v2 アプリの設定

クライアント接続を作成する

テーブルの操作

テーブル参照のクエリを実行する

サーバー上のデータのフィルター処理

データのページング

並べ替えられたデータを返す

データの挿入

データの変更

データの削除

ユーザーの認証

プロバイダーによる認証 (サーバー フロー)

プロバイダーによる認証 (クライアント フロー)

ソーシャル認証の基本的な例

認証されたユーザーに関する情報を取得する

外部リダイレクト URL 用に Mobile App Service を構成します。

その他のリソース

プロバイダーによる認証 (サーバーフロー)

プロバイダーによる認証 (クライアントフロー)