Azure Mobile Apps 向け Apache Cordova クライアント ライブラリの使用方法

• Android
• Cordova
• JavaScript
• iOS
• マネージド (Windows/Xamarin)

概要

このガイドでは、最新の Azure Mobile Apps 向け Apache Cordova プラグインを使用して一般的なシナリオを実行する方法について説明します。 Azure Mobile Apps を初めて使用する場合は、まず、「 Apache Cordova アプリの作成 」を参照して、バックエンドの作成、テーブルの作成、構築済みの Apache Cordova プロジェクトのダウンロードを行ってください。 このガイドでは、クライアント側の Apache Cordova プラグインに重点を置いています。

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

この SDK は、iOS、Android、Windows の各デバイスで Apache Cordova v6.0.0 以降をサポートしています。 プラットフォームのサポートは次のとおりです。

• Android API 19 ～ 24 (KitKat から Nougat)
• iOS バージョン 8.0 以降
• Windows Phone 8.1
• ユニバーサル Windows プラットフォーム

セットアップと前提条件

このガイドでは、バックエンドとテーブルを作成済みであることを前提としています。 このガイドでは、テーブルのスキーマが、これらのチュートリアルのテーブルの場合と同じであることを前提とします。 さらに、Apache Cordova プラグインがコードに追加済みであることを前提とします。 まだこれらの操作を行っていない場合は、次のコマンド ラインで Apache Cordova プラグインをプロジェクトに追加します。

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 アプリと Ionic v2 アプリの両方をサポートしています。 Ionic v2 アプリの場合のみ、追加で WindowsAzure オブジェクトの宣言が必要です。

クライアント接続の作成

WindowsAzure.MobileServiceClient オブジェクトを作成して、クライアント接続を作成します。 appUrl を Mobile App の 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);

success 関数は results を指定して呼び出します。 success 関数で 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() メソッドを使用して、results オブジェクトに totalCount フィールドを追加します。 totalCount フィールドには、ページングを使用しない場合に返されるレコード数の合計が入力されます。

pages 変数といくつかの UI ボタンを使用して、ページ リストを指定できます。loadPage() を使用すると、ページごとに新しいレコードを読み込むことができます。 既に読み込まれているレコードへのアクセス時間を短縮するには、キャッシュを実装します。

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

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

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

クエリ オブジェクトの詳細については、[クエリ オブジェクトのドキュメント]を参照してください。

方法: データを挿入する

適切な日付を指定して 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 サーバー SDK では、開発用に動的なスキーマをサポートしています。 動的スキーマでは、挿入操作または更新操作で列を指定するだけで、テーブルに列を追加できます。 実稼働環境にアプリケーションを移行する前に、動的スキーマを無効にしておくことをお勧めします。

方法: データを変更する

.insert() メソッドの場合と同様に、update オブジェクトを作成して .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

サーバー フローとクライアント フローの 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" です。

注意

現在、サーバー フローでは Google 認証が正しく機能しません。 Google の認証には、クライアント フローを使用する必要があります。

この場合は、Azure App Service が OAuth 2.0 認証フローを管理します。 選択されたプロバイダーのサインイン ページを表示し、ID プロバイダーでのサインインが成功した後で App Service 認証トークンを生成します。 login 関数は、完了すると、userId フィールドのユーザー ID と authenticationToken フィールドの 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 で提供されるトークンが変数 token に格納されるとします。

方法: 認証されたユーザーに関する情報の取得

認証情報は、AJAX ライブラリによる HTTP 呼び出しを使用して /.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 からのブラウザーのダウンロードに使用できます。 jQuery または別の AJAX API を使用して情報を取得することも可能です。 データは JSON オブジェクトとして取得されます。

外部リダイレクト URL 用に Mobile App Service を構成する方法

いくつかの種類の Apache Cordova アプリケーションでは、ループバック機能を使用して OAuth UI フローを処理します。 既定では認証サービスで認識されるのはサービスの利用方法だけであるため、localhost 上の OAuth UI フローによって問題が発生します。 問題のある OAuth UI フローの例は次のとおりです。

• Ripple エミュレーター
• Ionic による Live Reload
• モバイル バックエンドのローカルでの実行
• 認証を提供するものとは別の Azure App Service でのモバイル バックエンドの実行

ローカル設定を構成に追加するには、以下の手順に従います。

1. Azure Portal

2. [すべてのリソース] または [App Services] を選択し、モバイル アプリの名前をクリックします。

3. [ツール]

4. [監視] メニューの [リソース エクスプローラー] をクリックし、 [実行] をクリックします。 新しいウィンドウまたはタブが開きます。

5. 左側のナビゲーションで、サイトの [config] ノード、 [authsettings] ノードの順に展開します。

6. [編集]

7. "allowedExternalRedirectUrls" 要素を探します。 この要素は、null または値の配列に設定できます。 値を次の値に変更します。

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

   URL をご使用のサービスの URL に置き換えます。 例には、https://localhost:3000 (Node.js サンプル サービス用)、または https://localhost:4400 (Ripple サービス用) が含まれています。 ただし、これらの URL は例にすぎません。例に示されているサービスの状況など、状況が異なる場合があります。

8. 画面の右上隅にある [読み取り/書き込み] ボタンをクリックします。

9. 緑色の [PUT] ボタンをクリックします。

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

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

新しい設定が有効になるまで約 10 ～ 15 秒かかります。

方法: プッシュ通知に登録する

プッシュ通知を処理するには、 phonegap-plugin-push をインストールします。 このプラグインは、コマンド ラインで cordova plugin add コマンドを使用するか、Visual Studio 内で Git プラグイン インストーラーを使用することで簡単に追加できます。 Apache Cordova アプリの次のコードによって、デバイスがプッシュ通知に登録されます。

var pushOptions = {
    android: {
        senderId: '<from-gcm-console>'
    },
    ios: {
        alert: true,
        badge: true,
        sound: true
    },
    windows: {
    }
};
pushHandler = PushNotification.init(pushOptions);

pushHandler.on('registration', function (data) {
    registrationId = data.registrationId;
    // For cross-platform, you can use the device plugin to determine the device
    // Best is to use device.platform
    var name = 'gcm'; // For android - default
    if (device.platform.toLowerCase() === 'ios')
        name = 'apns';
    if (device.platform.toLowerCase().substring(0, 3) === 'win')
        name = 'wns';
    client.push.register(name, registrationId);
});

pushHandler.on('notification', function (data) {
    // data is an object and is whatever is sent by the PNS - check the format
    // for your particular PNS
});

pushHandler.on('error', function (error) {
    // Handle errors
});

プッシュ通知は、Notification Hubs SDK を使用してサーバーから送信します。 プッシュ通知をクライアントから直接送信しないでください。 この操作は、Notification Hubs または PNS に対するサービス拒否攻撃のトリガーに使用される可能性があります。 このような攻撃が発生すると、PNS はトラフィックを禁止する可能性があります。

詳細情報

API の詳細については、API に関するドキュメントを参照してください。