SmartREST 1.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によって自動的に認識するようにします。

プロトコル

SmartREST は現在確立された HTTP プロトコルを基本としており、 HTTP クライアントが提供される環境からアクセス可能です。SmartREST は、 HTTP における双方向型通信のための POST メソッドを使用して、排他的に /s リソース経由で通信を行います。ペイロードデータ形式は CSV（カンマ区切り値）形式です。

次の例は、クライアントと SmartREST エンドポイントとの間の通信です。注意点として、リクエストには Authorization ヘッダーとカスタム X-Id ヘッダーが含まれますが、これはリクエスト向けに使用する SmartREST テンプレートを指定するものです。

POST /s HTTP/1.0
Authorization: Basic ...
X-Id: ...
Transfer-Encoding: chunked

100,1234456

個々の SmartREST リクエストは、アクションに対応する固有の符号なし整数値から始まり、後続にパラメータ値を記述する、１つの行で表されます。

SmartREST エンドポイントは、以下のレスポンスを取得します。注意点として、 HTTP 応答コードは、SmartREST エンドポイントが利用不可の場合を除き、常に 200 です。

HTTP/1.1 200 OK
Transfer-Encoding: chunked

200,1,123456,Request result

SmartREST エンドポイントにより取得される各行は、「 SmartREST リクエスト結果から抽出される一意の符号なし整数(200)」、「 SmartREST リクエスト行番号」および「リクエストデータ値の一連の値」で構成されます。

データ形式

SmartREST エンドポイントとの通信には CSV（カンマ区切り値） 形式を使用します。スムーズに通信するには、以下のルールに従わなければなりません。

• すべての行が \n文字列で終了しなければなりません。
• 値は常にカンマ（,）で区切られます。
• 値が、二重引用府（"）、カンマ（,）、先頭または末尾の空白、改行(\n)、キャリッジリターン(\r)またはタブ位置を含む場合、それらを引用符（"）で囲まなければなりません。含まれる引用符（"）は、もう1つの引用符（""）を前に付けてエスケープしなければなりません。

サーバーからクライアントに送信されるメッセージにも、同じエスケープ ルールが適用されます。

例

次の例は、上述したルールの例となります。

100,Hello world!
101," I have leading whitespace!"
102,"I have trailing whitespace!"
103,"I contain a line
break!"
104,"I have ""quotes""!"
105,I also have 'quotes'!

処理モード

REST の実装 同様、 SmartREST でのデータ更新を伴うすべての通信(POST, PUT, DELETE)では４つの処理モード、 PERSISTENT 、 TRANSIENT 、 QUIESCENT 、 CEP が利用できます。

SmartREST エンドポイントに送信されたデータが、Things Cloud データベースへの格納とリアルタイムイベント処理の両方に転送されなければならない場合、 PERSISTENT モードを設定すべきです。このモードはデフォルトで、特別な追加設定は不要です。

通信されたデータがリアルタイムイベント処理のみで必要なケースでは、 TRANSIENT 処理モードを指定する必要があります。指定は、 HTTP リクエストヘッダーに追加します。

POST /s HTTP/1.0
Authorization: Basic ...
X-Id: ...
X-Cumulocity-Processing-Mode: TRANSIENT
Transfer-Encoding: chunked

100,1234456

ヘッダーに TRANSIENT モードがある場合、本文データは Things Cloud データベースに保持されません。

リアルタイムイベント処理の間、CEPでデータベースに保存すべきかどうかを定義することができます。

SmartREST エンドポイントに送信されるデータを Things Cloud データベースに保存すると同時にリアルタイム処理に転送する必要がある場合は、 QUIESCENT 処理モードを指定する必要があります。この場合、リアルタイム通知を使用不可にする必要があります。現在、QUIESCENT処理モードはメジャーメントおよびイベントにのみ適用できます。

SmartREST エンドポイントに送信されるデータを、リアルタイム通知無効のままリアルタイム処理エンジンへ一時的に送信する必要がある場合は、 CEP 処理モードを指定する必要があります。現在、CEP処理モードはメジャーメントおよびイベントにのみ適用されます。

