同期フレームワークは、クライアントアプリと Node.js クラウドアプリ API のセットで構成されます。

クライアントアプリは、バックエンドデータに直接アクセスしません。代わりに、同期クライアント API を使用して、デバイスに格納されたデータの読み取りと一覧表示を行い、変更 (作成、更新、および削除) をクラウドアプリに送信します。データにローカルで行われた変更は、クラウドアプリに送信される前にローカルの同期データキャッシュに格納されます。クライアントアプリは、同期クライアント API からリモートデータセットへの変更の通知を受け取ります。

クライアントアプリはクライアント同期サービスを使用して、リモートデータセットに行われた変更 (デルタ) をクラウドアプリから受け取り、同期データキャッシュに格納します。また、クライアントアプリはクライアント同期サービスを使用してローカルで行われた更新をクラウドアプリに送信します。クライアントアプリがオフラインのときは、キャッシュされた更新がデバイス上のローカルストレージにフラッシュされ、ネットワーク接続が再確立される前にクライアントアプリが閉じられる場合に変更を永続化できます。変更は、クライアントアプリが次回オフラインになったときにクラウドアプリにプッシュされます。

クラウドアプリはバックエンドデータに直接アクセスせず、同期クラウド API を介してのみアクセスします。クラウドアプリは、クライアント同期サービスを使用してクライアントアプリからアップデートを受け取るために同期クラウド API を使用します。これらのアップデートはクラウドアプリ同期データキャッシュに格納されます。クラウドアプリは、標準的な CRUDL (create, read, update, delete and list) および collisionHandler 関数を使用して、ホストされたストレージでバックエンドデータを管理するために同期クラウド API を使用します。

標準的なデータハンドラー関数以外に、クラウドアプリにはユーザー定義データアクセス関数も使用できます。

同期用のクライアントおよび Node.js API 呼び出しは、以下のガイドで文書化されています。

アプリで同期フレームワークを使用するには、以下の手順を実行します。

同期フレームワークは、アプリ開発者がデータセットのソースデータを定義することを可能にするフックを提供します。通常、ソースデータは外部のデータベース (MySql、Oracle、MongoDB など) ですが、これは要件ではありません。データセットのソースデータはどんな種類でもかまいません (csv ファイル、FTP メタデータ、複数のデータベーステーブルから取得されたデータなど)。同期フレームワークの唯一の要件は、ソースデータの各レコードが一意の ID を持ち、データが同期フレームワークに JSON オブジェクトとして提供されることです。

バックエンドデータソースと同期するために、アプリ開発者は同期のコードを実装できます。

たとえば、データベースからデータをロードする代わりにバックエンドからデータをリストするときに、ハードコーディングされたデータを返すことができます。

興味がある場合は、同期フレームワークを理解するのに役に立つ以下の情報をお読みください。

{
  record_uid_1 : {<JSON Object of data>},
  record_uid_2 : {<JSON Object of data>},
  record_uid_3 : {<JSON Object of data>},
  ...
}

同期クライアントと同期サーバー間の通信用プロトコル。
詳細については、同期プロトコルを参照してください。

同期サーバーは、同期プロトコルのサーバー部分であり、fh-mbaas-api モジュールに含まれます。以下のことを行います。

同期クライアントは、同期プロトコルのクライアント部分です。3 つの同期クライアント実装があります。

同期クライアント:

同期サーバーループは、同期サーバーで継続的に実行される機能です (各実行の間に 500ms の待機が発生)。
各実行中は、すべてのデータセットクライアントに対して反復処理が行われ、データセットをデータセットバックエンドから同期する必要があるかどうかを確認できます。

同期クライアントループは、同期クライアントで継続的に実行される機能です (各実行の間に 500ms の待機が発生)。
各実行中は、すべてのデータセットクライアントに対して反復処理が行われ、データセットを同期サーバーと同期する必要があるかどうかを確認できます。

同期クライアントでは、これは特定のデータセット用の同期サーバーからのアップデートをチェックする間隔です。
同期サーバーでは、これは特定のデータセット用データセットバックエンドからのアップデートをチェックする間隔です。

詳細については、同期周期の設定を参照してください。

データセットは、1 つ以上の同期クライアント、同期サーバー、および データセットバックエンド間で同期されるレコードのコレクションです。

同期クライアントと同期サーバー間で同期されたデータ用レコードのシステム。
API を提供する任意のシステムであり、同期サーバーから mysql データベースや SOAP サービスなどと統合できます。
同期サーバーは、データセットバックエンドと統合するためにデータセットハンドラーを使用して同期サーバー API を公開します。

