SmartREST

概要

このガイドではSmartRESTプロトコル、リクエスト時に使用するデータ形式のほか、SmartRESTテンプレートの詳細および登録フローについて説明します。既定メッセージのほか、エラーについても説明します。ステップごとのガイドについては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リクエストは、アクションに対応する一意の符号なし整数値からはじまり、後続にパラメータ値を記述する行で表わされます。

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(コンマ区切り値)形式を使用します。スムーズに通信するには、以下のルールに従わなければなりません。

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

以下は、上記のルールの例となります。

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テンプレート

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

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

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

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

ただし、

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

説明

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

リアルタイム通知と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つの値のうちのどれかを取ります。

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

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

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 行番号 無効なメッセージ識別子
45 行番号 無効なメッセージ引数
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}
値が{値の種別}: {値}でありません。