6.1. ICE Backend API¶

6.1.1. はじめに¶

6.1.1.1. 表記について¶

環境によって値の異なるものについて、本文中で以下のように表記します。

{バージョン}

Backend APIのメジャーバージョンの値です。（例：バージョン1.0の場合は「1」）

6.1.1.2. 用語定義¶

本章で使用する用語について以下のように定義します。

オブジェクト

エッジ上の管理対象物（コンテキスト、プロセッサ、トポロジ、エッジアプリケーション、デバイスアダプタ、デバイス）のこと
オペレーション

エッジアプリケーションやデバイスに対して指示・通知メッセージを送信すること
メタデータ

エッジやオブジェクト、オペレーション、ファイルなどを管理するための情報を記述したデータ
イベントデータ

デバイスやエッジアプリケーションから発生する様々なデータ

6.1.2. 機能概要¶

エッジの運用管理やファイルアップロード、エッジから送信されたデータにアクセスするためのREST APIを提供します。

Backend APIの主な機能を以下に列挙します。

ファイルアップロード

エッジ向けに配信するファイルをバックエンドにアップロードします。
オペレーション実行

エッジアプリケーションやデバイスなどのオブジェクトに対して指示・通知メッセージを送信します。オブジェクト側でオペレーションメッセージ受信時の挙動を実装する必要があります。
メタデータ管理

エッジやオブジェクト、アップロードしたファイル、実行したオペレーションのメタデータを管理します。
イベントデータ管理

デバイスやエッジアプリケーションが送信したイベントデータを管理します。

Backend APIは以下のインタフェースを備えます。

Entity Abstraction I/F

エッジやオブジェクトのメタデータ参照やオペレーション実行を行うインタフェースです。エッジやオブジェクトは、それぞれedge_id、object_idというユニークなIDによって識別します。API実行時には、これらのIDを指定することで特定のエッジ・オブジェクトのメタデータ参照やオペレーション実行が可能です。
Data Access I/F

エッジから送信されたイベントデータを参照するためのインタフェースです。イベントデータはdata_typeによってデータ種別を識別します。
Operation Management I/F

エッジに対して実行したオペレーションのメタデータや実行結果を参照するためのインタフェースです。オペレーション情報や実行結果はop_idというオペレーションに紐づいたユニークなIDによって識別します。
File Management I/F

ファイルのアップロードや、アップロード済みのファイル管理を行うためのインタフェースです。ファイルはfile_idというユニークなIDによって識別します。
Management Application I/F

管理アプリケーションに対するオペレーション実行やオペレーションの実行結果参照、管理アプリケーションが送信したイベントデータ参照を行うインタフェースです。

Backend APIの動作について、以下の図を用いて説明します。 Backend API自身の機能は①～④の範囲です。

①エッジの運用管理、データ取得など、RESTクライアントからの要求を受け付けます。
②エッジから送信されたデータやオペレーション情報の取得・削除など、DBへのクエリを実行します。
③エッジへのファイル配信のために、ファイルサーバにファイルをアップロードします。
④エッジの運用管理のために、MQTT Brokerにメッセージを送信します。
⑤Backend APIが送信したメッセージをICE CoreがMQTT Brokerから受け取ります。
⑥デバイスやエッジアプリケーションから発生するデータをICE CoreがMQTT Brokerに送信します。
⑦エッジから送られてくるデータをバックエンド側のMessage Router受け取ります。
⑧適切なコレクションを判断し、データをDBに格納します。

6.1.3. エッジの管理¶

エッジやオブジェクトの管理は、Entity Abstraction I/Fにより行います。エッジの起動時に各管理対象のメタデータがバックエンドに送信され、Entity Abstraction I/Fの GETメソッドにより参照可能となります。オブジェクトへのオペレーションを実行する場合、PUTメソッドを使用します。オペレーションタイプはop_typeパラメータで指定します。groupパラメータを使用することで、あるグループに含まれる複数のエッジに対して一斉にオペレーションを実行することができます。エッジがどのグループに含まれるかは、ICE Coreのプロファイルにて設定可能です。リクエストボディに、送信するメッセージの内容を記載します。リクエストボディのサイズ上限は100KBです。実行されたオペレーションのメタデータや、オペレーションの実行結果は、Operation Management I/Fから参照できます。オペレーションを受け取るオブジェクト側の実装でオペレーション実行結果を返却している場合のみ、オペレーション実行結果を参照可能となります。

