SmartREST 1.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!」です。

プロトコル

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,%%,STRING,"{""name"":""%%"",""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 には、さまざまな既定のメッセージがあります。

リクエストメッセージ

応答メッセージ

エラーメッセージ