SmartREST 2.0

概要

このセクションでは、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メソッドのテンプレートを作成できます。

さらに、応答およびオペレーションから特定の値を返すテンプレートを作成できます。

テンプレートコレクション

テンプレートコレクションは、デバイス通信プロトコルを指定する要求テンプレートと応答テンプレートのセットです。各コレクションは、一意の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

要求テンプレート

要求テンプレートには、次の基本フィールドが含まれます。

要求テンプレートには、データの作成時または更新時に追加されるオブジェクト構造内のすべてのフラグメント(必須およびカスタム)がリストされます。 テンプレートに固定値を設定し、サーバーで置き換えることができます。テンプレートに値が設定されていない場合は、その値をパブリッシュメッセージに含める必要があります(これには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つのフィールドが使用されます。

これにより、次の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に基づいて必須値の組み合わせが異なります。

これにより、次の最小限のテンプレートが作成されます。

# 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つの値を追加する必要があります。

例

追加のカスタムプロパティを使用してアラームをクリアするためのテンプレート

# 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と同じ構造を使用します。

応答テンプレートはすべてのオペレーションと、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

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のデバイス識別子としての値が作成されます。

例

100,myDevice,myType

子デバイスの作成 (101)

現在のデバイスの新しい子デバイスを作成します。新しく作成されたオブジェクトは子デバイスとして追加されます。さらに、子デバイスのexternalIdがc8y_Serialに作成され、値はルートデバイスのシリアルと一意の子デバイスIDの組み合わせになります。

例

101,uniqueChildId,myChildDevice,myChildType

サービスの作成 (102)

特定のデバイス用の新しいソフトウェア サービスを作成します。

例

102,myDevice_MongoDb,systemd,MongoDb,up

サービスステータスの更新 (104)

特定のソフトウェアサービスのステータスを設定します。

例

104,up

子デバイスを取得する (105)

デバイスの子デバイスの送信をトリガーします。

例

105

デバイスのフラグメントをクリアする (107)

１つ以上のフラグメントをデバイスから削除します。

例

107,c8y_Position,c8y_Configuration

ハードウェアの設定 (110)

デバイスのハードウェア プロパティを更新します。

例

110,1234567890,myModel,1.2.3

モバイルの設定 (111)

デバイスのモバイル プロパティを更新します。

例

111,1234567890,,54353

位置の設定 (112)

デバイスの位置プロパティを更新します。

例

112,50.323423,6.423423

構成の設定 (113)

デバイスの構成プロパティを更新します。

例

113,"val1=1\nval2=2"

サポートされている操作を設定する (114)

デバイスのサポートされている操作を設定します。

例

114,c8y_Restart,c8y_Configuration,c8y_SoftwareList

ファームウェアの設定 (115)

デバイスにインストールされているファームウェアを設定します。

例

115,firmwareName,firmwareVersion,firmwareUrl

ソフトウェアリストの設定 (116)

デバイスにインストールされているソフトウェアのリストを設定します。

例

116,software1,version1,url1,software2,,url2,software3,version3

必要な可用性の設定 (117)

可用性監視に必要な間隔を分単位の整数値で設定します。詳しくは、デバイス管理ライブラリ > デバイスの可用性の c8y_RequiredAvailabilityをご覧ください。存在しない場合のみ値を設定します。UIなどで入力した値は上書きされません。

例

117,60

サポートされているログの設定 (118)

デバイスのサポートしているログを設定します。

例

118,ntcagent,dmesg,logread

サポートされている構成の設定 (119)

デバイスのサポートされている構成を設定します。

例

119,modbus,system

現在インストールされている構成の設定 (120)

デバイスの現在インストールされている構成を設定します。

例

120,myType,http://www.my.url,config.bin,2020-07-22T17:03:14.000+02:00

適用中のデバイスプロファイルの設定 (121)

デバイスに適用されているデバイス プロファイルを設定します。

例

121,true,8473

高度なソフトウェアリストの設定 (140)

デバイスにインストールされている高度なソフトウェアのリストを設定します。既存のリストはすべて上書きされます。

例

140,docker,3.2.1,systemd,https://www.docker.com/,nginx,1.6,container,https://www.nginx.com/

高度なソフトウェアの追加 (141)

デバイスに存在するリストに高度なソフトウェアを追加します。

例

141,docker,3.2.1,systemd,https://www.docker.com/,nginx,1.6,container,https://www.nginx.com/

高度なソフトウェアの削除 (142)

デバイスに存在するリストから高度なソフトウェアを削除します。

例

142,docker,3.2.1,nginx,1.6

メジャーメントテンプレート (2xx)

カスタムメジャーメントの作成 (200)

特定のフラグメントとシリーズでメジャーメントを作成します。

例

200,c8y_Temperature,T,25

信号強度メジャーメントの作成 (210)

c8y_SignalStrengthタイプのメジャーメントを作成します。

例

210,-90,23,2016-06-22T17:03:14.000+02:00

温度メジャーメントの作成 (211)

c8y_TemperatureMeasurementタイプのメジャーメントを作成します。

例

211,25,2016-06-22T17:03:14.000+02:00

バッテリーメジャーメントの作成 (212)

c8y_Batteryタイプのメジャーメントを作成します。

例

212,95,2016-06-22T17:03:14.000+02:00

アラームテンプレート (3xx)

クリティカル アラームの作成 (301)

クリティカル アラームを作成します。

例

301,c8y_TemperatureAlarm

メジャーアラームの作成 (302)

メジャー アラームを作成します。

例

302,c8y_TemperatureAlarm,"This is an alarm"

マイナーアラームの作成 (303)

マイナーアラームを作成します。

例

303,c8y_TemperatureAlarm

警告アラームの作成 (304)

警告アラームを作成します。

例

304,c8y_TemperatureAlarm,,2013-06-22T17:03:14.000+02:00

既存アラームの重大度の更新 (305)

既存アラームの重大度を変更します。

例

305,c8y_TemperatureAlarm,CRITICAL

既存アラームをクリアする (306)

既存アラームをクリアします。

例

306,c8y_TemperatureAlarm

アラームのフラグメント削除 (307)

特定タイプのアラームのフラグメントを1つ以上削除します。

例

307,c8y_TemperatureAlarm,c8y_Position,c8y_Configuration

イベント テンプレート (4xx)

基本イベントの作成 (400)

指定されたタイプとテキストのイベントを作成します。

例

400,c8y_MyEvent,"Something was triggered"

位置更新イベントの作成 (401)

c8y_Positionを含む一般的な位置情報更新イベントを作成します。

例

401,51.151977,6.95173,67

デバイス更新を伴う位置更新イベントの作成 (402)

c8y_Positionを含む一般的な位置情報更新イベントを作成します。さらに、デバイスは同じc8y_Positionフラグメントで更新されます。

例

402,51.151977,6.95173,67

イベントのフラグメント削除 (407)

特定タイプのイベントのフラグメントを1つ以上削除します。

例

407,c8y_MyEvent,c8y_Position,c8y_Configuration

オペレーションテンプレート (5xx)

PENDINGオペレーションの取得 (500)

エージェントに対するすべてのPENDINGオペレーションの送信をトリガーします。

例

500

オペレーションをEXECUTINGに設定 (501)

指定されたフラグメントの最も古いPENDINGオペレーションをEXECUTINGに設定します。

例

501,c8y_Restart

オペレーションをFAILEDに設定 (502)

指定されたフラグメントの最も古いEXECUTINGオペレーションをFAILEDに設定します。

例

502,c8y_Restart,"Could not restart"

オペレーションをSUCCESSFULに設定 (503)

指定されたフラグメントの最も古いEXECUTINGオペレーションをSUCCESSFULに設定します。

デバイスはフラグメントとして送信されたオペレーションのタイプに基づいて、追加のステップをトリガーする追加パラメータを送信できます。（オペレーションの更新のセクション参照）

例

503,c8y_Restart

サブスクライブテンプレート

サブスクライブテンプレート (1xx)

子デバイスの取得 (106)

デバイスのすべての子デバイスをリストします。

例

106,child1,child2,child3

オペレーションテンプレート (5xx)

すべてのオペレーション応答は同じ基本構造を持ち、messageIdから始まり、その後にオペレーションを処理するルートデバイスまたは子デバイスのIDが続きます。

再起動 (510)

デバイスを再起動します。

例

510,DeviceSerial

コマンド (511)

オペレーションで送信されるコマンドを実行します。

例

511,DeviceSerial,execute this

構成 (513)

オペレーションで送信される構成を設定します。

例

513,DeviceSerial,"val1=1\nval2=2"

ファームウェア (515)

URLからファームウェアをインストールします。

例

515,DeviceSerial,myFimrware,1.0,http://www.my.url

ソフトウェアリスト (516)

オペレーションで送信されたソフトウェアをインストールします。

例

516,DeviceSerial,softwareA,1.0,url1,softwareB,2.0,url2

メジャーメント要求オペレーション (517)

リクエスト名で指定されたメジャーメントを送信します。

例

517,DeviceSerial,LOGA

リレー (518)

リレーを開閉します。

例

518,DeviceSerial,OPEN

リレーリスト (519)

リスト内のリレーを開閉します。

例

519,DeviceSerial,OPEN,CLOSE,CLOSE,OPEN

構成ファイルのアップロード (520)

現在の構成はThings Cloudからデバイスにアップロードされます。

例

520,DeviceSerial

構成ファイルのダウンロード (521)

URLから構成ファイルをダウンロードします。

例

521,DeviceSerial,http://www.my.url

ログファイルの要求 (522)

指定したパラメーターのログファイルをアップロードします。

例

522,DeviceSerial,logfileA,2013-06-22T17:03:14.000+02:00,2013-06-22T18:03:14.000+02:00,ERROR,1000

通信モード (523)

通信モードを変更します。

例

523,DeviceSerial,SMS

タイプで構成ファイルのダウンロード (524)

タイプ の URL から構成ファイルをダウンロードします。

例

524,DeviceSerial,http://www.my.url,type

パッチからのファームウェア (525)

パッチからファームウェアをインストールします。

例

525,DeviceSerial,firmwareName,1.0,http://www.my.url,dependency

タイプで構成ファイルのアップロード (526)

設定は Things Cloud からタイプでデバイスにアップロードされます。

例

526,DeviceSerial,type

デバイス プロファイルの設定 (527)

デバイス プロファイルを設定します。

例

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)

デバイスにインストールされているソフトウェアを更新します。

例

528,DeviceSerial,softwareA,1.0,url1,install,softwareB,2.0,url2,install

高度なソフトウェアの更新 (529)

デバイスにインストールされているソフトウェアを更新します。

例

529,DeviceSerial,softwareA,1.0,url1,install,softwareB,2.0,url2,install

クラウドリモートアクセス接続 (530)

リモート アクセス デバイス エージェントによるトンネリングを確立します。

例

530,DeviceSerial,10.0.0.67,22,eb5e9d13-1caa-486b-bdda-130ca0d87df8

オペレーションの更新

テンプレートを使用してオペレーションをSUCCESSFUL状態に設定すると、サーバーで追加の呼び出しをトリガーする追加のパラメータの送信がサポートされます。次の表に、この機能をサポートするオペレーションと、パラメータを使用して実行されるオペレーションを示します。

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>

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を使用して実行する必要があります。

次のエンドポイントおよびアクション操作がサポートされています。

操作がサポートされていない場合は、適切なエラー メッセージがトピック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"
  }
}