SmartREST 2.0

概要

このセクションでは、既存の SmartREST 1.0 テンプレートを MQTT で使用する方法について説明します。

SmartREST 1.0はHTTP要求/応答用に設計されており、MQTTとのIDレス通信をサポートしていないことに注意してください。HTTPを使用して送信する場合とまったく同じリクエストを送信するためにMQTT接続を使用するだけです。したがって、MQTTは要求/応答ではないため、いくつかの制限があります。

SmartREST 1.0のサポートは、既存のSmartREST1.0テンプレートを使い実装している場合に移行を容易にするために追加されました。

MQTT ClientId

SmartREST 1.0 では各メッセージの本文で ID を送信する必要がありますが、正しいMQTT ClientIdで接続することは依然として重要です。

MQTT ClientIdは、デバイスのc8y_SerialのexternalIdと一致する必要があります。正しいオペレーションと応答を割り当てるために使用されます。

SmartREST 1.0 の送受信

一般に、MQTT を介した SmartREST 要求と応答には、次のことが当てはまります。

• すべてのリクエスト行は、単一の MQTT メッセージとして送信されます。1 つの要求メッセージは、複数の応答メッセージに分割されるのではなく、常に 1 つの応答メッセージを生成します。
• すべての SmartREST 応答テンプレートは、1 つの要求の JSON 応答に適用されます。
• 一致するすべての応答テンプレートは、応答に 1 行を生成します。
• 応答行は\nで区切られます。

SmartREST 1.0 の送信

サーバーにデータを送信するには、SmartREST エンドポイント/sに POST する場合と同じコンテンツをパブリッシュできます。

X-ID ヘッダーは、クライアントがパブリッシュする必要があるトピックの一部です。

s/ul/<X-ID>

X-ID はプロトコル識別子として機能し、テンプレート コレクションを識別します。 X-ID は不変である必要があり、常にまったく同じテンプレートコレクションを識別します。 テンプレート コレクションが変更された場合は、X-ID も変更する必要があります。また、X-ID はグローバルに一意である必要があります。他のユーザーが使用していない X-ID を選択してください。確認のために、次のような逆引きドメイン名を使用することをお勧めします。

com.acme.gw801-v1
com.acme.gw801-v2

また、プロトコルバージョンを X-ID の接尾辞として追加することをお勧めします。

処理モード

Things Cloud SmartREST プロトコルは、送信されたデータがデータベースに保存しないようにするための TRANSIENT 処理モードをサポートしているため、トピックs/ではなくMQTTトピックt/にパブリッシュすると、データはリアルタイム処理にのみ渡されます。

t/ul/<X-ID>

Things Cloud SmartREST プロトコルは、QUIESCENT処理モードもサポートしており、トピックs/ではなくMQTTトピックq/にパブリッシュすることで、リアルタイム通知を回避できます。現在、QUIESCENT処理モードはメジャーメントとイベントにのみ適用可能です。

q/ul/<X-ID>

Things Cloud SmartREST プロトコルは CEP処理モードもサポートしており、トピックs/ではなくMQTTトピックc/にパブリッシュすることで、データはリアルタイム通知があるリアルタイムイベント処理エンジンにのみ送信されることを無効にします。現在、CEP処理モードはメジャーメントとイベントにのみ適用可能です。

c/ul/<X-ID>

SmartREST 1.0 の受信

テンプレートが応答テンプレートを起動する場合、サーバーは次のトピックで返されるメッセージをパブリッシュします。

s/dl/<X-ID>

このトピックは、クライアントがサブスクライブできます。

オペレーションの受信

HTTP 経由の SmartREST 1.0 はエンドポイント/notification/operationsを提供し、リアルタイムのオペレーションを監視します。次のMQTTトピックでも同じ内容を受け取ることができます。

s/ol/<X-ID>

制限事項

MQTT は現在、要求/応答をサポートしていません。したがって、パブリッシュトピックで要求を送信し、サブスクライブ トピックで応答を受信した場合、クライアントはそれらが要求に対する応答であることを安全に照合できません。

この制限に対処するには、どの要求が応答をトリガーしたかを知る必要がないようにテンプレートを設計することにより、クライアントがmessageIdによって自動的に認識するようにします。

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,myDatabaseDevice,systemd,DatabaseService,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

デバイスエージェント情報の設定 (122)

デバイス上で実行されるエージェントに関する情報を提供可能にします。

例

 122,thin-edge.io,0.6,https://thin-edge.io,Software AG

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

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

例

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

デバイス管理オブジェクトIDの取得 (123)

デバイス管理オブジェクトの ID を取得します。

例

 	123

高度なソフトウェアの追加 (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

サポートされるソフトウェアの種類の設定 (143)

デバイスがサポートするソフトウェアの種類を設定します。空の要素は無視します。空のリストは c8y_SupportedSoftwareTypes フラグメントを完全に削除します。

例

	143,yum,docker

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

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

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

例

200,c8y_Temperature,T,25

複数のフラグメントおよびシリーズによるカスタム測定の作成 (201)

複数のフラグメントおよびシリーズで測定を作成します。

例

201,KamstrupA220Reading,2022-03-19T12:03:27.845Z,c8y_SinglePhaseEnergyMeasurement,A+:1,1234,kWh,c8y_SinglePhaseEnergyMeasurement,A-:1,2345,kWh,c8y_ThreePhaseEnergyMeasurement,A+:1,123,kWh,c8y_ThreePhaseEnergyMeasurement,A+:2,234,kWh,c8y_ThreePhaseEnergyMeasurement,A+:3,345,kWh

信号強度メジャーメントの作成 (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

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

指定されたIDのオペレーションにEXECUTINGを設定します。オベレーションが存在し、要求元のデバイスをソースとして持つ必要があります。

例

504,123

オペレーションをFAILEDに設定（505）

指定されたIDのオペレーションにFAILEDを設定します。オベレーションが存在し、要求元のデバイスをソースとして持つ必要があります。

例

505,123,"Could not restart"

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

指定されたIDのオペレーションにSUCCESSFULを設定します。オベレーションが存在し、要求元のデバイスをソースとして持つ必要があります。

オペレーションのタイプに基づいて、追加のステップのトリガーとなる追加パラメータをデバイスに送信できるようになります。詳細についてはオペレーションの更新もご覧ください。

例

506,c8y_Restart

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

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

子デバイスの取得 (106)

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

例

106,child1,child2,child3

デバイス管理オブジェクトIDの取得 (124)

デバイス管理オブジェクトID を取得します。

例

124,12345

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

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

再起動 (510)

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

例

510,DeviceSerial

コマンド (511)

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

例

511,DeviceSerial,execute this

構成 (513)

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

例

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

ファームウェア (515)

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

例

515,DeviceSerial,myFirmware,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"
  }
}