概要
このセクションでは、SmartREST プロトコル、使用されるデータ形式、および SmartREST テンプレートの構造と登録について説明します。 組み込みメッセージとエラーについても説明します。
Things Cloud REST APIは、ほとんどの環境から簡単に使用できる汎用IoTプロトコルを提供します。これはどのようなIoTユースケースにもアドホックに適応させることができ、また標準的なインターネット通信およびセキュリティ メカニズムを利用します。適切な標準技術を利用しているため、独自IoTプロトコルと比べ先進的である一方、ローエンドのマイクロコントローラまたは低帯域幅通信チャネルなど、非常に制約の多い環境には課題をもたらすことがあります。
こうした環境向けに、Things Cloud はいわゆる「SmartREST」プロトコルを提供します。SmartRESTは以下のように、標準技術の利点と特別仕様のプロトコルの利点を同時に提供するものです。
- 標準HTTP技術の使用により、どのようなネットワークでもそのまま機能します。
- HTTPの認証と暗号化に対応します。
- プロトコルのバージョニングにも上手く対処します。
- ネットワークトラフィックの使用量は、通常の操作ではペイロードデータのみを転送することで、最適化されたプロトコルのものに近いです。
- CSV(コンマ区切り値)を基本としているので、Cベース環境からも容易に処理できます。
- 時計のないデバイス向けに、サーバーが生成するタイムスタンプに対応します。
次のセクションでは、SmartRESTの背景にある概念と、使用する基本プロトコルについて説明します。SmartRESTは後述の通り、テンプレートを使ってメタデータをペイロードデータから分離する処理を基本としています。最後に、SmartRESTを使用してデータを送受信する方法を説明します。
SmartRESTの動作方法
下記の画像は、SmartRESTの動作を図示したものです。デバイスおよび他のクライアントは Things Cloud 上の専用SmartRESTエンドポイントに接続し、それぞれのデータをコンマ区切り値からなる行として送信します。これらの行は Things Cloud のSmartRESTプロキシにより、標準の Things Cloud REST APIリクエストへと展開されます。同様に、Things Cloud からの応答は通常のJSON形式からプロキシによってコンマ区切り値に圧縮された後、デバイスに返却されます。
Things Cloud はコンマ区切り値をどのようにして意味のあるRESTリクエストとして解釈するのか?
まず、これを行うためにデバイスはテンプレートを Things Cloud に登録します。テンプレートは、展開されたRESTリクエスト形式をプレースホルダーと一緒に保持しており、その中へ Things Cloud の SmartREST プロキシが連続的にコンマ区切り値を挿入します。応答の場合、テンプレートはコンマ区切り値を構築するために、構造化されたREST応答からどの値を抽出するかを記述します。
テンプレートは、デバイスのソフトウェアまたはファームウェアのバージョンに関連付けられます。通常、デバイスまたはアプリケーションに固有な実装は、用途に応じたリクエストタイプに対応しており、決まった範囲の要求を発行します。同じ実装のデバイスはすべて、同じ一連のリクエストタイプを共有するのです。したがって、テンプレートは実装段階で定義できます。テンプレートを Things Cloud で使用できるようにするため、特定の実装を伴う最初のデバイスがそのテンプレートを送信し、すべての同様のデバイスで利用できるようにします。
以下の図は、このプロセスを表したものです。「Device_1.0」のバージョンを実装したデバイスがSmartREST経由での通信を開始すると仮定します。デバイスは認証情報を取得した後、SmartRESTプロキシに対し、テンプレートが登録済みであるかを問い合わせます。テンプレートがサーバー上で見つからない場合、デバイスはテンプレートを単一の静的テキストリクエストとして Things Cloud へ送信します。この手順が完了したら、このテンプレートを使用する同類のデバイスはすべて、テンプレートをサーバーに再送しなくても、SmartRESTを使用する通信を開始することができます。
この例は、変換プロセス概要も例示しています。「Template 1」において、%%
はプレースホルダーであり、これをSmartRESTプロキシが埋めます。time
はサーバー側タイムスタンプに置き換えられます(下記参照)。残りのプレースホルダーはリクエストデータに置き換えられます。リクエスト例における行1,200,20.5
は以下のように解釈されます。
- 最初のカラムは、使用するテンプレート(この例ではTemplate 1)を参照します。
200
はテンプレート内の最初のプレースホルダーを指し、この例で言えば「source」要素内のIDを指します。(メジャーメントを送信するデバイスID)20.5
はテンプレート内の2番目のプレースホルダーを指し、この例では温度メジャーメントの値に置き換えられます。
基本的なSmartRESTプロトコル
すべてのSmartRESTリクエストの基本構造は次の通りです。
- 最終的にどのように変換されるかに関係なく、リクエストはすべてエンドポイント/s宛のPOSTリクエストになります。
- 標準のHTTP「Authorization」ヘッダーを使用してクライアントを認証します。
- 付加的な「X-Id:」ヘッダーを使用して、クライアントの実装をデバイスタイプ(「Device_1.0」など)またはテンプレート登録プロセスで返却された識別子として指定します。
- リクエスト本体は、コンマ区切り値形式のテキスト行を含みます。各行は、標準の Things Cloud REST APIに対する1件のリクエストに相当します。
- 応答は常に「200 OK」です。
- 応答本体も同じく、コンマ区切り値からなる行を含みます。行は、特定のリクエストに関する Things Cloud REST APIからの応答に相当します。
上記の例で言えば、SmartRESTリクエストは次のようになります。
POST /s HTTP/1.1
Authorization: <AUTHORIZATION>
X-Id: Device_1.0
1,200,20.5
これに呼応する応答例として以下が挙げられます。
HTTP/1.1 200 OK
Transfer-Encoding: chunked
20,0
リクエストと応答を照合するため、応答行には、エラーコードの次に、応答に対応するリクエストを示す行が含まれます。この例で言えば、20
は「OK」を意味し、0
はリクエストの1行目を指します。
テンプレートの登録方法は?
前述の通り、クライアントは SmartREST を使用する場合、まず、SmartRESTテンプレートがすでにサーバーにとって既知であるかどうかを尋ねます。これは以下のような空のSmartRESTリクエストを使用して行われます。
POST /s HTTP/1.1
Authorization: <AUTHORIZATION>
X-Id: Device_1.0
デバイス実装が既知であれば、応答はIDを返し、このIDはその後のリクエストにおける「X-Id」ヘッダーの「簡略表現」として使用することができます。
HTTP/1.1 200 OK
20,<id>
デバイス実装が未知の場合、応答は以下のようになります。
HTTP/1.1 200 OK
40,"No template for this X-ID"
この場合、あなたのデバイス実装で使用するすべてのテンプレートを作成します。
POST /s HTTP/1.1
Authorization: <AUTHORIZATION>
X-Id: Device_1.0
10,1,POST,/measurement/measurements,application/vnd.com.nsn.cumulocity.measurement+json,,%%,NOW UNSIGNED NUMBER,{ "time": "%%", "type": ... }
この例では、10
はリクエストテンプレートを指します(一方、11
は応答テンプレートを指します)。このテンプレートは「1」番なので、このテンプレートを使用するSmartRESTリクエストは最初の列に「1」が付くことになります。このテンプレートはエンドポイント /measurement/measurements 宛の「POST」リクエストを参照し、コンテンツ種別は application/vnd.com.nsn.cumulocity.measurement+json
となります。このテンプレートで使用されるプレースホルダはー %%
です。プレースホルダーはタイムスタンプ(NOW
)と、符号なし数値および一般数値です。最後に、最後の列には、入力され送信されることになるPOSTリクエストの本体を格納します。
応答はどのように扱われますか?
上記の例ではリクエストとリクエストテンプレートの取り扱いを例示しました。応答の場合、JSONPath 表現がThings Cloud REST応答をCSVに変換します。例えば、デバイスにディスプレイ画面があり、メッセージをその画面に表示できるとしましょう。メッセージを更新するためのオペレーションは次のようになります。
{
"c8y_Message": {
"text": "Hello, world!"
},
"creationTime": "2019-02-25T08:32:45.435+01:00",
"deviceId": "8789602",
"status": "PENDING"
}
クライアント側では、デバイスは主に表示されることになるテキストを知る必要があります。JSONPathでは、以下の構文を使用して text
プロパティを抽出します。
$.c8y_Message.text
この構文において、$
はデータ構造のルートを指し、.
はデータ構造からの要素を選択します。オプションについて詳しくは、JSONPath リファレンスをご覧ください。
デバイスは通常、自らに関連するオペレーションと、PENDING状態のオペレーションをすべて問い合わせます。そうしたクエリに対する Things Cloud の標準応答は、次のようになります。
{
"operations": [{
"c8y_Message": {
"text": "Hello, world!"
},
"creationTime": "2014-02-25T08:32:45.435+01:00",
"deviceId": "8789602",
"status": "PENDING"
}, {
"c8y_Relay": {
"status": "OPEN"
}
}]
}
つまり、応答にはオペレーションのリストが含まれ、これらのオペレーションはさまざまな種類を有する場合があります。そうした構造に対処するには、以下の応答テンプレートを使用します。
11,2,$.operations,$.c8y_Message,$.c8y_Message.text
これは値ごとに説明すると、以下のような意味になります。
- 11: これは応答テンプレートです。
- 2: テンプレート番号は2番です。
- $.operations: この応答はリストであり、リストのプロパティは
operations
です。 - $.c8y_Message: このテンプレートは
c8y_Message
のプロパティを伴う応答に当てはまります。 - $.c8y_Message.text: テキストはメッセージから抽出され、返されることになります。
結果、SmartRESTクライアントは以下の応答を返されることになります。
HTTP/1.1 200 OK
2,0,"Hello, world!"
この応答は、表示メッセージを変換するためのテンプレートであるテンプレート2を使用して作成されました。応答は最初に送られたリクエストを参照します。実際に設定されるメッセージは「Hello, world!」です。
MQTT クイックリファレンス
クイックリファレンス
接続
- CONNECT d:1234:myDevice_10 acme/device_1234
シリアル「1234」とデフォルトのテンプレート myDevice_10 を使用してデバイスをテナント「acme」とユーザー「device_1234」に接続します。
トピック
パブリッシュ
- PUBLISH s/us - 静的テンプレートを送信します。
- PUBLISH s/us/5678 - 静的テンプレートを子 “5678” として送信します。
- PUBLISH s/ud - デフォルトのテンプレート (myDevice_10) を使用してメッセージを送信します。
- PUBLISH s/ud/5678 - 上記と同じですが、子 “5678"としてメッセージを送信します。
- PUBLISH s/uc/myCommon_10 - myCommon_10テンプレートを使用してメッセージを送信します。
- PUBLISH s/uc/myCommon_10/5678 - 上記と同じですが、子 “5678"としてメッセージを送信します。
サブスクライブ
- SUBSCRIBE s/ds - 静的コマンドを受信します。
- SUBSCRIBE s/dd - デフォルトのテンプレート (myDevice_10) を使用してコマンドを受信します。
- SUBSCRIBE s/dc/myCommon_10 - myCommon_10テンプレートを使用してコマンドを受信します。
- SUBSCRIBE s/e - エラーメッセージを受信します。
トピック形式
<protocol>/<direction><type>[/<template>][/<child_id>]
場所:
<protocol>
:s(persistent:永続的)、t(transient:一時的)、q(quiescent:静止)、c(CEP)
詳細は、SmartREST 1.0 > SmartREST 1.0を送信する > 処理モードをご覧ください。<direction>
:u(デバイスからの上流)、d(デバイスの下流)、e(エラー)<type>
:s(静的)、c(カスタム、デバイス定義)、d(デフォルト)、t(テンプレート)、cr(認証情報)
デバイス登録
- CONNECT 1234 management/devicebootstrap
- SUBSCRIBE s/dcr
- PUBLISH s/ucr
- PUBLISH s/ucr
- …
- 70,tenant,username,password
テンプレート登録
- PUBLISH s/ut/myCommon_10
- 10,999,POST,MEASUREMENT,,c8y_MyMeasurement;;c8y_MyMeasurement.M.value,NUMBER,… 10,msgId,api,method,response,type,time,custom1.path,custom1,type,custom1.value
テンプレート
使用可能な MQTT 静的テンプレートの概要については、テンプレート クイックリファレンスをご覧ください。
SmartREST 2.0
概要
このセクションでは、Things Cloud MQTT実装で使用できるSmartREST 2.0ペイロード形式について説明します。
SmartREST 2.0はMQTTプロトコルを利用するように設計されているので、HTTP経由のSmartREST 1.0よりもペイロードを削減できる可能性があリます。
SmartREST 2.0はMQTT経由でのみ利用可能であり、主な通信のために以下のMQTTトピックを提供しています。
メッセージをパブリッシュするには:
s/uc/<X-ID>
TRANSIENTモードでメッセージをパブリッシュするには:
t/uc/<X-ID>
QUIESCENTモードでメッセージをパブリッシュするには:
q/uc/<X-ID>
CEPモードでメッセージをパブリッシュするには:
c/uc/<X-ID>
TRANSIENT、QUIESCENT、およびCEPデータ処理の詳細については、SmartREST 1.0 > SmartREST 1.0を送信する > 処理モード をご覧ください。
応答をサブスクライブするには:
s/dc/<X-ID>
テンプレートの作成に関するトピックは、MQTT経由のテンプレートの作成で説明しています。
SmartREST 1.0からの変更点
SmartREST 2.0のベースは以前のバージョンと同じで、CSVに似たペイロード形式で、以前に作成されたテンプレートによってサポートされ、最終的にターゲットとするJSON構造を作成します。
機能にいくつかの変更が加えられました。
- テンプレートにはオブジェクトのIDが含まれなくなりました(代わりに、IDはMQTT ClientIdなどによって解決されます)。
- マネージドオブジェクトは、External IDを使用して直接作成および取得できます。
- 要求テンプレートの作成でJSONパスが使用されるようになりました(応答テンプレートなど)。
- 応答リストのサポート。
- パターンの一部だけが見つかった場合にも応答が返されます。
- 接続のデフォルトX-IDの宣言。
サポートされているテンプレート
SmartREST 2.0では、次の一致するHTTPメソッドのテンプレートを作成できます。
API | GET | POST | PUT |
---|---|---|---|
インベントリ | о | о | о |
アラーム | о | о | |
イベント | о | ||
メジャーメント | о | ||
オペレーション | о |
さらに、応答およびオペレーションから特定の値を返すテンプレートを作成できます。
テンプレートコレクション
テンプレートコレクションは、デバイス通信プロトコルを指定する要求テンプレートと応答テンプレートのセットです。各コレクションは、一意のID(X-IDと呼ばれる)によって参照されます。
MQTT経由のテンプレート作成
SmartREST 1.0と同様に、コレクション内のすべてのテンプレートを1つのメッセージで渡す必要があります。テンプレートコレクションの作成後は、MQTTを使用して変更することはできなくなります。
テンプレートを作成する場合、クライアントは次のトピックにパブリッシュする必要があります。
s/ut/<X-ID>
テンプレートコレクションが存在するかどうかを確認するために、クライアントは次のトピックをサブスクライブできます。
s/dt
サブスクライブすると、クライアントは作成トピックに空のメッセージを送信し、このX-IDの作成ステータスに関する新しいメッセージをトリガーできます。
例
s/ut/myExistingTemplateCollectionへの空のパブリッシュ
20,myExistingTemplateCollection,<ID of collection>
s/ut/myNotExistingTemplateCollectionへの空のパブリッシュ
41,myNotExistingTemplateCollection
要求テンプレート
要求テンプレートには、次の基本フィールドが含まれます。
フィールド | データ型 | 値 | 必須 | 説明 |
---|---|---|---|---|
messageId | String | はい | コレクション内のテンプレートを参照する一意のID | |
method | String | GET PUT POST |
はい | データを取得、更新、または作成するかどうか |
api | String | INVENTORY MEASUREMENT ALARM EVENT OPERATION |
はい | 使用する Things Cloud API |
response | Boolean | true false |
いいえ | リクエストが応答テンプレートをトリガーするかどうか。 GETテンプレートの場合はデフォルトでtrue、それ以外の場合はデフォルトでfalse |
mandatoryValues | List<String> | はい | APIの必須フィールドの値。 値は、テンプレートが使用するAPIおよびメソッドによって異なります | |
customValues | List<CustomValue> | いいえ | オブジェクトに追加するカスタム値 |
要求テンプレートには、データの作成時または更新時に追加されるオブジェクト構造内のすべてのフラグメント(必須およびカスタム)がリストされます。 テンプレートに固定値を設定し、サーバーで置き換えることができます。テンプレートに値が設定されていない場合は、その値をパブリッシュメッセージに含める必要があります(これにはmandatoryValuesが含まれます)。
例
このようなメジャーメントを作成するためのテンプレートを作成します(メジャーメントには、typeとtimeの2つの必須値があります)。
# 10,msgId,method,api,response,type,time,custom1.path,custom1.type,custom1.value
10,999,POST,MEASUREMENT,,c8y_MyMeasurement,,c8y_MyMeasurement.M.value,NUMBER,
このテンプレートでは、メジャーメントのカスタムプロパティを1つ追加定義します。テンプレート宣言の2つのフィールドを空のままにしているので(timeとカスタムプロパティ)、テンプレートを使うためにクライアントはこれら2つの値を送信する必要があります。
999,2016-06-22T17:03:14.000+02:00,25
# We can also use server time by leaving the time empty
999,,25
次のセクションでは、さまざまなテンプレートの作成方法と使用方法について詳しく説明します。
GETテンプレート
インベントリのGETテンプレートには、必須またはカスタムの値は必要ありません。代わりに、2つの異なるフィールドを使用します。
SmartREST 2.0では、IDによってインベントリからオブジェクトを取得するか、External IDによってオブジェクトを直接取得するかを選択できます。したがって、mandatoryValuesおよびcustomValuesフィールドの代わりに、次の2つのフィールドが使用されます。
フィールド | データ型 | 値 | 必須 | 説明 |
---|---|---|---|---|
byId | Boolean | true false |
はい | GETをThings Cloud ID(= true)またはExternal ID(= false)のどちらで実行するか |
externalIdType | String | いいえ | テンプレートがexternalIdによって呼び出された場合、固定externalIdTypeを設定します |
これにより、次の3つの異なる方法でインベントリを照会することができます。
Things Cloud ID (マネージドオブジェクトID)
# Creation:
10,999,GET,INVENTORY,,true
# Usage:
999,123456
テンプレートに固定タイプを持つExternal ID
# Creation:
10,999,GET,INVENTORY,,false,c8y_Serial
# Usage:
999,myDeviceImei
テンプレートに固定タイプがないExternal ID
# Creation:
10,999,GET,INVENTORY,,false
# Usage:
999,c8y_Serial,myDeviceImei
POST テンプレート
POSTテンプレートには、APIに基づいて必須値の組み合わせが異なります。
API | 必須値 |
---|---|
メジャーメント | type, time |
イベント | type, text, time |
アラーム | type, text, status, severity, time |
インベントリ | externalIdType |
これにより、次の最小限のテンプレートが作成されます。
# Creation:
10,100,POST,MEASUREMENT,false,c8y_MyMeasurement,,c8y_MyMeasurement.M.value,NUMBER,
10,101,POST,EVENT,,c8y_CustomEvent,mytext,,
10,102,POST,ALARM,,c8y_CustomAlarm,mytext,ACTIVE,MAJOR,
# Usage:
100
101
102
インベントリでのデータの作成には、オプションでそのオブジェクトのexternalIdの作成が含まれます。 これは、必須値externalIdTypeによって制御されます。
# Creation:
10,100,POST,INVENTORY,,c8y_MySerial
# Usage:
# Create object with externalId c8y_MySerial/myImei
100,myImei
# Create object with externalId c8y_MySerial/myImei
101,myImei,c8y_MySerial
# This message will result in not creating an external ID
101,,c8y_MySerial
PUTテンプレート
インベントリのPUTテンプレートはGETテンプレートと同じロジックに従いますが、さらにPUTにカスタム値を使用することもできます。
# Creation:
# 10,msgId,method,api,response,byId,externalIdTyoe,custom1.path,custom1.type,custom1.value
10,999,PUT,INVENTORY,,false,c8y_Serial,c8y_MyCustomValue,STRING,
# Usage:
999,myDeviceImei,myValue
アラームの PUT テンプレートは、アラームのタイプを使用して、更新するアラームを見つけます。最初にACTIVE アラームをチェックし、アクティブアラームがない場合は、ACKNOWLEDGED アラームをチェックします。
# Creation:
# 10,msgId,method,api,response,type,custom1.path,custom1.type,custom1.value
10,999,PUT,ALARM,,c8y_MyCustomAlarm,status,ALARMSTATUS
# Usage:
999,CLEARED
オペレーションのPUTテンプレートは、オペレーションのフラグメントを使用してオペレーションを見つけます。最初にEXECUTINGオペレーションをチェックし、EXECUTINGオペレーションがない場合はPENDINGオペレーションをチェックします。
# Creation:
# 10,msgId,method,api,response,fragment,custom1.path,custom1.type,custom1.value
10,999,PUT,OPERATION,,c8y_MyOperation,status,OPERATIONSTATUS,SUCCESSFUL,c8y_Fragment.val,NUMBER,
# Usage:
999,24
カスタムプロパティの追加
すべてのPOSTおよびPUT値を使用すると、テンプレートの結果にカスタムプロパティを追加できます。
1つのカスタムプロパティでは、テンプレートの作成に次の3つの値を追加する必要があります。
フィールド | 説明 |
---|---|
path | 設定する値のJsonパス |
type | 値のオプションのデータ型 デフォルト:STRING |
value | 設定する値 このフィールドを空のままにすると、クライアントはテンプレートを使用するときに値を送信する必要があります。 |
タイプ | 説明 |
---|---|
STRING | デフォルトの型。値の追加検証はありません。 |
DATE | ISO 8601形式のタイムスタンプ 日付を使用し、タイムスタンプを送信しないと、サーバー時刻が使用されます。 |
NUMBER | 整数または小数点以下の数字 |
INTEGER | 整数 |
UNSIGNED | 整数(正のみ) |
FLAG | 空のマップ(例:c8y_IsDevice:{}) クライアントはこの値に対して何も送信する必要はありません。 |
SEVERITY | アラームの重大度 アラームの重要度フィールドを更新するために使用します。 |
ALARMSTATUS | アラームの状態 アラームのステータスフィールドを更新するために使用します。 |
OPERATIONSTATUS | オペレーションの状態 オペレーションのステータスフィールドを更新するために使用します。 |
例
追加のカスタムプロパティを使用してアラームをクリアするためのテンプレート
# Creation:
10,999,PUT,ALARM,,c8y_MyCustomALarm,status,ALARMSTATUS,CLEARED,c8y_CustomFragment.reason,STRING,
# Usage:
999,Device resolved alarm on its own
カスタムメジャーメントを作成するためのテンプレート
# Creation:
10,999,POST,MEASUREMENT,,c8y_CustomMeasurement,,c8y_CustomMeasurement.custom.value,NUMBER,,c8y_CustomMeasurement.custom.unit,STRING,X
# Usage:
999,30.6
デバイスのプロパティを更新するためのテンプレート
# Creation:
10,999,PUT,INVENTORY,,false,c8y_Serial,c8y_MyCustomValue,STRING,
# Usage:
999,myDeviceImei,updatedValue
応答テンプレート
SmartREST 2.0応答テンプレートは、SmartREST 1.0と同じ構造を使用します。
フィールド | データ型 | 必須 | 説明 |
---|---|---|---|
messageId | String | はい | コレクション内のテンプレートを参照する一意のID |
base | String | いいえ | すべてのパターンが使用するJsonパスプレフィックス |
condition | String | いいえ | パターンを使用するためにオブジェクトに存在する必要があるJsonパス |
pattern | List<String> | はい | オブジェクトから抽出されてデバイスに返されるJsonパスのリスト |
応答テンプレートはすべてのオペレーションと、trueで応答フィールドを定義するすべての要求テンプレートに使用されます。いずれの場合も、サーバーは登録されたすべての応答テンプレートを試行するため、1つのオペレーションまたは要求に対して複数の応答行がある場合があります。
SmartREST 2.0は、条件が真(または条件が定義されていない)の場合、常に応答テンプレートを返します。解決されなかったパターンは、空の文字列として返されます。
条件フィールドを使用して、応答テンプレートを返すタイミングを制御する必要があります。
次の例では、データのクエリ方法とカスタムオペレーションの解析方法を示します。
デバイスオブジェクトからのクエリデータ
デバイスオブジェクト:
{
"id": "12345",
"type": "myMqttDevice",
"c8y_IsDevice": {},
"c8y_Configuration": "val1=1\nval2=2"
}
テンプレート作成:
10,999,GET,INVENTORY,,true
11,888,,c8y_IsDevice,type,c8y_Test,c8y_Configuration
クライアントからのパブリッシュ:
999,12345
クライアントへの受信情報:
888,myMqttDevice,,"val1=1\nval2=2"
カスタムオペレーションの解析
オペレーションオブジェクト:
{
"id": "12345",
"deviceId": "67890",
"agentId": "67890",
"status": "PENDING",
"c8y_CustomConfiguration": {
"val1": "1",
"val2": "2",
"customValues": ["a", "b", "c"]
},
"description": "Send custom configuration"
}
テンプレート作成:
11,111,c8y_CustomConfiguration,deviceId,val1,val2,customValues[*]
11,222,,deviceId,c8y_CustomConfiguration.val1,c8y_CustomConfiguration.val2
11,333,,deviceId,val1,val2,customValues[*]
11,444,c8y_CustomConfiguration,c8y_CustomConfiguration.val3,val1,val2,customValues[*]
クライアント受信情報(ClientIdが「myMqttTestDevice」であると仮定):
111,myMqttTestDevice,1,2,a,b,c
222,myMqttTestDevice,1,2
333,myMqttTestDevice,,,
条件がオペレーションと一致しないため、テンプレート444は返されません。
複数のオブジェクトを持つキーを含むデバイスオブジェクトからのクエリデータ
デバイスオブジェクト:
{
"id": "12345",
"name": "test",
"type": "c8y_MQTTdevice",
"c8y_IsDevice": {},
"myList": [
{
"pid": 12345,
"type": "test"
},
{
"pid": 123456,
"type": "test2"
}
]
}
テンプレート作成:
10,999,GET,INVENTORY,,true
11,888,,,"$.myList[*].type"
クライアントからのパブリッシュ:
999,12345
クライアントへの受信情報:
888,test,test2
デフォルトコレクションの使用
トピックの一部としてX-IDを使用すると、複数のテンプレートコレクションを簡単に使用できますが、メッセージごとにバイトが追加されます。 いずれにしても、デバイスがほとんど(または完全に)単一のコレクションを使用する場合は、このコレクションをデフォルトのコレクションとして指定することをお勧めします。
デフォルトのコレクションを指定すると、クライアントはX-IDを必要としない特別なトピックを使用でき、代わりにサーバーは前に指定されたX-IDを使用します。トピックは、パブリッシュの場合はs/ud、サブスクライブの場合はs/ddです。
MQTT ClientId内でX-IDを指定できます(MQTT実装をご覧ください)。
MQTT ClientIdは次のようになります。
d:myDeviceSerial:myDefaultTemplateXID
d:
を含める必要があります。MQTT接続の確立時にデフォルトのテンプレートが存在する必要はありません(クライアントが使用すると検証されます)。
IDの取り扱い
IDレス通信の概念
Things Cloud の MQTT 実装は、特にデバイス通信用に設計されています。そのため、クライアント側から不要なロジックをできるだけ削除しようとします。
REST(またはSmartREST)プロトコルを使用するには、更新するすべてのオブジェクト、アラーム、およびオペレーションのIDを知っている必要があります。したがって、クライアントはこれらのIDの状態を保持する必要があります。例えば、アラームを作成する場合、あとでクリアできるように、アラームのIDを知る必要があります。
MQTT実装では、このようなアクションを実行し、ロジックをサーバーに移動するためにデバイスで必要なロジックを減らしたいと考えています。
例 1: デバイスの ID
RESTを経由してデバイスオブジェクトのデータを更新するには、デバイスオブジェクトのID(マネージドオブジェクトID)を知る必要があります。また、このIDはデバイスに関連付ける必要がある、他のすべてのデータ(メジャーメント、アラーム、イベントのソースなど)にも必要です。
IDをデバイスに保持する必要性をなくすために、Things Cloudは Identity APIを提供しており、External ID(例えばシリアル番号)をオブジェクトにリンクできるため、いつでもIDを照会することができます。
一般的なデバイスの起動は次のようになります。
MQTTでは、MQTT ClientIdで Identity APIを自動的に使用します。 これにより、デバイスにIDを通知する必要がなくなり、クライアントはこの接続で他のデータも送信するため、すべてのメジャーメント、アラーム、イベントなどを正しいデバイスに関連付けることができます。
例 2: アラームの ID
クライアントがREST APIを使用してアラームを作成する場合、Things Cloudによって生成されたアラームのIDを取得する必要があります。
クライアントは、後でアラームを更新するためにこのIDを必要とします。例えば、アラームがアクティブでなくなった場合、ステータスをCLEAREDに更新します。
Things Cloudでは、デバイスはステータスがACTIVEのタイプごとに1つのアラームしか持つことができません。同じタイプで別のアラームを作成すると、重複除外されます。したがって、MQTT実装ではアラームのタイプを識別子として使用します。クライアントは解決されたアラームのタイプを送信するだけで、サーバーは正しいアラームオブジェクトを見つけることができます。
MQTT 静的テンプレート
概要
デバイスの統合を容易にするために、Things Cloudはすでに、独自のテンプレートを作成することなく任意のクライアントで使用できる多くの静的テンプレートをサポートしています。これらのテンプレートは、デバイス管理の目的で最も一般的に使用されるメッセージに焦点を当てています。
下記のテンプレートを使用するには、トピックs/us(TRANSIENTモードはトピックt/us、QUIESCENTモードはトピックq/us、CEPモードはトピックc/us)にメッセージをパブリッシュする必要があります。詳しくは、SmartREST 1.0 > SmartREST 1.0の送信 > 処理モードをご覧ください。
静的テンプレートを使用してオペレーションを受信するには、トピックs/dsをサブスクライブする必要があります。
テンプレート クイックリファレンス
以下のコマンドをクリックすると、それぞれのテンプレートの詳細が表示されます。パラメータが角かっこで囲まれている場合は省略可能です。
クライアントは、s/dsをサブスクライブするときに次のテンプレートを受信することができます。
デバイスの自動作成
静的テンプレートのトピックは、デバイスの自動作成をサポートしています。MQTT ClientIdに関連付けられた子デバイスがなく、データを送信すると、Things Cloudは自動的にMQTT ClientId用のデバイスを作成します。独自にデバイスを作成する場合、最初のメッセージはデバイスの作成でなければなりません。この場合、Things Cloudはテンプレートからデバイスを作成します。
デバイスの自動作成は、第1レベルの子デバイスでもサポートされています。下位レベルの子デバイスの場合は、子デバイスを作成するためのテンプレートを使用して、新しい子デバイスの下にある子デバイスのトピックにそのテンプレートを送信する必要があります。
必須パラメータなしの処理
パラメータが必須として宣言されていない場合、クライアントはその場所に空の文字列を送信できます。
100,,myType
末尾のコンマは必要ありません。次の2行では、同じメッセージになります。
100,,
100
テンプレートのパブリッシュ
次のテンプレートを使用して、トピックs/us、t/usに関するデータをパブリッシュできます。TRANSIENTデータ処理のトピックt/の詳細については、SmartREST 1.0 > SmartREST 1.0の送信 > 処理モードをご覧ください。
インベントリテンプレート(1xx)
デバイス作成 (100)
インベントリにシリアル番号に対するデバイスがまだ存在していない場合は、新しいデバイスを作成します。デバイスのc8y_SerialのexternalIdとMQTT ClientIdのデバイス識別子としての値が作成されます。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | device name | いいえ | String | MQTT Device <serialNumber> |
2 | device type | いいえ | String | c8y_MQTTDevice |
例
100,myDevice,myType
子デバイスの作成 (101)
現在のデバイスの新しい子デバイスを作成します。新しく作成されたオブジェクトは子デバイスとして追加されます。さらに、子デバイスのexternalIdがc8y_Serialに作成され、値はルートデバイスのシリアルと一意の子デバイスIDの組み合わせになります。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | unique child ID | はい | String | |
2 | device name | いいえ | String | MQTT Device <serialNumber> |
3 | device type | いいえ | String | c8y_MQTTChildDevice |
例
101,uniqueChildId,myChildDevice,myChildType
サービスの作成 (102)
特定のデバイス用の新しいソフトウェア サービスを作成します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | service unique external id | はい | String |
2 | service type | はい | String |
3 | service name | はい | String |
4 | service status | はい | String |
例
102,myDevice_MongoDb,systemd,MongoDb,up
サービスステータスの更新 (104)
特定のソフトウェアサービスのステータスを設定します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | service status | はい | String |
例
104,up
子デバイスを取得する (105)
デバイスの子デバイスの送信をトリガーします。
例
105
デバイスのフラグメントをクリアする (107)
1つ以上のフラグメントをデバイスから削除します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1… | fragmentName | はい | String |
例
107,c8y_Position,c8y_Configuration
ハードウェアの設定 (110)
デバイスのハードウェア プロパティを更新します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | serialNumber | いいえ | String |
2 | model | いいえ | String |
3 | revision | いいえ | String |
例
110,1234567890,myModel,1.2.3
モバイルの設定 (111)
デバイスのモバイル プロパティを更新します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | imei | いいえ | String |
2 | iccid | いいえ | String |
3 | imsi | いいえ | String |
4 | mcc | いいえ | String |
5 | mnc | いいえ | String |
6 | lac | いいえ | String |
7 | cellId | いいえ | String |
例
111,1234567890,,54353
位置の設定 (112)
デバイスの位置プロパティを更新します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | latitude | いいえ | Number |
2 | longitude | いいえ | Number |
3 | altitude | いいえ | Number |
4 | accuracy | いいえ | Integer |
例
112,50.323423,6.423423
構成の設定 (113)
デバイスの構成プロパティを更新します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | configuration | いいえ | String |
例
113,"val1=1\nval2=2"
サポートされている操作を設定する (114)
デバイスのサポートされている操作を設定します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1… | List of supported operations | いいえ | String |
例
114,c8y_Restart,c8y_Configuration,c8y_SoftwareList
c8y_SoftwareList
を削除するには、114, c8y_Restart,c8y_Configuration
などのように、更新したリストで新しい114リクエストを送信してください。ファームウェアの設定 (115)
デバイスにインストールされているファームウェアを設定します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | name | いいえ | String |
2 | version | いいえ | String |
3 | URL | いいえ | String |
例
115,firmwareName,firmwareVersion,firmwareUrl
ソフトウェアリストの設定 (116)
デバイスにインストールされているソフトウェアのリストを設定します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1… | 下記の 3 values(ソフトウェア毎) 配列 | いいえ | (n/a) |
1.1 | name | いいえ | String |
1.2 | version | いいえ | String |
1.3 | URL | いいえ | String |
例
116,software1,version1,url1,software2,,url2,software3,version3
必要な可用性の設定 (117)
可用性監視に必要な間隔を分単位の整数値で設定します。詳しくは、デバイス管理ライブラリ > デバイスの可用性の c8y_RequiredAvailabilityをご覧ください。存在しない場合のみ値を設定します。UIなどで入力した値は上書きされません。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | Required interval | いいえ | Integer |
例
117,60
サポートされているログの設定 (118)
デバイスのサポートしているログを設定します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1… | supported logs 配列 | いいえ | String |
例
118,ntcagent,dmesg,logread
サポートされている構成の設定 (119)
デバイスのサポートされている構成を設定します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1… | supported configurations 配列 | いいえ | String |
例
119,modbus,system
現在インストールされている構成の設定 (120)
デバイスの現在インストールされている構成を設定します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | Configuration type | はい | String | |
2 | Configuration file download URL | はい | String | |
3 | File name | いいえ | String | 構成のタイプ |
4 | Date and time when the configuration was applied | いいえ | Date | 現在の日時 |
例
120,myType,http://www.my.url,config.bin,2020-07-22T17:03:14.000+02:00
適用中のデバイスプロファイルの設定 (121)
デバイスに適用されているデバイス プロファイルを設定します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | Profile executed | はい | String | |
2 | Profile ID | いいえ | String | 最も古い実行中デバイスのプロファイルオペレーションによるプロファイルID |
例
121,true,8473
高度なソフトウェアリストの設定 (140)
デバイスにインストールされている高度なソフトウェアのリストを設定します。既存のリストはすべて上書きされます。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | Name of the software | はい | String | |
2 | Version of the software | はい | String | |
3 | Type of the software | いいえ | String | |
4 | URL of the software | いいえ | String |
例
140,docker,3.2.1,systemd,https://www.docker.com/,nginx,1.6,container,https://www.nginx.com/
高度なソフトウェアの追加 (141)
デバイスに存在するリストに高度なソフトウェアを追加します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | Name of the software | はい | String | |
2 | Version of the software | はい | String | |
3 | Type of the software | いいえ | String | |
4 | URL of the software | いいえ | String |
例
141,docker,3.2.1,systemd,https://www.docker.com/,nginx,1.6,container,https://www.nginx.com/
高度なソフトウェアの削除 (142)
デバイスに存在するリストから高度なソフトウェアを削除します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | Name of the software | はい | String | |
2 | Version of the software | はい | String |
例
142,docker,3.2.1,nginx,1.6
メジャーメントテンプレート (2xx)
カスタムメジャーメントの作成 (200)
特定のフラグメントとシリーズでメジャーメントを作成します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | fragment | はい | String | |
2 | series | はい | String | |
3 | value | はい | String | |
4 | unit | いいえ | String | |
5 | time | いいえ | Date | 現在のサーバー時刻 |
例
200,c8y_Temperature,T,25
信号強度メジャーメントの作成 (210)
c8y_SignalStrengthタイプのメジャーメントを作成します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | rssi value | 2が未設定なら、はい | Number | |
2 | ber value | 1が未設定なら、はい | Number | |
3 | time | いいえ | Date | 現在のサーバー時刻 |
例
210,-90,23,2016-06-22T17:03:14.000+02:00
温度メジャーメントの作成 (211)
c8y_TemperatureMeasurementタイプのメジャーメントを作成します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | temperature value | はい | Number | |
2 | time | いいえ | Date | 現在のサーバー時刻 |
例
211,25,2016-06-22T17:03:14.000+02:00
バッテリーメジャーメントの作成 (212)
c8y_Battery
タイプのメジャーメントを作成します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | battery value | はい | Number | |
2 | time | いいえ | Date | 現在のサーバー時刻 |
例
212,95,2016-06-22T17:03:14.000+02:00
アラームテンプレート (3xx)
クリティカル アラームの作成 (301)
クリティカル アラームを作成します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | type | はい | String | |
2 | text | いいえ | String | alarmType型のアラームが発生 |
3 | time | いいえ | Date | 現在のサーバー時刻 |
例
301,c8y_TemperatureAlarm
メジャーアラームの作成 (302)
メジャー アラームを作成します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | type | はい | String | |
2 | text | いいえ | String | alarmType型のアラームが発生 |
3 | time | いいえ | Date | 現在のサーバー時刻 |
例
302,c8y_TemperatureAlarm,"This is an alarm"
マイナーアラームの作成 (303)
マイナーアラームを作成します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | type | はい | String | |
2 | text | いいえ | String | alarmType型のアラームが発生 |
3 | time | いいえ | Date | 現在のサーバー時刻 |
例
303,c8y_TemperatureAlarm
警告アラームの作成 (304)
警告アラームを作成します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | type | はい | String | |
2 | text | いいえ | String | alarmType型のアラームが発生 |
3 | time | いいえ | Date | 現在のサーバー時刻 |
例
304,c8y_TemperatureAlarm,,2013-06-22T17:03:14.000+02:00
既存アラームの重大度の更新 (305)
既存アラームの重大度を変更します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | type | はい | String |
2 | severity | はい | String |
例
305,c8y_TemperatureAlarm,CRITICAL
既存アラームをクリアする (306)
既存アラームをクリアします。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | type | はい | String |
例
306,c8y_TemperatureAlarm
アラームのフラグメント削除 (307)
特定タイプのアラームのフラグメントを1つ以上削除します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | alarmType | はい | String |
2… | fragmentName | はい | String |
例
307,c8y_TemperatureAlarm,c8y_Position,c8y_Configuration
イベント テンプレート (4xx)
基本イベントの作成 (400)
指定されたタイプとテキストのイベントを作成します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | type | はい | String | |
2 | text | はい | String | |
3 | time | いいえ | Date | 現在のサーバー時刻 |
例
400,c8y_MyEvent,"Something was triggered"
位置更新イベントの作成 (401)
c8y_Positionを含む一般的な位置情報更新イベントを作成します。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | latitude | いいえ | Number | |
2 | longitude | いいえ | Number | |
3 | altitude | いいえ | Number | |
4 | accuracy | いいえ | Number | |
5 | time | いいえ | Date | 現在のサーバー時刻 |
例
401,51.151977,6.95173,67
デバイス更新を伴う位置更新イベントの作成 (402)
c8y_Positionを含む一般的な位置情報更新イベントを作成します。さらに、デバイスは同じc8y_Positionフラグメントで更新されます。
位置 | パラメータ | 必須 | タイプ | デフォルト値 |
---|---|---|---|---|
1 | latitude | いいえ | Number | |
2 | longitude | いいえ | Number | |
3 | altitude | いいえ | Number | |
4 | accuracy | いいえ | Number | |
5 | time | いいえ | Date | 現在のサーバー時刻 |
例
402,51.151977,6.95173,67
イベントのフラグメント削除 (407)
特定タイプのイベントのフラグメントを1つ以上削除します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | eventType | はい | String |
2… | fragmentName | いいえ | String |
例
407,c8y_MyEvent,c8y_Position,c8y_Configuration
オペレーションテンプレート (5xx)
PENDINGオペレーションの取得 (500)
エージェントに対するすべてのPENDINGオペレーションの送信をトリガーします。
例
500
オペレーションをEXECUTINGに設定 (501)
指定されたフラグメントの最も古いPENDINGオペレーションをEXECUTINGに設定します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | fragment | はい | String |
例
501,c8y_Restart
オペレーションをFAILEDに設定 (502)
指定されたフラグメントの最も古いEXECUTINGオペレーションをFAILEDに設定します。
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | fragment | はい | String |
2 | failureReason | いいえ | String |
例
502,c8y_Restart,"Could not restart"
オペレーションをSUCCESSFULに設定 (503)
指定されたフラグメントの最も古いEXECUTINGオペレーションをSUCCESSFULに設定します。
デバイスはフラグメントとして送信されたオペレーションのタイプに基づいて、追加のステップをトリガーする追加パラメータを送信できます。(オペレーションの更新のセクション参照)
位置 | パラメータ | 必須 | タイプ |
---|---|---|---|
1 | fragment | はい | String |
2… | parameters | いいえ | String |
例
503,c8y_Restart
サブスクライブテンプレート
サブスクライブテンプレート (1xx)
子デバイスの取得 (106)
デバイスのすべての子デバイスをリストします。
位置 | パラメータ | タイプ |
---|---|---|
1… | child | String |
例
106,child1,child2,child3
オペレーションテンプレート (5xx)
すべてのオペレーション応答は同じ基本構造を持ち、messageIdから始まり、その後にオペレーションを処理するルートデバイスまたは子デバイスのIDが続きます。
再起動 (510)
デバイスを再起動します。
例
510,DeviceSerial
コマンド (511)
オペレーションで送信されるコマンドを実行します。
位置 | パラメータ | タイプ |
---|---|---|
1 | Command text | String |
例
511,DeviceSerial,execute this
構成 (513)
オペレーションで送信される構成を設定します。
位置 | パラメータ | タイプ |
---|---|---|
1 | configuration | String |
例
513,DeviceSerial,"val1=1\nval2=2"
ファームウェア (515)
URLからファームウェアをインストールします。
位置 | パラメータ | タイプ |
---|---|---|
1 | firmware name | String |
2 | firmware version | String |
3 | url | String |
例
515,DeviceSerial,myFimrware,1.0,http://www.my.url
ソフトウェアリスト (516)
オペレーションで送信されたソフトウェアをインストールします。
位置 | パラメータ | タイプ |
---|---|---|
1… | 下記の 3 values(ソフトウェア毎)配列 | (n/a) |
1.1 | name | String |
1.2 | version | String |
1.3 | url | String |
例
516,DeviceSerial,softwareA,1.0,url1,softwareB,2.0,url2
メジャーメント要求オペレーション (517)
リクエスト名で指定されたメジャーメントを送信します。
位置 | パラメータ | タイプ |
---|---|---|
1 | request name | String |
例
517,DeviceSerial,LOGA
リレー (518)
リレーを開閉します。
位置 | パラメータ | タイプ |
---|---|---|
1 | Relay state | String |
例
518,DeviceSerial,OPEN
リレーリスト (519)
リスト内のリレーを開閉します。
位置 | パラメータ | タイプ |
---|---|---|
1… | relay state 配列 | String |
例
519,DeviceSerial,OPEN,CLOSE,CLOSE,OPEN
構成ファイルのアップロード (520)
現在の構成はThings Cloudからデバイスにアップロードされます。
例
520,DeviceSerial
構成ファイルのダウンロード (521)
URLから構成ファイルをダウンロードします。
位置 | パラメータ | タイプ |
---|---|---|
1 | url | String |
例
521,DeviceSerial,http://www.my.url
ログファイルの要求 (522)
指定したパラメーターのログファイルをアップロードします。
位置 | パラメータ | タイプ |
---|---|---|
1 | Log file name | String |
2 | Start date | Date |
3 | End date | Date |
4 | Search text | String |
5 | Maximum lines | Integer |
例
522,DeviceSerial,logfileA,2013-06-22T17:03:14.000+02:00,2013-06-22T18:03:14.000+02:00,ERROR,1000
通信モード (523)
通信モードを変更します。
位置 | パラメータ | タイプ |
---|---|---|
1 | mode | String |
例
523,DeviceSerial,SMS
タイプで構成ファイルのダウンロード (524)
タイプ の URL から構成ファイルをダウンロードします。
位置 | パラメータ | タイプ |
---|---|---|
1 | URL | String |
2 | configuration type | String |
例
524,DeviceSerial,http://www.my.url,type
パッチからのファームウェア (525)
パッチからファームウェアをインストールします。
位置 | パラメータ | タイプ |
---|---|---|
1 | firmware name | String |
2 | firmware version | String |
3 | URL | String |
4 | dependency | String |
例
525,DeviceSerial,firmwareName,1.0,http://www.my.url,dependency
タイプで構成ファイルのアップロード (526)
設定は Things Cloud からタイプでデバイスにアップロードされます。
位置 | パラメータ | タイプ |
---|---|---|
1 | configuration type | String |
例
526,DeviceSerial,type
デバイス プロファイルの設定 (527)
デバイス プロファイルを設定します。
位置 | パラメータ | タイプ |
---|---|---|
1 | firmware marker | (n/a) |
1… | 5 values of firmware | (n/a) |
1.1 | firmware name | String |
1.2 | firmware version | String |
1.3 | firmware URL | String |
1.4 | firmware isPatch | String |
1.5 | firmware dependency | String |
2 | software marker | (n/a) |
2… | 下記の 4 values(ソフトウェア毎)配列 | (n/a) |
2.1 | software name | String |
2.2 | software version | String |
2.3 | software URL | String |
2.4 | software action | String |
3 | configuration marker | (n/a) |
3… | 下記の 2 values(構成毎)配列 | (n/a) |
3.1 | configuration URL | String |
3.2 | configuration type | String |
例
527,DeviceSerial,$FW,firmwareName,1.0,http://www.my.url,true,dependency,$SW,softwareA,1.0,http://www.my.url1,action1,softwareB,2.0,http://www.my.url2,action2,$CONF,http://www.my.url1,type1,http://www.my.url2,type2
ソフトウェアの更新 (528)
デバイスにインストールされているソフトウェアを更新します。
位置 | パラメータ | タイプ |
---|---|---|
1… | 下記の 4 values(ソフトウェア毎)配列 | (n/a) |
1.1 | name | String |
1.2 | version | String |
1.3 | URL | String |
1.4 | action | String |
例
528,DeviceSerial,softwareA,1.0,url1,install,softwareB,2.0,url2,install
アクションは install
または delete
のいずれかです。
install
アクションを受信すると、デバイスエージェントはインストールが完了した後、そのソフトウェアがデバイスのc8y_SoftwareListフラグメントに表示されるようにします。また、エージェントは以前のバージョンのソフトウェアがあるかどうかを判断し、新しいバージョンと置き換えることで、更新します。
delete
アクションを受信すると、デバイスエージェントは、ソフトウェア更新オペレーションが完了した後、そのソフトウェアがデバイスのc8y_SoftwareListフラグメントに表示されないようにします。
高度なソフトウェアの更新 (529)
デバイスにインストールされているソフトウェアを更新します。
位置 | パラメータ | タイプ |
---|---|---|
1… | 下記の 5 values(ソフトウェア毎)配列 | (n/a) |
1.1 | name | String |
1.2 | version | String |
1.2 | type | String |
1.3 | URL | String |
1.4 | action to be performed | String |
例
529,DeviceSerial,softwareA,1.0,url1,install,softwareB,2.0,url2,install
クラウドリモートアクセス接続 (530)
リモート アクセス デバイス エージェントによるトンネリングを確立します。
位置 | パラメータ | タイプ |
---|---|---|
1 | hostname | String |
2 | port | Integer |
3 | connection key | String |
例
530,DeviceSerial,10.0.0.67,22,eb5e9d13-1caa-486b-bdda-130ca0d87df8
オペレーションの更新
テンプレートを使用してオペレーションをSUCCESSFUL状態に設定すると、サーバーで追加の呼び出しをトリガーする追加のパラメータの送信がサポートされます。次の表に、この機能をサポートするオペレーションと、パラメータを使用して実行されるオペレーションを示します。
フラグメント | パラメータ | トリガーされるアクション |
---|---|---|
c8y_Command | result | 結果がオペレーションに追加されます |
c8y_RelayArray | relay states | デバイスオブジェクトはステータスで更新されます |
c8y_CommunicationMode | no parameter needed | デバイスオブジェクトはモードで更新されます |
c8y_LogfileRequest | file url | ファイルのURLがオペレーションに追加されます |
c8y_DownloadConfigFile | (optional) timestamp | デバイス オブジェクトは、構成ダンプの ID とタイムスタンプ (またはサーバー時刻) で更新されます |
MQTT 経由の JSON
このセクションでは、Things Cloud MQTT 実装で使用できる JSON ペイロード形式について説明します。
固定テンプレートでのみ機能する SmartREST 2.0 と比較して、JSON の MQTT のサポートは、REST API のペイロードの柔軟性と MQTT の低いプロトコルオーバーヘッドを組み合わせるように設計されています。
ペイロードを最小限に抑えることが重要な場合(モバイルトラフィック、低機能デバイス)は、SmartRESTの方法をお勧めします。
トピック構造
JSON MQTT のトピック構造は、REST エンドポイントと非常によく似ています。主な違いは、トピックに含まれる <action>
アクション操作部分です。
メッセージをパブリッシュするには:
<api>/<resource>/<action>/<resource_id>
TRANSIENTモードでメッセージをパブリッシュするには:
t/<api>/<resource>/<action>/<resource_id>
QUIESCENTモードでメッセージをパブリッシュするには:
q/<api>/<resource>/<action>/<resource_id>
CEP モードでメッセージをパブリッシュするには:
c/<api>/<resource>/<action>/<resource_id>
<resource_id>
はすべての <action>
に必要ではありません。以下の例をご覧ください。TRANSIENT、QUIESCENTおよびCEPデータ処理の詳細については、処理モードをご覧ください。
アクション操作トピック
アクション操作トピックは、content-typeヘッダーと組み合わせたHTTPメソッドに対応しています。
次のアクション操作を実行可能:
- create - HTTP POST に対応
- createBulk - content-typeヘッダー値がコレクションメディアタイプに設定されたHTTP POSTに対応
application/vnd.com.nsn.cumulocity.measurementCollection+json;charset=UTF-8;ver=0.9
- update - HTTP PUT に対応
- delete - HTTP DELETE に対応
エンドポイントのサポート
現在のJSON MQTT実装は、すべてのSmartREST 2.0操作をカバーしていないため、例えば、デバイスのブートストラッププロセス 全体をSmartREST 2.0を使用して実行する必要があります。
次のエンドポイントおよびアクション操作がサポートされています。
エンドポイント | create | createBulk | update | delete |
---|---|---|---|---|
event/events | о | о | о | о |
alarm/alarms | о | о | о | |
measurement/measurements | о | о | о | |
inventory/managedObjects | о | о | ||
inventory/managedObjects/<DeviceID>/childDevices | о |
操作がサポートされていない場合は、適切なエラー メッセージがトピックerrorに送信されます。
上記のすべてのエンドポイントに対して、REST APIと同じペイロードを使用することができます。唯一の違いは「source」フィールドにあります。RESTではこのフィールドは必須ですが、JSON MQTTではここでデバイスIDを設定する必要はありません。 sourceのデバイスIDは、MQTT ClientIdに基づいて自動的に解決されます。この値は、すでにそこで何かが定義されている場合でも常に使用されます。
例
新しいイベントの作成
トピック/event/events/createにペイロードを含むメッセージをパブリッシュするには:
{
"type": "TestEvent",
"text": "sensor was triggered",
"time": "2014-03-03T12:03:27.845Z"
}
多くのイベントの作成
トピック/event/events/createBulkにペイロードを含むメッセージをパブリッシュするには:
{
"events": [
{
"type": "TestEvent1",
"text": "sensor was triggered",
"time": "2014-03-03T12:03:27.845Z"
},
{
"type": "TestEvent2",
"text": "sensor was triggered",
"time": "2014-03-04T12:03:27.845Z"
}
]
}
イベントの更新
トピック/event/events/update/<event_id>にペイロードを含むメッセージをパブリッシュするには:
{
"text": "new text"
}
イベントの削除
トピック/event/events/delete/<event_id>に空のペイロードを含むメッセージをパブリッシュします。
メジャーメントデータポイントの作成
トピックmeasurement/measurements/createにペイロードを含むメッセージをパブリッシュするには:
{
"type": "c8y_TemperatureMeasurement",
"time": "2021-09-06T17:35:14.000+02:00",
"c8y_TemperatureMeasurement": {
"T": {
"value": 20,
"unit": "C"
}
}
}
エラー処理
JSON MQTT実装に関連するエラーをサブスクライブするには、トピックerrorを使用します。無効なペイロード、間違ったトピック、またはその他の例外が発生した場合、このトピックに通知がパブリッシュされます。ペイロードはJSON形式です。標準的なエラーメッセージの他に、どのメッセージが失敗したのかをクライアントが見つけるのに役立つmessageIdも含まれています。
ペイロードの例:
{
"error": "undefined/validationError",
"message": "Following mandatory fields should be included: severity,text,time",
"messageId": 3
}
オペレーションの受信
通知クライアントは、トピックdevicecontrol/notificationsをサブスクライブして、新しく作成されたオペレーションの通知を受信できます。サブスクライブ開始時に、まだ転送されていないすべてのオペレーションがパブリッシュされます。
さらに、このファイルにはExternal IDが含まれているため、クライアントはどの子デバイスに対してオペレーションが実行されるかを識別できます。
通知の例:
{
"agentId": "1",
"creationTime": "2018-05-17T07:33:15.555Z",
"delivery": {
"log": [
],
"status": "PENDING",
"time": "2018-05-17T07:33:15.575Z"
},
"deviceId": "2",
"id": "123",
"status": "PENDING",
"c8y_Command": {
"text": "Do something"
},
"description": "Execute shell command",
"externalSource": {
"externalId": "3",
"type": "c8y_Serial"
}
}