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 データ処理の詳細については、処理モード を参照してください。

応答をサブスクライブするには、

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 接続の確立時に、デフォルトのテンプレートが存在する必要はありません（クライアントが使用すると検証されます）。