ステートの登録と取得

Thing の状態を表す値をステートとして Thing Interaction Framework に登録できます。

最新のステートはモバイルアプリから参照できます。これにより、Thing の持つセンサー値や設定値を様々な形で利用できます。

また過去に保存したステートは、REST API や開発者ポータルより履歴として取得・閲覧できます。

実装方法や利用方法の詳細はこちら（Android、iOS、JavaScript、Thing、REST API、開発者ポータル）をご覧ください。

全体的なフロー

ステートの登録・取得の全体的なフローを以下にまとめます。

1. ステートの登録

Thing からステートをアップロードできます。アップロードは、Thing 側の SDK によって以下のタイミングで実行されるように制御されています。

• 一定間隔での自動的なアップロード

• モバイルアプリからの コマンド を処理し終わったタイミングでのアップロード

ゲートウェイ のエンドノードから登録する場合は、コンバーターから任意のタイミングで登録できます。

2. ステートの保存

Thing Interaction Framework は、登録されたステートを保存します。過去に登録されたステートは履歴として管理されます。

ステートを条件としたトリガーが設定されている場合は、このタイミングでトリガーの条件がチェックされます。トリガーの詳細は トリガーによる自動実行 をご覧ください。

3. ステートの取得要求

最新ステートやステート履歴が取得できます。取得方法は、モバイルアプリからの取得と開発者ポータルからの取得の 2 通りがあります。

ステートのデータ形式 の例にあるようにステートは JSON 形式で取り扱われますが、モバイルアプリ側の SDK を利用するとプラットフォームに適した方式（リフレクションによる値の埋め込みや Dictionary での参照など）でステートを取得できます。取得した値を元に、モバイルアプリで視覚的にわかりやすく表示することができます。

ステート履歴の取得は、過去のステートをそのまま取得する以外に、履歴を集計した結果を取得することもできます。ステート履歴の詳細は ステート履歴の管理 をご覧ください。

ステートのデータ形式

ステートは JSON 形式でアップロードされます。

たとえば、エアコンから現在の部屋の温度と湿度をステートとして登録する場合は、次のような形式のデータが Thing Interaction Framework にアップロードされます。

{
  "currentTemperature": 28,
  "currentHumidity": 70
}

ステートで表現するデータの形式は自由に決めることができますが、スキーマによってデータ形式を定めておく必要があります。詳細は スキーマ をご覧ください。

ステートとして入れ子（ネスト）構造になっているデータを使うこともできます。この場合、以下の制限が適用されます。

• ステート履歴集計時に フィールド条件 として指定できるのは、ステートのトップレベルのフィールドのみです。
• トリガー実行条件の ステート条件 として指定できるのは、ステートのトップレベルのフィールドのみです。

ステート履歴の管理

Thing Interaction Framework に登録されたステートは、履歴として管理されます。ステート履歴は以下の様式で管理されます。

履歴の不変性

一度保存されたステート履歴は変更・削除できません。

タイムスタンプの付与

登録されたステートは、タイムスタンプが付与された形で保存されます。後ほどステート履歴の検索・閲覧を行う際に、このタイムスタンプを利用します。

タイムスタンプは、基本的に Thing Interaction Framework が自動的に付与します。このため、Thing 側ではタイムスタンプを意識せずにステートの登録を行えます。

Thing 側で明示的にタイムスタンプを付与することもできます。これは、Thing 側でステートをいったん蓄積し、後ほど一括登録するケースなどにおいて便利な機能です。この場合、Thing 側で設定するタイムスタンプと実際にステートが登録された時間との差は、後述するグループ化の間隔により定められる時間内に納まる必要があります。一例として、ステート履歴を 15 分間隔でグループ化する場合、許容されるタイムスタンプの最大時間差は 6 時間となります。

グループ化とサンプリング

登録されたステートは 初期登録時 に指定した間隔でグループ化され保存されます。この際、指定した間隔により決定される密度でサンプリングされます。

指定可能なグループ化の間隔と、これに伴い適用されるステートのサンプリング密度および許容されるタイムスタンプと実登録時間との最大差は次のとおりです。

グループ化の間隔とサンプリング密度の概念を示す例として、グループ化の間隔を「15 分」とした場合の様子を以下に図示します。

• 黄色の枠は 15 分間隔で設定されたグループを示しています。グループは、UNIX エポック（協定世界時での 1970 年 1 月 1 日 0 時 0 分 0 秒）を起点に、15 分間隔で設置されます。

• 適用されるサンプリング密度は「30 秒ごとに 1 ステート」なので、1 つのグループは、概念的に 30 秒間隔のスロット 30 個に区切られます。

• 各スロットにつき 1 つのステートが保存できます。

1 つのスロットに複数のステート登録が行われた場合は、最新のものが保存されます。グループ化間隔が「15 分」のケースを例に取ると、1 つのスロットのサンプリング対象である 30 秒の間に 2 つ以上のステートが登録された場合は、次の図のように最新のものがスロット内に保存され、それ以前のステート履歴は破棄されます。

なお、ステート履歴の管理は、ステートの種類によらず Thing ごとにひとまとめに管理される点に注意してください。

• Thing が複数種類のステートを登録する場合、これらは一切区別されることなくサンプリングされます。あるスロットに複数のステートを登録しようとした場合は、種類によらず最新のものが保存されます。

• Thing 側の SDK は、コマンド実行完了時と一定間隔での自動実行の 2 つのタイミングでステート更新（登録）を行います。これらは一切区別されることなくサンプリングされます。Thing のステートを一定間隔で観測するような場合は、履歴の不慮の消失を防ぐために、必要に応じてコマンド実行完了時に呼び出されるステートハンドラを無効化してください。

  詳細は ステートの更新 をご覧ください。

グループごとの集計

登録したステート履歴をグループごとに集計した値を取得できます。例えば、エアコンから部屋の温度と湿度をステートとして登録した場合、グループ単位でそれぞれの値の平均値や最大・最小値などを得ることができます。なお、現時点では 1 種類の集計値のみ取得可能です（近日中に複数集計値を同時取得をサポートする予定です）。

グループごとの集計は Thing Interaction Framework が行うため、アプリ開発者側でデータ加工などを行う必要がありません。

以下に実行例を示します。下記の例では、次のステートを持った状態で取得機能や集計機能を実行した場合を示しています。

• 例 1：時間範囲指定のみ（グループごと）

  ステートの時間範囲のみを、グループごとに取得できます。

  

• 例 2：時間範囲指定のみ（グループなし）

  ステートの時間範囲のみを、グループなしで取得できます。

  

• 例 3：時間範囲指定＋フィールド条件（集計なし）

  指定した時間範囲のうち、指定した条件（ここでは currentTemperature フィールドが 32 以上のもののみ）を満たすものだけを取得できます。

  

• 例 4：時間範囲指定＋フィールド条件（COUNT で集計あり）

  指定した時間範囲、かつ、指定した条件（ここでは currentTemperature フィールドが 32 以上のもののみ）を満たすステートについて、グループごとに指定フィールドが存在するステートの件数を集計できます。

  

• 例 5：時間範囲指定のみ（MIN で集計あり）

  指定した時間範囲のステートについて、グループごとに指定フィールドが最小のステートを取得できます。