テンプレート

SmartREST テンプレートとは、 CSV データおよび Things Cloud REST APIコールの変換に使用する、要求用および応答用のテンプレート集です。 SmartREST テンプレートには、処理に使用する SmartREST テンプレートを、カスタム X-Id ヘッダー値で特定するためのテンプレート識別子が含まれます。

個々の要求用テンプレートおよび応答用テンプレートは、メッセージ識別子と呼ばれる固有の数値識別子を有し、これを個々の SmartREST 要求行または応答行の最初の値により参照されます。デフォルトのメッセージ識別子と重ならないよう、100で始まるメッセージ識別子を選択することをお勧めします。

要求用テンプレート

要求用テンプレートには、 SmartREST 要求に対応するREST APIコール（その後プラットフォームへ送られる）へ変換するための情報がすべて含まれます。

要求用テンプレートには以下の情報が含まれます。

• メッセージ識別子としての固有の符号なし整数
• 要求メソッド（例：GETまたはPOST）
• リソースURI（例：/inventory/managedObjects）
• 送信データおよび受信データのContent-TYpeおよびAcceptのヘッダー値
• プレースホルダー（例：%%）
• 予想されるリクエストパラメータ（例：STRING（文字列）、NUMBER（数）、UNSIGNED（符号なし）整数およびDATE（日付））
• 各要求パラメータのプレースホルダーを伴うテンプレート文字列

応答用テンプレート

応答用テンプレートには、クライアントへ CSV データ形式で応答されることになるデータ値をプラットフォームのREST APIから抽出するために必要な情報が含まれます。

応答用テンプレートには以下の情報が含まれます。

• メッセージ識別子としての固有の符号なし整数
• $または$.managedObjectsなど、データの抽出元となるベースオブジェクトまたはオブジェクトリストを参照するJSONパス。JSONパスがオブジェクトのリストを指す場合、リスト内の各オブジェクトについて抽出されたデータから成る1つの行が取得されます。
• 値を抽出するためにベースオブジェクトまたはオブジェクトリスト内に存在しなければならないJSONパス（例：$.id）。この値は応答に含まれません。
• 抽出する各値を表わすJSONパスの変数（例：$.id、$.nameまたは$.type）。値は、テンプレートにおいて定義された順序で応答に追加されます。

登録プロセス

このガイドでは、主に SmartREST の/sエンドポイントを使用した SmartREST テンプレートの登録を中心に解説します。プラットフォームインベントリAPIを使用して登録することも可能です。

SmartREST テンプレート登録前に、同一IDのテンプレートが存在しないかを確認しなければなりません。テンプレートがすでに存在する場合、重複のためエラーメッセージが返却されます。

SmartREST テンプレートがすでに登録されているかは、次のように空リクエストを行うことによって確認できます。

POST /s HTTP/1.0
Authorization: Basic ...
X-Id: ...
Transfer-Encoding: chunked

テンプレートがすでに存在する場合、次の応答が取得されます。メッセージ識別子 20 はテンプレートがインベントリに存在することを意味し、パラメータ12345 はテンプレートのマネージドオブジェクトのGIdを意味します。

HTTP/1.1 200 OK
Transfer-Encoding: chunked

20,12345

テンプレートが存在しない場合、エラーメッセージを含む以下の応答が取得されます。

HTTP/1.1 200 OK
Transfer-Encoding: chunked

40,"No template for this X-ID."

テンプレートが存在しない場合、空リクエスト時に使用したX-Idを用いてテンプレート登録要求を発行できます。

テンプレートは、CSV データ形式の SmartREST テンプレートを含めた単一要求によって登録することができます。テンプレート登録要求と通常の SmartREST 要求との違いは、テンプレート登録では行ごとに要求が処理されないという点です。

POST /s HTTP/1.0
Authorization: Basic ...
X-Id: ...
Transfer-Encoding: chunked

