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"
  }
}