SmartREST

概要

このガイドでは SmartREST プロトコル、リクエスト時に使用するデータ形式のほか、 SmartREST テンプレートの詳細および登録フローについて説明します。既定メッセージのほか、エラーについても説明します。ステップごとの詳細な説明についてはREST開発者ガイドのSmartRESTをご覧ください。

プロトコル

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 リクエストは、アクションに対応する固有の符号なし整数値からはじまり後続にパラメータ値を記述する、1つの行で表されます。

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

HTTP/1.1 200 OK
Transfer-Encoding: chunked

200,1,123456,Request result

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

注記:Things Cloud REST APIからの応答が空になることが想定される場合(例えばマネージドオブジェクトの削除後)、 SmartREST からのレスポンスも空となります。 登録された応答テンプレートとの関連性はありません。

データ形式

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

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

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)では4つの処理モード、 PERSISTENTTRANSIENTQUIESCENTCEP が利用できます。 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 エンドポイントに送信されるデータを累積データベースに保存すると同時にリアルタイム処理に転送する必要がある場合は、 QUIESCENT 処理モードを指定する必要があります。この場合、リアルタイム通知を使用不可にする必要があります。現在、QUIESCENT処理モードはメジャーメントおよびイベントにのみ適用できます。

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

テンプレート

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

個々のリクエスト用テンプレートおよび応答用テンプレートは、メッセージ識別子と呼ばれる固有の数値識別子を有し、これを個々の SmartREST リクエスト行または応答行の最初の値により参照されます。既定のメッセージ識別子と重ならないよう、100で始まるメッセージ識別子を選択することを推奨します。

リクエスト用テンプレート

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

リクエスト用テンプレートには以下の情報が含まれます。

応答用テンプレート

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

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

登録プロセス

このガイドでは、主に 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 リクエスト内で発生すると、リクエスト全体がテンプレートとして扱われます。したがって、1011以外のメッセージ識別子はすべて、エラーとして処理されます。

リクエスト用テンプレート

リクエスト用テンプレートの構文は以下の通りです。

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

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

デバイスの作成:

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

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

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>]

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

11,201,,"$.c8y_IsDevice","$.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の概要の理解、リアルタイム通知向けに提供するエンドポイントおよびチャネルの説明はリアルタイム通知 を参照ください。

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

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

メッセージ識別子

メッセージ識別子 メッセージパラメータ 説明
80 None 固有のbayeux clientIdを返す初期ハンドシェイク
81 clientId,channel 所定のチャネルへの接続
82 clientId,channel 所定のチャネルからのチャネル接続解除
83 clientId 通知を受信するための接続の確立(long-polling)
84 clientId サーバーからのクライアントの接続解除

ハンドシェイク

リクエスト例:

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つのいずれかになります。

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

例:

86,,10000,retry

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

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

リクエスト例:

POST /devicecontrol/notifications 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 にはさまざまな既定のメッセージがあります。

リクエストメッセージ

メッセージ識別子 メッセージパラメータ 説明
10 テンプレートメッセージ識別子
メソッド
リソース識別子
Content MIME type
Accept MIME type
プレースホルダー
リクエストパラメータ
テンプレート文字列
リクエスト用テンプレートを表わします。このメッセージが本文に含まれる場合、本文全体が SmartREST テンプレートとして扱われるため、1011以外のメッセージはすべてエラーとなります
11 テンプレートメッセージ識別子
ベースJSONパス
条件付きJSONパス
値JSONパス
応答用テンプレートを表わしますこのメッセージが本文に含まれる場合、本文全体が SmartREST テンプレートとして扱われるため、1011以外のメッセージはすべてエラーとなります。
15 X-Id 後続行で有効となるX-Idを定義します。この行を使用する場合、X-Idヘッダーを使用してはなりません。
61 Device MO GId デバイスのブートストラップ処理中にデバイス認証情報のポーリングを行います。X-Idヘッダーが存在してはならず、新規デバイスリクエストを使用しなければなりません
80 None 固有のbayeux clientIdを返す初期ハンドシェイク。SmartRESTリアルタイム通知
81 clientId,channel 所定のチャネルへの接続。SmartRESTリアルタイム通知
82 clientId,channel 所定のチャネルからの切断。SmartRESTリアルタイム通知
83 clientId 通知を受信するための接続の確立(ロングポーリング)。SmartRESTリアルタイム通知
84 clientId サーバーからのクライアントの接続解除。SmartRESTリアルタイム通知

応答メッセージ

メッセージ識別子 メッセージパラメータ 説明
20 SmartREST テンプレートMO GId エコー応答メッセージ。テンプレートが見つかったか、または作成され、すべてOKです
40 なし テンプレートが見つかりませんでした
41 行番号(任意) テンプレート作成エラー
42 行番号 リクエスト行形式エラー
43 行番号 無効なメッセージ識別子
50 行番号
HTTP 応答コード
サーバーエラー。このメッセージは、SmartREST プロキシとプラットフォームとの間でエラーが生じた場合に発せられます
70 行番号
固有デバイス識別子
テナントID
ユーザー名
パスワード
認証情報と併せたデバイスブートストラップポーリング応答
86 タイムアウト、間隔、再接続ポリシー SmartRESTリアルタイム通知を使用するクライアント向けの設定アドバイス
87 行数、X-Id 後続応答行の作成に使用されたX-Idを示します

エラーメッセージ

メッセージ識別子 エラーメッセージ
41 Cannot create templates for already existing template object
すでに存在するテンプレートオブジェクトであるため、テンプレートを作成できません。
41 Duplicate message identifiers are not allowed
メッセージ識別子の重複は許可されません。
41 Bad request template definition
リクエスト用テンプレートの定義が誤っています。
41 Bad response template definition
応答用テンプレートの定義が誤っています。
41 Bad value type: …
値のタイプが誤っています。
41 Bad pattern
パターンが誤っています。
41 Not a valid message identifier for template creation
テンプレート作成に有効なメッセージ識別子ではありません。
41 Invalid JsonPath
無効なJSONパスです。
41 Using JsonPath to refer to a list of objects is not allowed for SmartRest
オブジェクトリストを参照するためのJSONパスの使用はSmartRESTの場合、許可されません。
41 Using Filters (?) in JsonPath is not allowed for SmartRest
JsonPathにおけるフィルター(?)の使用はSmartRESTの場合、許可されません
41 No content type supported for {GET or DELETE} templates.
{GETまたはDELETE}テンプレートに対応するコンテンツ型がありません。
41 No template string supported for {GET or DELETE} templates.
{GETまたはDELETE}テンプレートに対応するテンプレート文字列がありません。
41 No content type found for {POST or PUT} templates.
{POSTまたはPUT}テンプレートに対応するコンテンツ型が見当たりません。
41 No template string found for {POST or PUT} templates.
{POSTまたはPUT}テンプレートに対応するテンプレート文字列が見当たりません。
41 Values are only supported for templates with placeholder.
値はプレースホルダーを有するテンプレートに限り利用できます。
42 Malformed Request
リクエストの形式が誤っています。
43 Invalid message identifier
無効なメッセージ識別子です。
45 No arguments supported
対応する引数がありません。
45 Wrong number of arguments
引数の数が誤っています。
45 Value is not a {value type}: {value}
値が{値のタイプ}: {値}でありません。