データセットハンドラーは、同期サーバーをデータセットバックエンドに統合する機能です。
データセットに対して CRUDL アクションを実行したり、データセットレコード間で競合を管理したりする多くのハンドラーがあります。
これらのハンドラーのデフォルトの実装では fh.db (RHMAP MBaaS で支援される MongoDB) を使用します。
これらの各ハンドラーはオーバーライドできます。詳細については、Sync Server API を参照してください。

重要: ハンドラーをオーバーライドする場合、Red Hat は、デフォルトの実装を使用している一部のハンドラーとオーバーライドされた実装を使用している他のハンドラーでの異常な動作を回避するために、すべてのハンドラーをオーバーライドすることをお勧めします。

データセットクライアントは、クライアントとサーバー間で積極的に同期されている各データセットに対する同期クライアントと同期サーバーに格納された設定です。
以下のようなデータが含まれます。

データセットレコードはデータセット内の個別レコードです。
以下のものが含まれます。

同期プロトコルで使用されるハッシュには 2 つの種類があります。

同期サーバーアーキテクチャーに含まれるもの: * HTTP ハンドラー * キューおよびプロセッサー * 同期スケジューラー

これらの各コンポーネントによりデータは MongoDB で永続化されます。˙

同期周期は、システムが 2 つの同期プロセスの間に待機する期間です。

重要: クライアントとサーバーで別々に周期を設定できます。ただし、Red Hat は以下のシナリオを回避するために同じ設定を使用することをお勧めします。

サーバーの同期周期の値により、同期プロセッサーが実行される頻度が決定されます。同期プロセッサーが実行されるたびに、データセットバックエンドに対してリスト操作が実行され、データとローカルコピーが同期されます。使用しているアプリケーション向けの同期周期の最適な値を決定するために、以下のセクションをお読みください。

同期周期値を使用して、サーバーがバックエンドに生成する要求の数を制御できます。この値は、バックエンドが負荷を処理でき、サーバー自体が過負荷の状態でない限り、0ms に設定できます。

同期アーキテクチャーで説明されているように、同期データを格納するために使用するさまざまなキューがあります。データを処理するために、各キューに対応するワーカーが作成されます。この唯一のタスクは、キューからジョブを一度に 1 つずつ取得し、処理することです。ただし、あるジョブを完了してから利用可能な次のジョブを取得するまでの時間を表す間隔値があります。この値は、ワーカーのパフォーマンスを最大化するために設定できます。

本項では以下のことを行う開発者を対象とします。

fh-mbaas-api@>=7.0.0 をすでに使用している場合は、本項のどの手順も実行しないでください。

7.0.0 より前は、同期サーバーが fh.db API を使用して同期操作データを MongoDB に格納していました。fh.db は、中間 http API (fh-ditch) を介することがある MongoDB のラッパーです。この結果、同期操作データに対して実行できるアクションは制限されます。また、MongoDB に直接接続されるモジュールの使用も制限されます。fh-mbaas-api@7.0.0 では、同期サーバーで MongoDB への直接接続が必要です。

条件は以下のとおりです。

同期データハンドラー向けのメソッド署名は、新しい同期フレームワークでは異なります。データハンドラーを実装した場合は、パラメーターの順序を変更する必要があります。これらの変更は、javascript のパラメーター順序規則 (つまり、コールバックが最後のパラメーター) に準拠します。

重要 パラメーターとして各ハンドラーに渡されたコールバック関数が各呼び出しに対して実行されるようにします。これにより、ハンドラーの完了後もワーカーを維持できます。

7.0.0 よりも前のバージョンとそのバージョンのデータハンドラーおよび署名は以下のとおりです。

// <7.0.0
sync.handleList(dataset_id, function(dataset_id, params, callback, meta_data) {});
sync.globalHandleList(function(dataset_id, params, callback, meta_data) {});
// >=7.0.0
sync.handleList(dataset_id, function(dataset_id, params, meta_data, callback) {});
sync.globalHandleList(function(dataset_id, params, meta_data, callback) {});


// <7.0.0
sync.handleCreate(dataset_id, function(dataset_id, data, callback, meta_data) {});
sync.globalHandleCreate(function(dataset_id, data, callback, meta_data) {});
// >=7.0.0
sync.handleCreate(dataset_id, function(dataset_id, data, meta_data, callback) {});
sync.globalHandleCreate(function(dataset_id, data, meta_data, callback) {});


// <7.0.0
sync.handleRead(dataset_id, function(dataset_id, uid, callback, meta_data) {});
sync.globalHandleRead(function(dataset_id, uid, callback, meta_data) {});
// >=7.0.0
sync.handleRead(dataset_id, function(dataset_id, uid, meta_data, callback) {});
sync.globalHandleRead(function(dataset_id, uid, meta_data, callback) {});