Entity Abstraction I/Fの管理対象一覧を以下に示します。（管理アプリケーションはManagement Application I/Fで扱います。）

管理対象	サポートするオペレーションタイプ	説明
エッジ	―	ICE Core本体です。
コンテキスト	―	ICE Coreのコンテキストです。
プロセッサ	―	ICE Coreのプロセッサです。
トポロジ	―	ICE Coreのトポロジです。
エッジアプリケーション	message, download	エッジ上で動作するエッジアプリケーションです。
デバイスアダプタ	message	エッジ上で動作するデバイスアダプタです。
デバイス	message	デバイスアダプタに紐づけられたデバイスです。
LwM2Mデバイス	listObservers, cleanObservers, discover, create, delete, read, write, execute, writeAttributes, observe, cancelObserver	エッジ上で動作するLwM2Mデバイスです。

エッジのメタデータは下記のようなフォーマットでDBに格納されます。 edge_idがユニークキーになります。

{
    "_id": "{ID}",    //データベースが自動で付与するID
    "edge_id": "{Edge ID}",    //エッジID
    "flow_id": "{Flow ID}",    //フローID
    "type": "edge_register",    //メッセージのタイプ(内部処理に使用)
    "marked": false,    //既読フラグ
    "updated_at": "2016-12-02T12:27:34.126Z",    //データを挿入・更新した日時
    "payload": { JSONオブジェクト }    //ICE Coreのプロファイル
}

オブジェクトのメタデータは下記のようなフォーマットでDBに格納されます。 app_typeはエッジアプリケーションのみのフィールドです。管理アプリケーションの場合を除き、値は”ua”となります。 {edge_id, object_id, object_type}がユニークキーになります。

{
    "_id": "{ID}",    //データベースが自動で付与するID
    "edge_id": "{Edge ID}",    //エッジID
    "flow_id": "{Flow ID}",    //フローID
    "type": "object_register",    //メッセージのタイプ(内部処理に使用)
    "object_id": "{Object ID}",    //オブジェクトID
    "object_type": "{Object Type}",    //オブジェクト種別(device、edge_applicationなど)
    "app_type": "ua",    //アプリケーション種別
    "marked": false,    //既読フラグ
    "updated_at": "2016-12-02T12:27:34.126Z",    //データを挿入・更新した日時
    "payload": { JSONオブジェクト }    //オブジェクトのプロファイル
}

6.1.3.1. オペレーション種別¶

オペレーション実行時に指定するオペレーション種別(op_type)について説明します。

message

任意のJSONメッセージをオブジェクトに送信します。リクエストボディの内容がそのままオブジェクトに渡されます。
download

ファイル配信を行う場合に使用します。エッジアプリケーションへのオペレーションとして実行します。

downloadは旧互換のための機能であり、messageを使用してダウンロード処理を実装することを推奨します。

以下のフォーマットでJSONメッセージをリクエストボディに指定します。
```
{
    "url": "{Url}",    //ファイルのダウンロードURL
    "condition": {    //エッジアプリケーションに渡すプロパティ(エッジアプリケーションの実装内で任意に使用)
    }
}
```
listObservers

LwM2MのlistObserversオペレーションを実行します。リクエストボディは使用しません。
cleanObservers

LwM2MのcleanObserversオペレーションを実行します。リクエストボディは使用しません。
discover

LwM2Mのdiscoverオペレーションを実行します。

以下のフォーマットでJSONメッセージをリクエストボディに指定します。Objectの発見を行う場合はlwm2m.object_idのみを指定し、Resourceの発見を行う場合はlwm2m.object_idとlwm2m.object_instance_idの両方を指定します。
```
{
    "lwm2m": {
        "object_id": "{Object ID}",    //LwM2MのObject IDを指定
        "object_instance_id": "{Object Instance ID}"    //LwM2MのObject Instance IDを指定
    }
}
```

create

LwM2Mのcreateオペレーションを実行します。