10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""Test Device"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"
11,201,,"$.c8y_IsDevice","$.id"

テンプレートが正常に登録されると、以下のような応答が返されます。

HTTP/1.1 200 OK
Transfer-Encoding: chunked

20,12345

構文

個々の要求用テンプレートおよび応答用テンプレートは、テンプレートデータから成る1つの行内に格納されます。要求用テンプレートはメッセージ識別子10で示され、応答用テンプレートは識別子11で示されます。これらのメッセージ識別子のうち1つが SmartREST 要求内で発生すると、リクエスト全体がテンプレートとして扱われます。したがって、10と11以外のメッセージ識別子はすべて、エラーとして処理されます。

要求用テンプレート

要求用テンプレートの構文は以下の通りです。

10,<ID>,<METHOD>,<URI>,<CONTENT>,<ACCEPT>,<PLACEHOLDER>,<PARAMS>,<TEMPLATE>

それぞれのパラメータについては下記の通りです。

• <ID>：要求用テンプレートのメッセージ識別子。
• <METHOD>：要求に使用する HTTP メソッド。GET、POST、PUT、DELETEがサポートされます。
• <URI>：リソース識別子。
• <CONTENT>：Content-Typeのヘッダーフィールド値。
• <ACCEPT>：Acceptのヘッダーフィールド値。 多くの場合<CONTENT>と同じになります。
• <PLACEHOLDER>：要求のURIおよびテンプレート文字列内でパラメータに置き換えられる文字列。
• <PARAMS>：テンプレートに要求されるパラメータの種類をスペースで区切ったリスト。要求URIおよびテンプレート文字列内でプレースホルダー文字列が発生する数は、指定されたパラメータの数と同一でなければなりません。
  • STRINGパラメータ：値が指定されていない場合に限りエラーが発生します。
  • UNSIGNEDパラメータ：供給されたパラメータが符号なし整数でない場合にエラーが発生します。
  • INTEGERパラメータ：供給されたパラメータが符号付き整数でない場合にエラーが発生します。
  • NUMBERパラメータ：供給されたパラメータが浮動小数点数でない場合にエラーが発生します。
  • DATEパラメータ：パラメータを日付として構文解析できない場合にエラーが発生します。
  • NOWパラメータはエラーを生じることがありません。要求パラメータは不要です。
• <TEMPLATE>：プレースホルダーがパラメータ値に置き換えられた後にプラットフォームへのペイロードとして送られることになる、実際のパラメータ文字列です。

要求の例を次に示します。

10,100,POST,/alarm/alarms,application/vnd.com.nsn.cumulocity.alarm+json,application/vnd.com.nsn.cumulocity.alarm+json,&&,UNSIGNED NOW,"{""source"":{""id"":""&&""},""type"":""c8y_MyAlarmFromSmartREST"",""text"":""This alarm was created by using SmartREST"",""severity"":""MAJOR"",""status"":""ACTIVE"",""time"":""&&""}"
10,200,POST,/measurement/measurements,application/vnd.com.nsn.cumulocity.measurement+json,application/vnd.com.nsn.cumulocity.measurement+json,&&,UNSIGNED UNSIGNED NOW UNSIGNED,"{""c8y_SmartMeasurement"":{""temp1"":{""value"":&&,""unit"":""C""},""temp2"":{""value"":&&,""unit"":""F""}},""time"":""&&"",""source"":{""id"":""&&""},""type"":""c8y_SmartMeasurement""}"
10,300,PUT,/inventory/managedObjects/&&,application/vnd.com.nsn.cumulocity.managedObject+json,,&&,,"{""c8y_Hardware"":{""model"":""&&"",""revision"":""&&""}}"
10,301,PUT,/alarm/alarms/&&,application/vnd.com.nsn.cumulocity.alarm+json,,&&,,"{""status"":""CLEARED""}"
10,302,PUT,/devicecontrol/operations/&&,application/vnd.com.nsn.cumulocity.operation+json,,&&,,"{""status"":""SUCCESSFUL""}"
10,600,GET,/identity/externalIds/c8y_Serial/&&,,,&&,,
10,601,GET,/devicecontrol/operations?deviceId=##&status=PENDING,,,##,,
10,602,GET,/inventory/managedObjects/&&,,,&&,,