// <7.0.0
sync.handleUpdate(dataset_id, function(dataset_id, uid, data, callback, meta_data) {});
sync.globalHandleUpdate(function(dataset_id, uid, data, callback, meta_data) {});
// >=7.0.0
sync.handleUpdate(dataset_id, function(dataset_id, uid, data, meta_data, callback) {});
sync.globalHandleUpdate(function(dataset_id, uid, data, meta_data, callback) {});


// <7.0.0
sync.handleDelete(dataset_id, function(dataset_id, uid, callback, meta_data) {});
sync.globalHandleDelete(function(dataset_id, uid, callback, meta_data) {});
// >=7.0.0
sync.handleDelete(dataset_id, function(dataset_id, uid, meta_data, callback) {});
sync.globalHandleDelete(function(dataset_id, uid, meta_data, callback) {});


// <7.0.0
sync.listCollisions(dataset_id, function(dataset_id, callback, meta_data) {});
sync.globalListCollisions(function(dataset_id, callback, meta_data) {});
// >=7.0.0
sync.listCollisions(dataset_id, function(dataset_id, meta_data, callback) {});
sync.globalListCollisions(function(dataset_id, meta_data, callback) {});


// <7.0.0
sync.removeCollision(dataset_id, function(dataset_id, collision_hash, callback, meta_data) {});
sync.globalRemoveCollision(function(dataset_id, collision_hash, callback, meta_data) {});
// >=7.0.0
sync.removeCollision(dataset_id, function(dataset_id, collision_hash, meta_data, callback) {});
sync.globalRemoveCollision(function(dataset_id, collision_hash, meta_data, callback) {});

同期サーバーが MongoDB に直接接続するようになったため、起動時にセットアップ時間が必要です。sync.init() を現在使用している場合は、これらの呼び出しを sync:ready イベントハンドラーでラップします。たとえば、以下のコードを使用する場合は、

fh.sync.init('mydataset', options, callback);

イベントハンドラーに配置するよう変更します。

fh.events.on('sync:ready', function syncReady() {
  sync.init('mydataset', options, callback);
});

または、同期 API からイベントエミッターを使用できます。

fh.sync.getEventEmitter().on('sync:ready', function syncReady() {
  sync.init('mydataset', options, callback);
});
[source,json]

