登録プロセス

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

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

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

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

テンプレートがすでに存在する場合、次のレスポンスが取得されます。メッセージ識別子 20 はテンプレートがインベントリに存在することを意味し、パラメータ 123456 はテンプレートのマネージドオブジェクトの 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"":""このアラームは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 にインポートする方法については、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 ： 許容する Content-Type 値
• %% ： プレースホルダー文字列
• 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）