要求の例は、Postman コレクションにも含まれています。 Postman コレクションでは、リクエストのセットは SmartREST > Register Request Templatesにあります。

例

デバイスの作成：

10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""Test Device"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"

それぞれのパラメータについては下記の通りです。

• 10：要求用テンプレートを表します。
• 100：要求用テンプレートのメッセージ識別子。
• POST：使用する HTTP メソッド。
• /inventory/managedObjects：リソース識別子。
• application/vnd.com.nsn.cumulocity.managedObject+json：Content-Type値
• application/vnd.com.nsn.cumulocity.managedObject+json：Accept値
• %%：プレースホルダー文字列。
• STRING：文字列でなければならない1つのパラメータをリクエストが許容することを指定します。

EXECUTINGへオペレーションを更新：

10,101,PUT,/devicecontrol/operations/%%, application/vnd.com.nsn.cumulocity.operation+json, application/vnd.com.nsn.cumulocity.operation+json,%%,INTEGER,"{""status"":""EXECUTING""}"

応答用テンプレート

応答用テンプレートの構文は以下の通りです。

11,<ID>,<BASE>,<COND>,<VALUE>[,<VALUE>]

それぞれのパラメータについては下記の通りです。

• <ID>：応答用テンプレートのメッセージ識別子。
• <BASE>：値の抽出元となるオブジェクトまたはオブジェクトリストを指す、ベースJSONパス。
• <COND>：存在確認を受ける条件付きJSONパス。パスが存在する場合に限り、値が抽出されます。
• <VALUE>：ベースオブジェクト内またはベースオブジェクトリストに含まれるオブジェクト内の抽出対象値を指すJSONパス。個数制限なく <VALUE>を指定することができます。

例

11,201,,"$.c8y_IsDevice","$.id"

それぞれのパラメータについては下記の通りです。

• 11：応答用テンプレートを表します。
• 201：応答用テンプレートのメッセージ識別子。
• $：ベースオブジェクトのJSONパスを空としているため、$が想定されます。
• $.c8y_IsDevice：c8y_IsDeviceというフラグメントをオブジェクトが有する場合に限り値が抽出されることを指定します。
• $.id：抽出される値(デバイスID)

複数のX-Idを伴うSmartRESTの使用

SmartRESTは、同一リクエスト内に異なる複数のX-Idが存在する場合でも、メッセージの送信を行うことができます。この場合、X-Idヘッダーは入力せず、代わりに個々のX-Idをそれぞれに対応する行に入力することになります。

メッセージの送信

X-Idを本文中で指定するには、以下の行を記述します。

15,myxid

次のX-Id行を入力するまで、後続の行は指定されたX-Idで処理されます。

15,myxid1
...
...
15,myxid2
...

メッセージの受信

複数のX-Idを用いてリクエストした場合、応答にも複数のX-Idの応答が含まれます。応答には、後続行がどのX-Idに属するものかを示す追加行が含まれます。 この行の2番目の値は、当該X-Idに続く行数を意味します。

87,2,myxid1
...
...
87,1,myxid2
...

テンプレートが登録済みか否かの確認

X-Id行を本文に含めることで、テンプレートがすでに存在するか確認することができます。

15,myxid1
15,myxid2
15,myxid3
15,myxid4

すべての行について、登録プロセス時に記載のような応答が返されます。 下記が例となります。

20,12345
20,12346
40,"No template for this X-ID."
20,12347

テンプレートの登録

テンプレート登録でも、本文中でX-Idを使用することができます。したがって、1回のリクエストで複数のテンプレートを作成することができます。