fh.sync.init() に渡された logLevel オプションは利用できなくなりました。デフォルトでは、新しい同期サーバーは何もログに記録しません。すべてのロギングでは [debug](https://www.npmjs.com/package/debug) モジュールが使用されます。同期サーバーからの出力をログに記録する場合は、以下のように DEBUG 環境変数を設定できます。

DEBUG=fh-mbaas-api:sync

SDK 全体からすべてのログを参照する場合は、以下のように設定します。

DEBUG=fh-mbaas-api:*

debug モジュールの他のすべての環境変数と動作機能が利用可能です。

同期サーバーはスケーラブルとして設計されています。

本項では、同期サーバーのパフォーマンスとスケーリングのオプションについて説明します。

同期サーバーのパフォーマンスを検査するには 2 つのオプションがあります。

同期サーバーのパフォーマンスを理解するために確認する必要がある主要なメトリクスは以下のとおりです。

同期サーバーをスケールする場合は、以下のことを検討します。

同期サーバーは、実行中にさまざまなコレクションを MongoDB に保持します。

本書では、同期サーバーが作成するコレクションとその目的について説明します。

同期サーバーにより作成されたすべてのコレクションには接頭辞 fhsync が付けられます。

各キューコレクションに対して、ドキュメントは処理後すぐに削除されません。代わりに、ドキュメントは deleted と示されます。これにより、開発者はドキュメントを監査ログとして使用し、デバッグに役立てたりすることができるようになります。

これらのキューが容量を使用しすぎないようにするために、これらのメッセージには TTL (time to live) を設定できます。TTL 値に到達すると、これらのメッセージはデータベースから削除されます。

詳細については、$fh.sync.setConfig の「queueMessagesTTL」オプションを参照してください。

この問題のデバッグを容易に行うために、以下の質問に回答してください。

クライアントはサーバーに変更を送信しましたか?

クライアントが変更を行った後に同期要求の要求本文を確認して変更が送信されたかどうかを調べます。変更は pending アレイにある必要があります。以下に例を示します。

{
  "fn":"sync",
  "dataset_id":"myShoppingList",
  /*...*/
  "pending":[{
    "inFlight":true,
    "action":"update",
    "post":{
      "name":"Modified Name",
      "created":1495123790928
    },
    "postHash":"2e90b858164184b9ff31e0937cef8ddf4a959ac5",
    "timestamp":1495799747404,
    "uid":"591dc768a95300322eee1d1f",
    "pre":{
      "name":"Original Name",
      "created":1495123790928
    },
    "preHash":"421932b23f05f8aef528d73fff3cbf5aa00786a4",
    "hash":"f98f595974f7e7e1f07aed6220fab04446f459c9",
    "inFlightDate":1495799747850
  }]
}

変更が保留中のアレイにない場合は、デバイスがオンラインであることを検証します。クライアントアプリにエラーがないか確認し、該当する同期アクションを呼び出していることを検証します (たとえば、更新の場合は sync.doUpdate())。クライアントアプリで、変更を行うコードの周辺でデバッグしたり、ロギングを追加したりすると役に立ちます。

この変更のレコードが fhsync_pending_queue コレクションにありますか?

「いいえ」の場合は、サーバーが変更を受け取っていないか、受け取るときにエラーが発生しました。

レコードが fhsync_pending_queue コレクションに存在したが、レコードに対するキューの Time To Live (TTL) 期間が経過したため、レコードが削除された可能性があります。これに該当する場合は、TTL を増やすと、デバッグが有効になります。

レコードの deleted フィールドにタイムスタンプがありますか?

「いいえ」の場合は、そのアイテムがまだ処理されていません。

この更新のレコードが fhsync_pending_queue コレクションにありますか?

「いいえ」の場合は、更新の処理中にエラーが発生した可能性があります。

レコードの type フィールドが failed または collision に設定されていますか?

「はい」の場合は、更新をデータセットバックエンドに適用できない可能性があります。

「いいえ」であり、タイプが applied の場合は、作成または更新ハンドラーをデバッグして、なぜそのハンドラーで変更がデータセットバックエンドに適用されたと見なされたのかを確認する必要があります。

type フィールドは、collision、failed、または applied のいずれかである必要があります。

変更がデータセットバックエンドからクライアントに同期されるまでに十分な時間が経過しましたか?

変更がデータセットバックエンドに適用され、他のクライアントがその変更を取得する前に、以下の 2 つのことが起こる必要があります。

十分な時間が経過したら、データセットバックエンドとの同期中のエラーをサーバーログで確認してください。

データセット向けの fhsync_queue コレクションに最近のレコードがありますか?

「いいえ」の場合は、レコードの TTL 値が経過し、レコードが削除された可能性があります。この場合は、TTL 値を増やしてさらにデバッグすることができます。

別の可能性としては、同期スケジューラーでそのデータセットの同期がスケジュールされなかったことが挙げられます。この理由としては、そのデータセットに対して現在アクティブなクライアントがなく、そのデータセットに対してクライアントが最後にアクティブであったときから clientSyncTimeout が経過したことが考えられます。

レコードの deleted フィールドにタイムスタンプがありますか?

「いいえ」の場合は、同期がまだ処理されていないことを意味します。

fhsync_<datasetid>_records キャッシュ内のレコードは最新ですか?

リストハンドラーが呼び出され、結果がレコードキャッシュに追加されている必要があります。レコードキャッシュが更新されたことを検証するには、更新されたレコードの fhsync_<datasetid>_records コレクションを確認します。このレコード内のデータはデータセットバックエンドのデータに一致する必要があります。一致しない場合は、サーバーログでリストハンドラーのエラーと動作を確認します。リストハンドラーにロギングを追加すると役に立つことがあります。

クライアント同期呼び出しが正常に実行されましたか?

クライアントが同期呼び出しを行う場合に、サーバーからの有効な応答があることを確認します。呼び出しが正常に行われた場合は、クライアントが更新済みレコードを取得していることを検証します。サーバーキャッシュに更新済みレコードが含まれるのにクライアントが更新済みレコードを受け取らない場合は、クエリーパラメーターとサーバーに送信されたメタデータが正しいことを確認します。デバッグログを有効にすると、正しくないデータがどのようにクライアントに送信されたのかを簡単に調べることができる場合があります。

デバッグのために同期ログを有効にするには、サーバーで以下の環境変数を設定します。

DEBUG=fh-mbaas-api:sync

この処理により、大量のログが生成されます。各ログエントリーには、そのログメッセージのコンテキストでアクションを実行する特定のデータセット ID がタグ付けされます (可能な場合)。これらのログは理解しにくいことがありますが、クライアントからの更新とそれらの更新のさまざまな段階を追跡できます。成功したシナリオのログと不成功のシナリオのログを比較し、障害が発生した段階を特定すると役に立つことがあります。

この問題の原因は、(特にエッジケースに関連する) カスタムハンドラー実装にあることが考えられます。カスタムハンドラーにログを追加すると役に立つことがあります。

データセットバックエンド接続の問題 (特に断続的な問題) はデバッグおよび特定が困難なことがあります。データセットバックエンドを外部的に監視または確認すると、役に立つことがあります。