データ集配設定の設計¶

本章では、システム構築前に行うべき設計作業、および設計の事前知識として必要となる仕様・用語について説明します。

Device Phantomの仕様理解¶

Device Phantomとは、CAPがデバイスの状態情報を管理するためのデータ構造です。
CAPが規定するデータフォーマットに従ったJSONドキュメントとしてキャッシュストアに保持されます。

以下の温度センサ(temperature)と湿度センサ(humidity)を例に説明します。

{
    "deviceId" : "ieMSI_1FH1ne",
    "attributes" : {
        "reported" : {
            "temperature" : 17.0,
            "humidity" : 48.6
        },
        "desired" : {
            "temperature" : 25.0
        },
        "delta" : {
            "temperature" : 25.0
        }
    },
    "metadata" : {
        "reported" : {
            "temperature" : {
                "timestamp" : 1501475759191
            },
            "humidity": {
                "timestamp" : 1501475759191
            }
        }
    },
    "lastUpdate" : 1501475759191,
    "version": 15
}

JSONドキュメント内の以下のプロパティ名はCAPの予約語です。

JSONドキュメントの各プロパティについて説明します。

プロパティ名		説明
deviceId		各デバイスに一意に割り振ったデバイスの識別子を設定してください。使用できる文字列は最大 100文字の英数字と記号 (.-)です。未指定の場合、デバイス送信時のHTTP、MQTTのトピックに指定したクライアントIDの値が設定されます
attributes		-
	reported	デバイスが送信するデバイスデータ(=センサの実測値)を設定してください。本フィールドは任意のスキーマのJSONオブジェクトが設定できます。オブジェクトはネスト構造が可能で、ネストの深さは5階層まで利用いただけます
	desired	運用者や管理アプリがデバイスに送信する期待値を設定してください。本プロパティに設定されたJSONで、attributes.reportedに設定されたJSONのスキーマ (プロパティ名・構造 )が一致しているものを対象に後述のdeltaが計算されます。
	delta	reportedデータと desiredデータに差分時に用いられるデータです。 deltaは attributes.reportedやattributes.desiredのデータ受信時に自動で計算されます。deltaが作成・更新されると、デバイスにdeltaが通知されます。なお、デバイスへの通知の負荷軽減のため、再計算されたdeltaが前回送信時のdelta値と同じ場合、 deltaは送信されません。
metadata		-
	reported	reportedデータのメタ情報を設定してください。デバイスやアプリケーションは本フィールドに管理用の任意の情報をメタ情報に設定することができます。メタ情報は、CAPが設定する属性の最終更新時刻を格納するtimestampフィールドを含みます。timestampはCAPにより自動的に更新され、デバイスやアプリケーションから更新できません。時刻の形式はunix-timeで精度はミリ秒です。CAPが動作するホストマシンで取得した時刻が使用されます。
	desired	desiredデータのメタ情報を設定してください。デバイスやアプリケーションは本フィールドに管理用の任意の情報を設定することができます。
	delta	reportedデータとdesiredデータの差分(deltaデータ)のメタ情報を設定してください。デバイス、アプリケーションは本フィールドに管理用の任意の情報を設定することができます。
lastUpdate		Device Phantomの最終更新時刻が格納されるプロパティです。この属性は CAPにより自動的に更新され、デバイスやアプリケーションからは更新できません。時刻の形式はunix-timeで精度はミリ秒です。CAPが動作するホストマシンから取得した時刻が使用されます。
version		Device Phantomのバージョンを示すlong型のプロパティです。送信データにversionが指定されていない場合、Device Phantomの初回作成時に0が設定され、以降はDevice Phantomが更新される度にversionフィールドの値がインクリメントされます。デバイスやアプリケーションが古いバージョン番号を指定してDevice Phantomを更新しようとした場合、その操作は失敗します。 CAPはメッセージの順序保証をしないため、古いデータでの上書きを防止したい場合は本versionフィールドを利用してください。本フィールドは任意属性のため、 Device Phantomのバージョンによらず、クライアントからDevice Phantomを更新したい場合は、本フィールドを省略して送信します。versionの値にはエポックミリ秒を推奨します。

デバイスタイプの設計¶

本節ではデバイスタイプの設計について説明します。デバイスタイプの説明は「運用ガイド(概要編)」を参照ください。

デバイスタイプの設計は、システムの全体の構成、システムの目的に合わせて行います。デバイスタイプは以下の2つの観点で設計を行います。

Cache型もしくはパススルー型の選択
デバイスから受信するデバイスデータの型の登録

Cache型・パススルー型の選択¶

「利用ガイド(概要編)」の「デバイスタイプ」の説明を参照し、Cache型・パススルー型のどちらを利用するか決定してください。

デバイス検索のための設計 (Cache型デバイスタイプのみ)¶

Cache型デバイスタイプを選択した場合、デバイスの検索機能を利用できます。デバイス検索機能はAPI実行時に指定したCache型デバイスタイプのキャッシュストアを対象に実行されます。デバイスの種類ごとにデバイスデータの送信先のデバイスタイプを分けることで、事前に検索範囲を限定し、運用対象を絞りこむことができます。

検索機能を利用する場合はデバイスタイプの登録の際に、検索時にクエリに指定するプロパティの型の情報の設定が必要になります。検索機能を利用しない場合は型情報の設定は不要です。

CAPのクエリ検索はSQLライクな構文を用いて実行します。 SQL文のtable指定に該当する箇所にはデバイスタイプを指定し、クエリはデバイスタイプを対象に検索を実行されます。

デバイスから送信されるJSON形式のデータのプロパティには、以下の４つの型が指定できます。

整数値 (LONG)
小数値 (DOUBLE)
文字列 (STRING)
真偽値 (BOOLEAN)

デバイスタイプの登録方法については「運用ガイド(導入編)」をご参照ください。

送信データのJSONのスキーマの設計¶

CAPのサービス連携機能は送信処理前にJSONスキーマの変換を行うことができます。連携先サービスに送信後のデータの利用方法を検討し、送信データのスキーマを設計します。

送信データは、サービス運用画面から設定することで、期待したフォーマットに変換することができます。