15,myxid1
10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""Test Device"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"
11,201,,"$.c8y_IsDevice","$.id"
15,myxid2
10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""Test Device"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"
11,201,,"$.c8y_IsDevice","$.id"

SmartRESTリアルタイム通知

Things Cloudプラットフォームで利用可能なリアルタイム通知のエンドポイントおよびチャネルをすべて、SmartREST構文でも使用することができます。 Bayeux protocol の概要の理解、リアルタイム通知向けに提供するエンドポイントおよびチャネルの説明は リアルタイム通知 API をご覧ください。

リアルタイム通知とSmartRESTの併用

リアルタイム通知においてSmartRESTを使用するようThings Cloudプラットフォームに指示するには、URLへ送られるすべてのリクエストにX-Idヘッダーを含める必要があります。

メッセージ識別子

ハンドシェイク

リクエスト例:

80

応答例:

Un1q31d3nt1f13r

チャネル接続

リクエスト例:

81,Un1q31d3nt1f13r,/mychannel

応答例:

エラー発生時を除き、当該チャネル接続について特定の応答は存在しません。

チャネル接続解除

リクエスト例:

82,Un1q31d3nt1f13r,/mychannel

応答例:

エラー発生時を除き、当該チャネル接続解除について特定の応答は存在しません。

接続

リクエスト例:

83,Un1q31d3nt1f13r

応答例:

応答は当該X-IdについてSmartREST経由で登録された応答用テンプレートによって設定されます。リアルタイム経由で受信した通知はすべて利用可能なテンプレートと併せて構文解析され、合致するすべてのテンプレートが、接続リクエストに対する応答として返されます。

接続維持:

Things Cloudプラットフォームは10分おきに接続断を検出するために、開いているロングポーリング接続経由でスペース文字を送信します。したがって、長時間にわたり開いたままの接続に対する応答には最初の行の先頭にスペース文字を含んでいる可能性があります。

接続解除

リクエスト例:

84,Un1q31d3nt1f13r

応答例:

エラー発生時を除き、当該接続解除について特定の応答は存在しません。

アドバイス応答

bayeuxプロトコルは、接続のタイムアウト、接続リクエスト間隔、および接続の応答のフォローアップのポリシーに対する推奨設定をクライアントに伝えるための特別なフラグメントを有しています。このアドバイスはSmartREST経由でも、応答内で個別の行として伝達されます。また、上述のリクエストのどの応答にも付加することができます。

応答形式:

86,<timeout>,<interval>,<reconnect policy>

タイムアウト(timeout)および間隔(interval)は、時間をミリ秒単位で定義します。再接続ポリシー(reconnect policy)値は、次の3つのいずれかになります。

• none:接続からの応答後に再接続しません。
• retry:接続からの応答後に再接続します。
• handshake:新たなハンドシェイクから開始します（例：clientIdが無効であるため／サーバーがセッションを閉じたため）。

アドバイス応答は、すべての値を埋める必要はありません。

例:

86,,10000,retry

複数のテンプレートを伴うチャネル接続

デバイスが複数のテンプレートを使用する場合（例：子デバイスが親デバイスと異なるテンプレートを有する場合）、これらのテンプレートをチャネル接続リクエストに加えることができます。その場合、サーバーはすべてのテンプレート（ヘッダーおよびチャネル接続ステートメントから）を使用して応答の構文解析を行います。

リクエスト例:

POST /notification/operations HTTP/1.0
Authorization: Basic ...
X-Id: mytemplate1

81,Un1q31d3nt1f13r,/mychannel,mytemplate2,mytemplate3

複数のテンプレートを使用する場合、行の構文解析にテンプレートを示す付加的な行を含みます。

87,{解析行数},{後続行の解析に使用するX-Id}

応答例:

HTTP/1.0 200 OK

87,2,mytemplate1
100,myvalue
101,myvalue2
87,1,mytemplate3
100,myvalue3

既定のメッセージ

SmartREST には、さまざまな既定のメッセージがあります。

リクエストメッセージ

応答メッセージ

エラーメッセージ