フラグメントライブラリ

概要

デバイス統合ライブラリは、ソフトウェア管理や構成管理などのデバイス管理アクティビティのために Things Cloud で使用されるデータ構造を定義します。データ構造はフラグメントとして表され、これらをマネージドオブジェクト、オペレーション、その他のリソースの範囲内で使用することができます。フラグメントの概念の詳細については、Things Cloud のドメインモデルを参照してください。

次のセクションでは、デバイスの最も重要な機能、そのマネージドオブジェクト、およびそれらに対応するすべてのフラグメントについて説明します。Things Cloud UI、データベースで管理されているデバイスオブジェクト、およびデバイスとの通信内容との関係について説明します。

REST API を使用して Things Cloud の機能を公開する方法の詳細については、Things Cloud OpenAPI仕様を参照してください。

さらに、SmartREST の詳細と、次のセクションで説明するすべての SmartREST テンプレートの完全なリストについては、SmartREST を参照してください。

デバイス管理を開始するには、デバイス管理アプリケーションの デバイス メニューで すべてのデバイス タブを開きます。リスト内のデバイスをクリックすると、特定デバイスの「デバイスの詳細」が開きます。さまざまなタブと、それぞれのタブに関する特定の情報が表示されます。

備考

各タブと UI による関連する設定の詳細については、デバイス管理アプリケーション > デバイス詳細の表示も参照してください。

デバイスの詳細

このリストはデバイスフラグメントを通じて操作でき、表示されるタブはデバイスがサポートする機能によって異なります。これは主に c8y_SupportedOperations というフラグメントによって操作されます。このフラグメントの配列に格納された内容に基づいて、タブやボタンなどの機能が有効になります。例えば、c8y_SupportedOperations フラグメントに c8y_Firmware が含まれていると、デバイスの詳細 ページにファームウェアタブが表示され、デバイスはファームウェアオブジェクトを管理することができるようになります。

c8y_SupportedOperations フラグメント

c8y_SupportedOperations フラグメントには、次のフラグメントを追加することが可能です。

フラグメント	定義
c8y_Availability	デバイスのステータスとその可用性に関する情報を保持します
c8y_Command	ユーザーがデバイスとの双方向型セッションを実行できるようにします
c8y_Configuration	すべての制御文字を含むデバイスの完全な構成状態が含まれます
c8y_ConfigurationDump	デバイスのバイナリ構成ファイルの管理を許可します
c8y_DeviceProfile	デバイスのデバイスプロファイル機能を有効にします
c8y_DownloadConfigFile	設定ファイルをバイナリとしてダウンロードすることを許可します
c8y_Firmware	デバイスのファームウェアに関する情報を格納します
c8y_Hardware	デバイスの基本ハードウェア情報、例えばメーカー名やシリアル番号などを格納します
c8y_LogfileRequest	ログファイルを送信するようデバイスにリクエストし、そのログファイルをログビューアーで見ることができます
c8y_MeasurementRequestOperation	デバイスのアクションメニューに「メジャーメント取得」アクションを表示し、手動ステータス更新のためのオペレーションを送信します
c8y_Mobile	デバイスの内蔵モデムの機器識別情報（IMEI）や SIM カード（ICCIDなど）、基本的な接続性関連情報を保持します
c8y_Network	デバイス管理アプリケーションのネットワークタブにデータを送信し、ネットワーク情報を表示します
c8y_Position	アセットの地理的位置を緯度、経度および高度で報告します
c8y_Profile	対象プロファイルを通知します
c8y_Restart	デバイスを再起動します
c8y_Relay	デバイスリレーの切り替えを有効にします
c8y_RelayArray	配列内のデバイスリレーの切り替えを有効にします
c8y_SendConfiguration	ユーザーインターフェース経由での構成設定をリロードできます
c8y_SoftwareList	デバイスにインストールされているソフトウェアの全リストが含まれます
c8y_SoftwareUpdate	インストールまたはアンインストールするソフトウェアのリストが含まれます
c8y_UploadConfigFile	設定ファイルをバイナリとしてアップロードできるようにします

一般的なコンセプト

機能

デバイスは、独自のマネージドオブジェクトの c8y_SupportedOperations フラグメントを使用して、サポートされている機能を通知できます。フラグメント自体は文字列の配列です。このフラグメントは、次のセクションで説明する特定のユースケースに対する意味を持つ組込み操作、またはカスタム操作が含まれる場合があります。

PUT /inventory/managedObjects/<deviceId>

{
    "c8y_SupportedOperations": [
        "c8y_Restart",
        "c8y_Network"
    ]
}

フィールド	データ型	必須	詳細
c8y_SupportedOperations	array	はい	サポートされている操作の文字列の配列

いくつかの機能は、同様のコンセプトを持つ独自の c8y_Supported<...> フラグメントを導入しています。これらのフラグメントを使用すると、デバイスは特定の種類のログファイルまたは構成を処理する機能を通知することができます。

SmartREST例

114 静的テンプレートは、デバイスがサポートされている操作を通知するために使用できます。

114,c8y_Restart,c8y_Configuration,c8y_SoftwareList

現在のステータスの伝達

デバイスは、現在のステータスを Things Cloud に伝達する役割を担います。ステータスは通常、デバイス自体のマネージドオブジェクトで伝達されます。Things Cloud は、機能ごとに特定のフラグメントを提供します。デバイスは、ローカル状態の変更を検出するたびにこのデータを更新する必要があります。

実際には、デバイスが起動時、ローカル状態の変更を要求された場合、および外部の変更が検出される場合に、サポートされているすべての機能に関するローカル状態を公開する必要があることを意味します。

オペレーション処理

オペレーションは常にステータス PENDING で作成されます。デバイスは、ライフサイクル内のさまざまなステータスにオペレーションを移動する役割を担います。オペレーション処理を開始する前に、デバイスエージェントはそのステータスを EXECUTING に更新する必要があります。処理が完了した後、デバイスは結果に応じてオペレーションのステータスを SUCCESS または FAILED に設定する必要があります。

SmartREST 2.0

Things Cloud は、オペレーションのステータスを操作するために静的テンプレート 501、502、503 を提供します。これらのテンプレートは、オペレーションタイプを入力パラメーターとして受け取り、常に前のステータスの最も古いオペレーションを更新します。すべてのオペレーションをデバイスに到着する順に処理することをお勧めします。

デバイスは、デバイスコントロール API にクエリを送信するか、オペレーション JSON トピックをサブスクライブするか、または ID を含むカスタムレスポンステンプレート（つまり、ステンプレート 504、505、506）を使用してオペレーション ID を見つけることができます。これにより、既知の ID を持つオペレーションのステータスを設定できます。

オペレーション処理中のエラー処理

オペレーション処理中にエラーが発生した場合、デバイスはオペレーションのステータスを FAILED に設定し、エラーの理由をできるだけ説明する必要があります。これには、オペレーションが完全に期待通りに完了するのを妨げる予期しないエラー状態または予想されるエラー状態が含まれます。複数の異なるステップを持つ操作の 1 つのステップのみが失敗した場合でも、オペレーション全体を FAILED と見なす必要があります。

エラーが発生する前に発生したローカル状態の変更をロールバックする必要があるかどうかは、デバイスとそのユースケース次第です。オペレーションが失敗した後に状態の変更が残っている場合、デバイスはこの変更された状態を Things Cloud に伝える必要があります。

エージェントクラッシュ後の復旧

予期しない再起動の後、デバイスはそのステータスを完全に復旧する必要があります。これには、プラットフォームと通信されたすべてのステータスパラメータとすべての実行中のオペレーションが含まれます。ステータスの復旧は、デバイス上の現在の値でクラウドのすべての値を更新することで実行できます。実行中のオペレーションの復旧はより困難です。デバイスは、EXECUTING ステータスになったすべてのオペレーションを追跡することが期待されます。通常、デバイスは長時間実行されるオペレーションの情報を永続的なストレージに保持し、再開できるようにします。予期せぬシャットダウンやクラッシュが発生した場合、これが常に可能であるとは限りません。この場合、デバイスは実行中のすべての操作をキャンセルして、デバイス自体のステータスをリセットすることがあります。

GET /devicecontrol/operations?deviceId=<deviceId>&status=EXECUTING

{
  "operations": [
    {
      "creationTime": "2023-06-25T14:53:52.395Z",
      "deviceId": "123",
      "id": "101",
      "status": "EXECUTING",
      "c8y_Restart": {}
    },
    {
      "creationTime": "2023-06-25T14:57:29.089Z",
      "deviceId": "123",
      "id": "102",
      "status": "EXECUTING",
      "c8y_SendConfiguration": {}
    }
  ]
}

次に、ステータスを 1 つずつ変更する必要があります。

PUT /devicecontrol/operations/<operationId>

{
  "status": "FAILED"
}

SmartREST 2.0

静的テンプレート 507 を使用することもできます。このテンプレートは、指定されたタイプまたはすべてのタイプのすべてのオペレーションのステータスを EXECUTING から FAILED に変更します。

冪等性なケース

デバイスが既に存在する状態を要求するオペレーションを受け取った場合、そのオペレーションの処理方法はデバイス側に委ねられます。例えば、すでに存在するソフトウェアパッケージをインストールするようにデバイスに要求された場合です。通常、デバイスエージェントではこのようなケースを処理する方法として、スキップ、実行、失敗の 3 つがあります。すでにインストールされているソフトウェアパッケージの場合、次のオプションを選択することができます。

パッケージがすでにインストールされていると見なし、要求された状態がすでに存在するためインストールをスキップする
パッケージの再インストールを含め、通常通り処理を実行する
要求された状態は、コマンドが誤った前提条件の下で作成されたことを示している可能性があるため、操作を失敗させる

理想的なオプションは、ユースケースと具体的なオペレーションによって異なります。どのオプションが選択されているかに関係なく、デバイスはローカル状態と Things Cloud と通信されていることが一貫していることを確認する必要があります。

アラーム

アラームタブは、常にすべてのデバイスに表示されます。その内容は、デバイスから報告されたアラームステータスと、Analyticsやスマートルールなどの他のソースで埋められています。デバイスはそれらが発生した際にThings Cloudでアラームを発生させます。アラームの状態が解決されたら、デバイスは作成されたアラームのステータスを CLEARED に更新する必要があります。

アラームの発生

デバイスはいつでもアラームを発生させることができます。通常、アラームはデバイス環境の問題のステータスを通知するために使用されます。

POST /alarm/alarms

{
   "source": {
       "id": "4801"
   },
   "type": "c8y_TemperatureAlarm",
   "text": "CPU temperature too high",
   "severity": "MAJOR",
   "time": "2021-10-07T12:00:00.000Z"
}

フィールド	データ型	必須	詳細
source	object	はい	デバイスのID
type	string	はい	アラームのタイプ
text	string	はい	アラームステータスを説明するアラーム文字列
severity	string	はい	アラームの重大度
time	string	はい	アラーム発生時間

上記の必須パラメータに加えて、デバイスはアラームステータスに関してより詳細なカスタムフラグメントをアラームに含めることもできます。

SmartREST 例

Things Cloudは、には、デバイスの基本的なアラーム管理のための静的 SmartREST テンプレートがいくつか用意されています。異なる重要度のために 301 から 304 までのメッセージID が設定されています。

302,c8y_TemperatureAlarm,"CPU temperature too high"

アラームのクリア

デバイスは、ローカルアラームステータスが解決されたことを検出すると、アラームをクリアする必要があります。これは、アラームステータスをCLEAREDに更新することによって実行されます。

PUT /alarm/alarms/<alarmId>

{
   "status": "CLEARED"
}

フィールド	データ型	必須	詳細
status	string	はい	新しいアラームのステータス

SmartREST例

306の静的テンプレートは、指定されたタイプのアクティブなアラームをクリアするために用意されています。

306,c8y_TemperatureAlarm

クリティカルアラーム

デバイスが重大度クリティカルのアラームを発生させると、そのアラームがアクティブな間、デバイスは利用不可能と見なされます。サービスモニタリングタブの集約された可用性の概要は、この時間をオフラインとして反映します。

デバイスは、ユースケースを遂行するデバイスの能力に影響を与えるアラームステータスに限り、重要度「クリティカルアラーム」を使用する必要があります。

子デバイス

子デバイス タブには、すべての子デバイスのリストが表示されます。デバイスに子デバイスが割り当てられている場合にのみ使用できます。

子デバイスを親デバイスに割り当てる

デバイスを紐づけるには、親デバイスは、子デバイスの ID を含む次のリクエストをインベントリ API にPOSTする必要があります。

POST /inventory/managedObjects/<deviceId>/childDevices

{
   "managedObject": {
      "id": "28067400"
   }
}

フィールド	データ型	必須	詳細
managedObject.id	string	はい	紐づける子デバイスの ID

SmartREST例

既存のデバイスに子デバイスを追加するには、接続されたデバイスを接続し、子デバイス作成テンプレートを呼び出す必要があります。

101,uniqueChildId,myChildDevice,myChildType

子デバイスのゲートウェイ操作

エージェントマーカーフラグメント com_cumulocity_model_Agent を子デバイスではなく親デバイスで使用することで、デバイスを子デバイスの接続ゲートウェイとして効果的に宣言します。子デバイスはThings Cloudに直接接続されていませんが、デバイスとその統合を通してデータを送受信します。

この場合、子デバイスのオペレーションは、接続された親デバイスに配信されます。親デバイスは、含まれているデバイス ID またはその他の情報に基づいて、アドレス指定された子デバイスを判断する必要があります。そして、コマンドを正しい子デバイスに転送する必要があります。

Things Cloudの組み込みの静的 SmartREST 応答テンプレートには、対象となる子デバイスを決定するための最初のパラメータとして、常にデバイス識別子が含まれています。以下は、デバイス識別子が強調表示されたc8y_Restartオペレーションの 510 静的レスポンステンプレートの例です。

510,DeviceSerial

カスタム応答テンプレートも、最初のパラメータとして対象となるデバイスの外部IDを含んでいます。そちらにも同様の仕組みを実装することをお勧めします。

構成

構成タブでは、デバイス構成に 3 つの異なる形式を使用できます。

テキストベースの構成
レガシーファイルベースの構成
型指定されたファイルベースの構成

これらはすべて、デバイスが現在の設定をプラットフォームにアップロードし、ユーザーが新しい設定をデバイスにインストールするという類似のコンセプトに従っています。このタブは、デバイスが利用可能なフォーマットのサポートを知らせたときに表示されます。

テキストベースの構成

構成の最も基本的な形式は単純なテキストベースの構成です。ここでは、構成は文字列として直接保存され、転送されます。この形式は、マイクロコントローラベースのデバイスなど、人間が読める小さな構成ファイルのみに使用することをお勧めします。

デバイスの現在の構成状態は、デバイス自体のマネージドオブジェクト内の c8y_Configuration フラグメントで通信されます。これには、すべての制御文字を文字列として含む完全な構成が含まれています。エンコーディングが適切に行われるように特別な注意を払う必要があります。Things Cloud は UTF-8 文字をサポートしていますが、JSON ペイロードは JSON仕様、SmartREST ペイロードは SmartREST仕様に従ったエスケープが必要な場合があります。

転送データ量とデバイスのリソースを節約するため、オンデマンドでのみ現在の構成をアップロードすることをお勧めします。デバイスが現在の構成をプラットフォームにアップロードするために用意されたオペレーションは、以下の通りです。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Configuration": {
       "config": "c8y.url.http=https://management.cumulocity.com\nc8y.url.mqtt=mqtt.cumulocity.com\n"
   }
}

名称	タイプ	必須	説明
config	string	いいえ	デバイスが適用する完全な構成テキスト

現在のテキスト構成をアップロードする

c8y_SendConfiguration に c8y_SupportedOperations を含むデバイスの場合、構成タブには、デバイスから Things Cloud に構成をアップロードするためのボタンが用意されています。このボタンをクリックすると、c8y_SendConfiguration が作成されます。

{
   "c8y_SendConfiguration": {}
}

名称	タイプ	必須	説明
c8y_SendConfiguration	object	はい	デバイスに構成をアップロードさせるためのコマンドとして、オペレーションを指定した構成マーカーオブジェクトを送信する

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
c8y_Configuration フラグメントを使用して、現在の構成を独自のマネージドオブジェクトにアップロードする
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

c8y_SendConfiguration 操作に使用できる組み込みの静的応答テンプレートはありません。デバイスは、この機能を実装するためにカスタムテンプレートを作成する必要があります。このようなテンプレートとその使用がどのように機能するかについて、例を次に示します。

テンプレートの作成:
11,100,,c8y_SendConfiguration,deviceId

オペレーションの受信：

上記で作成したカスタムテンプレートを使用して c8y_SendConfiguration オペレーションを受信する
100,DeviceSerial,4801
オペレーションのステータスをEXECUTINGに設定する
501,c8y_SendConfiguration
113静的テンプレートを使用して現在の構成状態をアップロードする
113,"c8y.url.http=https://management.cumulocity.com\nc8y.url.mqtt=mqtt.cumulocity.com\n"
オペレーションのステータスを SUCCESSFULに設定する
503,c8y_SendConfiguration

テキスト構成のインストール

構成のインストールをサポートするデバイスは、c8y_Configuration に c8y_SupportedOperations を追加することで、通信することができます。構成タブはユーザーが設定した構成をデバイスに送信するためのボタンを提供します。その結果、このアクションにより、デバイスのマネージドオブジェクトで見つかったのと同じフラグメント署名を持つ c8y_Configuration オペレーションが作成されます。

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
c8y_Configuration フラグメント内に含まれる設定をインストールし適用する
デバイスのマネージドオブジェクトの c8y_Configuration フラグメントを更新する
オペレーションステータスをSUCCESSFULに設定する

SmartREST例

513 静的応答テンプレートは、 c8y_Configuration オペレーションを受信するために使用できます。

c8y_Configuration 操作を受信
513,DeviceSerial,"c8y.url.http=https://management.cumulocity.com\nc8y.url.mqtt=mqtt.cumulocity.com\n"
操作ステータスをEXECUTINGに設定
501,c8y_Configuration
含まれている構成をインストールして適用する
c8y_Configuration オペレーションを受信する
113,"c8y.url.http=https://management.cumulocity.com\nc8y.url.mqtt=mqtt.cumulocity.com\n"
オペレーションのステータスを SUCCESSFULに設定する
503,c8y_Configuration

レガシーファイルベースの構成

構成をファイルとして管理するデバイスは、レガシーファイルベースの構成を使用して基本的な形を実現できます。新しいデバイス統合では、より用途が広いため、代わりに型指定されたファイルベースの構成を実装することをお勧めします。

この方法では、構成をバイナリファイルとして格納および転送します。

備考

これは内部の Things Cloud リポジトリでのみ機能します。デバイスがレガシー構成にしか対応していない場合、外部URLによる構成はサポートされないことに注意してください。デバイス管理オブジェクトに保存されるID（以下に例を示します）は、常にインベントリに保存された内部バイナリを参照します。

現在のレガシー構成をアップロードする

デバイスは、c8y_UploadConfigFile に c8y_SupportedOperations を追加することで、現在の構成を Things Cloud にアップロードするためのサポートを通知できます。これにより、構成タブにある デバイスから新しいスナップショットを取得 ボタンが有効になります。これをクリックすると、デバイスに対して c8y_UploadConfigFile オペレーションが生成されます。

{
   "c8y_UploadConfigFile": {}
}

名称	タイプ	必須	説明
c8y_UploadConfigFile	object	はい	デバイスに構成ファイルをアップロードさせるためのコマンドとして、オペレーションを指定した構成ファイルマーカーオブジェクトをアップロードする

構成をアップロードする場合、デバイスは最初に構成ファイルを Things Cloud インベントリバイナリにアップロードしてから、インベントリ内に c8y_ConfigurationDump タイプのマネージドオブジェクトとして構成リポジトリのエントリを作成する必要があります。このオブジェクトには、アップロードしたばかりのファイルへのリンクが含まれている必要があります。このエントリは、ユーザーがリポジトリで目的の構成を見つけられるように、わかりやすい名前と説明で作成することをお勧めします。

POST /inventory/managedObjects

{
   "name": "myDevice configuration",
   "description": "Uploaded by myDevice on 2021-09-15T12:00:00+0200",
   "url": "https://demos.cumulocity.com/inventory/binaries/154702",
   "type": "c8y_ConfigurationDump"
}

名称	タイプ	必須	説明
name	string	はい	構成の名称
description	string	いいえ	構成の説明
url	string	はい	構成ファイルがアップロードされた URL
type	string	はい	構成リポジトリのエントリオブジェクトのタイプ。常に「c8y_ConfigurationDump」でなければならない

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
構成ファイルを Things Cloud のインベントリバイナリにアップロードする
構成リポジトリのエントリを作成する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

520 静的応答テンプレートがこの機能で使用できます。

c8y_UploadConfigFile オペレーションを受信する
520,DeviceSerial
オペレーションのステータスを EXECUTING に設定する
501,c8y_UploadConfigFile
REST を使用したインベントリバイナリ API へ構成をアップロードする
REST を使用したインベントリに構成リポジトリのエントリを作成する
オペレーションのステータスを SUCCESSFUL に設定する
503,c8y_UploadConfigFile

レガシー構成のインストール

構成をリモートでインストールできるデバイスは、c8y_DownloadConfigFile に c8y_SupportedOperations を追加して、これを知らせることができます。次に、構成タブに 構成をデバイスに送信 ボタンが表示されます。クリックすると、デバイスの c8y_DownloadConfigFile オペレーションが作成されます。

{
   "c8y_DownloadConfigFile": {
       "url": "https://demos.cumulocity.com/inventory/binaries/9100",
       "c8y_ConfigurationDump": {
           "id": "9200"
       }
   }
}

名称	タイプ	必須	説明
url	string	はい	構成ファイルの取得元となる URL
c8y_ConfigurationDump	object	はい	構成リポジトリのエントリオブジェクトの ID を含む構成ダンプ参照オブジェクト

指定されたURLから構成をダウンロードしインストールした後、デバイスは独自のマネージドオブジェクトで現在インストールされている構成を参照する必要があります。これは、ネストされた c8y_ConfigurationDump フラグメント全体をデバイス自体のマネージドオブジェクトに転送することで行われます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_ConfigurationDump": {
       "id": "9200"
   }
}

名称	タイプ	必須	説明
id	string	はい	参照される構成オブジェクトの ID

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
指定したURLから構成ファイルをダウンロードする
構成ファイルをインストールする
デバイスのマネージドオブジェクトに現在インストールされている構成ダンプを更新する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

521 静的応答テンプレートがこの機能で使用できます。

c8y_DownloadConfigFile オペレーションを受信する
521,DeviceSerial,https://demos.cumulocity.com/inventory/binaries/9100
オペレーションのステータスを EXECUTING に設定する
501,c8y_DownloadConfigFile
指定した URL から構成をダウンロードする
構成ファイルをインストールする
オペレーションのステータスを SUCCESSFUL に設定し、現在インストールされている c8y_ConfigurationDump フラグメントをそれとなく設定する
503,c8y_DownloadConfigFile

型指定されたファイルベースの構成

デバイス構成を管理する最も用途の広い方法は、型指定されたファイルベースの構成です。ここでは、デバイスは複数の構成ファイルを同時に管理できます。型指定されたファイル構成は、c8y_SupportedConfigurations フラグメントをデバイス自体のマネージドオブジェクトに追加することによって、デバイスに対してアクティブ化されます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_SupportedConfigurations": [
       "agent_conf",
       "ssh_conf"
   ]
}

名称	タイプ	必須	説明
c8y_SupportedConfigurations	array	はい	デバイスでサポートされている構成の文字列の配列

Things Cloud では、構成のタイプを検証したり、さらに処理したりすることはありません。プラットフォームの観点からは、これらは単純な文字列です。これらのタイプ文字列を構成ファイルに関連付けることは、デバイスエージェントの役割です。

SmartREST例

c8y_SupportedConfiguration フラグメントは、静的テンプレート119を使用してアップロードできます。
119,agent_conf,ssh_conf

現在の構成ファイルをアップロードする

レガシー構成と同様に、c8y_UploadConfigFile を c8y_SupportedOperations に追加することで、型指定された構成のアップロードが通知されます。この場合、ボタンをクリックすると、対象となる構成タイプを追加パラメータとして、非常に似た c8y_UploadConfigFile オペレーションが作成されます。

{
   "c8y_UploadConfigFile": {
       "type": "agent_conf"
   }
}

名称	タイプ	必須	説明
type	string	はい	アップロードする構成のタイプ

次に、デバイスは構成の種類と同じ種類のイベントを作成する必要があります。Things Cloud では、イベントがデバイスに自動的に関連付けられ、含まれている古いイベント (およびそのバイナリ添付ファイル) は保持ルールを使用して自動的にクリーンアップできるため、レガシーファイルベースの構成のようにインベントリではなく、ここでイベントを使用します。

POST /event/events

{
   "source": {
       "id": "4801"
   },
   "type": "agent_conf",
   "time": "2021-09-15T15:57:41.311Z",
   "text": "agent_conf upload requested"
}

名称	タイプ	必須	説明
source	object	はい	デバイスオブジェクトの ID
type	string	はい	アップロードされた構成のタイプ
time	string	はい	構成がアップロードされた ISO 日時
text	string	はい	構成のラベルテキスト

アップロードしたばかりのイベントに構成ファイルを添付するには、イベントバイナリAPIを使用する必要があります。ファイルはmultipart/form-dataリクエストを使用して添付されます。

POST /event/events/<eventId>/binaries

Host: https://<TENANT_DOMAIN>
Authorization: <AUTHORIZATION>
Accept: application/json
Content-Type: multipart/form-data;boundary="boundary"

--boundary
Content-Disposition: form-data; name="object"

{ "name": "agent.conf", "type": "text/plain" }
--boundary
Content-Disposition: form-data; name="file"; filename="agent.conf"
Content-Type: text/plain

c8y.url.http=https://management.cumulocity.com
c8y.url.mqtt=mqtt.cumulocity.com
--boundary--

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
構成タイプのイベントを作成する
構成ファイルをイベントに添付する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

Things Cloud は、型指定された c8y_UploadConfigFile オペレーションのための 526 静的 SmartREST テンプレートを提供します。

型指定された c8y_UploadConfigFileオペレーションを受信する
526,DeviceSerial,agent_conf
オペレーションのステータスを EXECUTING に設定する
501,c8y_UploadConfigFile
REST API を使用した config タイプのイベントを作成する
REST API を使用してターゲットの構成ファイルをイベントに添付する
オペレーションのステータスをSUCCESSFUL に設定する
503,c8y_UploadConfigFile

構成ファイルのインストール

型指定された構成のインストールもレガシー構成と類似の動作を行います。デバイスの c8y_SupportedOperations に c8y_DownloadConfigFile を追加すると、 構成をデバイスに送信ボタンの可用性が制御されます。クリックすると、構成タイプを含む c8y_DownloadConfigFile オペレーションが作成されます。

{
   "c8y_DownloadConfigFile": {
       "type": "agent_conf",
       "url": "https://demos.cumulocity.com/inventory/binaries/156719"
   }
}

名称	タイプ	必須	説明
type	string	はい	適用する構成のタイプ
url	string	はい	構成ファイルの取得元となる URL

デバイスが構成をダウンロードしてインストールしたとき、デバイス自体のマネージドオブジェクトにある特定タイプの現在インストールされている構成を更新する必要があります。これは、c8y_Configuration_<config type> フラグメントをデバイス自体のマネージドオブジェクトに追加することで行われます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Configuration_agent_conf": {
       "name": "agent_conf",
       "time": "2021-09-15T15:47:13.721Z",
       "type": "agent_conf",
       "url": "https://demos.cumulocity.com/inventory/binaries/156719"
   }
}

名称	タイプ	必須	説明
c8y_Configuration_agent_conf	object	はい	「c8y_Configuration_」という接頭語の後に、特定タイプの現在インストールされている構成の詳細を含んだ構成タイプが続くフラグメント名
name	string	はい	インストールされている構成ファイルのオプション名
time	string	はい	構成がいつ適用されたかを示す ISO 日時
type	string	はい	構成のタイプ
url	string	はい	構成の取得元URL

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
含まれているURLから構成ファイルをダウンロードする
構成ファイルをインストールする
デバイスの現在インストールされている構成を、デバイス自体のマネージドオブジェクトにある型指定された構成フラグメントで更新する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

524 静的なSmartREST応答テンプレートは、型指定された c8y_DownloadConfigFile オペレーションに使用でき、120静的テンプレートは、現在の構成をアップロードするために用意されています。

型指定された c8y_UploadConfigFile を受信する
524,DeviceSerial,https://demos.cumulocity.com/inventory/binaries/156719,agent_conf
オペレーションのステータスを EXECUTING に設定する
501,c8y_DownloadConfigFile
含まれているURLから構成ファイルをダウンロードする
対象の構成タイプとして構成をインストールする
現在インストールされている構成を設定する
120,agent_conf,https://demos.cumulocity.com/inventory/binaries/156719,agent_conf.txt,2021-09-15T15:47:13.721Z
オペレーションのステータスを SUCCESSFUL に設定する
503,c8y_DownloadConfigFile

接続

接続タブは、サードパーティの SIM 管理プラットフォームと統合され、Things Cloudデバイス管理アプリケーション内で SIM 管理機能を提供します。次のすべての条件が満たされた場合にデバイスのタブが表示されます。

接続マイクロサービスがサブスクライブされ、構成されている
デバイス管理オブジェクトには、MSISDN または ICCID プロパティが設定されたc8y_Mobileフラグメントが含まれている
デバイスによって参照される SIM は、テナント用に構成された SIM 管理プロバイダーによって管理される

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Mobile": {
       "msisdn": "380561234567",
       "iccid": "89100423481F445593U"
   }
}

名称	タイプ	必須	説明
msisdn	string	いいえ	インストールされている SIM の MSISDN
iccid	string	いいえ	インストールされている SIM の ICCID

構成されている接続プロバイダーに応じて、MSISDN または ICCID を使用して、デバイスに存在する SIM を識別できます。常に両方を c8y_Mobileフラグメントに含めることをお勧めします。 c8y_Mobileフラグメントに関連付けられるモバイル接続関連のプロパティは他にも多数ありますが、接続管理に関連するのは MSISDN または ICCID のみです。

SmartREST例

111 静的テンプレートは、デバイスがモバイル情報を通信するために提供されています。

111,1234567890,8930000000000000459,54353

デバイスの可用性

デバイスの可用性 タブには、デバイスの可用性と接続ステータスが表示されます。これを実現するには、デバイスは、デバイス自体のマネージドオブジェクトの c8y_RequiredAvailability フラグメントを使用して、必要な間隔を通信する必要があります。このアクションにより、デバイスの可用性と接続の監視がアクティブになります。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_RequiredAvailability": {
       "responseInterval": 15
   }
}

名称	タイプ	必須	説明
responseInterval	integer	いいえ	デバイスの予想される応答間隔 (分単位)。ゼロ以下の場合、デバイスはメンテナンスモードと見なされる

通常、デバイスはプラットフォームへの最初の接続時に既定値で必要な間隔を一度だけ設定する必要があります。その後の変更はプラットフォームユーザーに任せることができます。

SmartREST例

117 静的テンプレートは、SmartREST 接続デバイスに必要な可用性を設定するために提供されます。このテンプレートは、既存の必要な可用性構成を上書きしないため、デバイスの起動時にファイア・アンド・フォーゲットのアプローチで送信できます。

117,15

可用性の監視

c8y_RequiredAvailability フラグメントに設定された応答間隔は、プラットフォームがデバイスからデータを受信する予定間隔として使用されます。この間隔でデータが受信されない場合、デバイスはオフラインとしてマークされ、 c8y_UnavailabilityAlarm タイプのアラームが自動的に発生します。このアラームは、デバイスがデータを再送信すると自動的にクリアされます。デバイスからのそれ以上の操作は必要ありません。

Things Cloudによって計算された可用性情報は、デバイスのフラグメント c8y_Availability と c8y_Connection に格納されます。

"c8y_Availability": { "lastMessage": "2022-05-21...", "status": "AVAILABLE" },
"c8y_Connection": {"status":"CONNECTED"}

名称	タイプ	説明
lastMessage	Date	デバイスがThings Cloudに最後のメッセージを送信した日時。
status	String	現在のステータス（AVAILABLE、UNAVAILABLE、MAINTENANCEのいずれか）

以下のリクエストはデバイスのハートビートとみなされ、X-Cumulocity-Application-Key ヘッダーが設定されていない限り、デバイスを使用可能としてマークし、デバイスの最後のメッセージのタイムスタンプを更新します。

イベント、メジャーメント、アラームの作成（ソースとして指定されたデバイス）
空のPUTリクエスト、または {} または {"id": ... }という ID だけを持つリクエストの形で（付与されたIDを持つ）デバイスの更新。

備考

最後のメッセージ更新後、データベースに新しいステータスが保存されるまでに数分かかる場合があります。

接続監視

Things Cloudは、デバイスの接続監視も提供します。デバイスがオペレーションを受信することができる接続を確立すると、プラットフォームはこのデバイスを接続されたと見なします。これは、HTTPロングポーリング接続やMQTTセッションにも同様に適用されます。

監視対象デバイスは c8y_Connection に対して以下のいずれかのステータスを持ちます。

ステータス (文字列)	説明
CONNECTED	デバイス・プッシュ接続が確立される。
DISCONNECTED	`responseInterval` が0より大きく、デバイスがAVAILABLEでもCONNECTEDでもない。
MAINTENANCE	`responseInterval` が0以下であれば、デバイスはメンテナンス中である。

備考

デバイスがデバイスプッシュ経由で接続されていないが必要な応答間隔内にメッセージが送信された場合、c8y_Availability のステータスが CONNECTED でなくても、c8y_Connection のステータスは AVAILABLE になることがあります。

デバイス情報

デバイス情報 タブは、既定のデバイス情報を組み合わせたいくつかのウィジェットを含む定義済みのダッシュボードです。例えば、デバイスステータスウィジェットは、デバイス状態と最後に利用可能になった日時に関する情報を保持する c8y_Availability フラグメントから情報を取得します。詳細については、可用性を参照してください。

デバイスマーカー

デバイスは、インベントリ内で、独自のマネージドオブジェクトの c8y_IsDevice フラグメントを付与されます。このフラグメントを持つデバイスのみが、デバイス管理アプリケーションの すべてのデバイス のリストに表示されます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_IsDevice": {}
}

備考

SmartREST 2.0 で作成されたデバイスには、このフラグメントが自動的に含まれます。

エージェントマーカー

オペレーションを受信するために、デバイスは独自のマネージドオブジェクトでエージェントマーカーフラグメントを宣言する必要があります。これにより、プラットフォームは、このフラグメントを持たない子階層のすべての子デバイスに対して、デバイスにオペレーションを送ることができるようになります。

PUT /inventory/managedObjects/<deviceId>

{
   "com_cumulocity_model_Agent": {}
}

備考

SmartREST 2.0 で作成されたデバイスには、このフラグメントが自動的に含まれます。

デバイスの再起動

リモートで再起動できるデバイスは、デバイスの c8y_Restart フラグメントに c8y_SupportedOperations オペレーション追加して、この機能を通知することができます。すると、デバイス詳細 ページで、コンテキストメニューの中に 再起動 ボタンが表示されるようになります。

再起動操作

デバイス管理アプリケーションで 再起動 ボタンをクリックすると、次のような操作が送信されます。

{
  "c8y_Restart": {}
}

フィールド	データ型	必須	詳細
c8y_Restart	object	はい	オペレーションを再起動操作として指定する再起動マーカーフラグメント

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
リクエストされた再起動を実行する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

Things Cloud は、510 静的応答テンプレートを提供します。

デバイスは510静的応答テンプレートを介してコマンドを受信する
510,DeviceSerial
デバイスがオペレーションステータスをEXECUTINGに設定する
501,c8y_Restart
デバイスはオペレーションステータスを SUCCESSFUL に設定して、正常に実行されたことを確認する
503,c8y_Restart

ハードウェア情報

デバイスは、独自のマネージドオブジェクト内の c8y_Hardware フラグメントを使用して、基盤となるハードウェア情報をThings Cloud に通知することができます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Hardware": {
       "serialNumber": "1234567890",
       "model": "myModel",
       "revision": "1.2.3"
   }
}

フィールド	データ型	必須	詳細
serialNumber	string	いいえ	デバイスハードウェアのシリアル番号
model	string	いいえ	ハードウェア形式のテキスト識別子
revision	string	いいえ	ハードウェア改訂のテキスト識別子

SmartREST例

110 静的テンプレートを使用してハードウェア情報をアップロードします。通常、エージェントアプリケーションの起動時に一度実行できます。

110,1234567890,myModel,1.2.3

エージェント情報

すべてのデバイスは、実行中のエージェントすなわちThings Cloud と統合するソフトウェアに関する情報を提供する必要があります。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Agent": {
       "name": "thin-edge.io",
       "version": "0.6",
       "url": "https://thin-edge.io/",
       "maintainer": "Cumulocity"
   }
}

フィールド	データ型	必須	詳細
name	string	はい	エージェント名
version	string	はい	エージェントのバージョン
url	string	いいえ	エージェントのURL
maintainer	string	はい	エージェントの管理者

SmartREST例

122 の静的テンプレートを使用してエージェントの詳細をアップロードします。

122,thin-edge.io,0.6,https://thin-edge.io/,Cumulocity

エージェントの初期化時に一度だけ実行します。

リレー

リレーは、OPEN または CLOSED の状態になることができるバイナリ状態スイッチの一種です。リレーは、スマートエネルギーメーターを介して消費者の電源を接続または切断するなど、さまざまな目的で使用できます。マネージドオブジェクトでは、リレー制御モデルに制御の状態が含まれます。制御状態が変化すると、インベントリモデルを更新して新しい状態を含める必要があります。

単一リレー

単一のリレーを管理および監視するために、Things Cloudはリレー制御ウィジェットを提供しています。

リレー状態

デバイスは、マネージドオブジェクト内の c8y_Relay フラグメントを更新することで、リレー状態を通知できます。

PUT /inventory/managedObjects/<deviceId>

"c8y_Relay": {
  "relayState" : "OPEN"
}

名称	タイプ	必須	説明
c8y_Relay.relayState	string	はい	リレーの状態：「OPEN」または「CLOSED」

リレー状態の設定

リモートからのリレー位置変更をサポートするデバイスでは、c8y_Relay オペレーションを c8y_SupportedOperations に追加できます。その後、ユーザーはリレー制御ウィジェットでリレー位置の更新をリクエストできます。これにより、デバイスに対してフラグメントタイプ c8y_Relay のオペレーションが作成されます。

オペレーションの表現は、インベントリの表現と同じです。

"c8y_Relay": {
  "relayState" : "OPEN"
}

オペレーション	状態	説明
state	OPEN、CLOSED	OPEN はリレーを開く位置に、CLOSED は閉じる位置に命令します。

オペレーションを受信すると、デバイスは次のアクションを実行することが期待されます。

オペレーションのステータスをEXECUTINGに設定する
リレーの状態を設定する
マネージドオブジェクトに新しいリレーの状態を設定する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST 例

Things Cloud は、リレー状態を設定するための 518 静的レスポンステンプレートを提供します。

デバイスは 518 静的レスポンステンプレートを介してコマンドを受信する
518,OPEN
デバイスはオペレーションのステータスを EXECUTING に設定するbr> 501,c8y_Relay
デバイスはリレー状態を設定する
デバイスはオペレーションのステータスを SUCCESSFUL に設定することで、実行が成功したことを確認する
503,c8y_Relay

複数のリレー

複数のリレーを管理および監視するために、Things Cloud はリレーアレイ制御ウィジェットを提供します。

複数リレーの状態

デバイスは、マネージドオブジェクト内の c8y_RelayArray フラグメントを更新することで、複数のリレーの状態を通知できます。

PUT /inventory/managedObjects/<deviceId>

"c8y_RelayArray" : [
  "OPEN",
  "CLOSED",
  "CLOSED",
  "OPEN"
]

名称	タイプ	必須	説明
c8y_RelayArray	array	はい	リレー状態の文字列の配列

複数リレーの状態を設定する

リレー位置をリモートで変更することをサポートするデバイスは、c8y_SupportedOperationsにc8y_RelayArrayオペレーションを追加できます。その後、ユーザーはリレーアレイ制御ウィジェットでリレー位置の更新をリクエストできます。これにより、デバイスに対してフラグメントタイプ c8y_RelayArray のオペレーションが作成されます。

オペレーションの表現は、インベントリの表現と同じです。

"c8y_RelayArray" : [
"OPEN",
"CLOSED",
"CLOSED",
"OPEN"
]

オペレーション受信すると、デバイスは次のアクションを実行することが期待されます。

オペレーションのステータスを EXECUTING に設定する
リレーの状態をそれぞれの値に設定する
マネージドオブジェクトに新しいリレー状態を設定する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST 例

Things Cloudは、519 静的レスポンステンプレートを提供します。

デバイスは 519 静的レスポンステンプレートを介してコマンドを受信する
519,OPEN,CLOSED,CLOSED,OPEN
デバイスはオペレーションのステータスを EXECUTING に設定する
501,c8y_RelayArray
デバイスはオペレーションのステータスを SUCCESSFUL に設定することで実行が成功したことを確認し、503 静的テンプレート内の暗黙的なパラメータを使用してリレーアレイの状態を設定する
503,c8y_RelayArray,OPEN,CLOSED,CLOSED,OPEN

デバイスプロファイル

デバイスプロファイル タブには、追加されたデバイスプロファイルのさまざまなパラメータが表示されます。デバイスエージェントの観点から見ると、デバイスプロファイルは、ファームウェア更新、ソフトウェア更新、および型指定されたファイルベースのデバイス構成の組み合わせです。これらの機能をサポートするエージェントコードの大部分は再利用できます。

デバイスプロファイル機能は、デバイスが c8y_SupportedOperationsでc8y_DeviceProfileオペレーションを通知すると有効になります。デバイスプロファイル タブでは、ユーザーはデバイスにプロファイルを適用できます。これにより、設定されたプロファイルに従って c8y_DeviceProfile オペレーションが作成されます。ファームウェア、ソフトウェア、および構成が存在する場合、個々のオペレーション（c8y_Firmware, c8y_SoftwareUpdate、および型指定された c8y_DownloadConfigFile）とまったく同じように処理する必要があります。最初にファームウェア、2番目にソフトウェア、3番目に構成をインストールしてc8y_Profileオペレーションを実行し、その後のアクションが、それ以前のアクションを上書きする可能性を最小限に抑えることをお勧めします。

{
   "profileName": "my profile",
   "profileId": "158751",
   "c8y_DeviceProfile": {
       "software": [
           {
               "name": "curl",
               "action": "install",
               "version": "2.3.4",
               "url": "http://my.url.com"
           },
           {
               "name": "cumulocity_agent",
               "action": "install",
               "version": "1.2.3",
               "url": "https://cumulocity.com/agent"
           }
       ],
       "configuration": [
           {
               "name": "ssh_conf",
               "type": "ssh_conf",
               "url": "http://cumulocity.com/conf"
           },
           {
               "name": "agent_conf",
               "type": "agent_conf",
               "url": "https://demos.cumulocity.com/inventory/binaries/156719"
           }
       ],
       "firmware": {
           "name": "device_fw",
           "version": "1.0.1",
           "url": "https://cumulocity.com/fw"
       }
   }
}

名称	タイプ	必須	説明
profileName	string	はい	適用されているデバイスプロファイル名
profileId	string	はい	デバイスプロファイルオブジェクトへのID参照
c8y_DeviceProfile	object	はい	インストールに必要なすべての情報を含むデバイスプロファイルオブジェクト
c8y_DeviceProfile.software	array	いいえ	インストールまたは削除するソフトウェアオブジェクトの配列
c8y_DeviceProfile.software.name	string	はい	ソフトウェアパッケージ名
c8y_DeviceProfile.software.action	string	はい	ソフトウェアをインストールまたは削除する必要があるかどうかを説明するパッケージで実行するアクション
c8y_DeviceProfile.software.version	string	はい	ソフトウェアのバージョン
c8y_DeviceProfile.software.url	string	はい	ソフトウェアバイナリの取得元となる URL
c8y_DeviceProfile.configuration	array	いいえ	適用する構成オブジェクトの配列
c8y_DeviceProfile.configuration.name	string	はい	構成の名前
c8y_DeviceProfile.configuration.type	string	はい	構成の種類
c8y_DeviceProfile.configuration.url	string	はい	構成ファイルの取得元となる URL
c8y_DeviceProfile.firmware	object	いいえ	ターゲットファームウェアの詳細を含むファームウェアオブジェクト
c8y_DeviceProfile.firmware.name	string	はい	インストールするファームウェアの名前
c8y_DeviceProfile.firmware.version	string	はい	ファームウェアのバージョン
c8y_DeviceProfile.firmware.url	string	はい	ファームウェアバイナリの取得元となるURL

デバイスが c8y_Profile オペレーションを受信したら、最初に独自のマネージドオブジェクトでターゲットプロファイルを通知する必要があります。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Profile": {
       "profileName": "my profile",
       "profileId": "158751",
       "profileExecuted": false
   }
}

名称	タイプ	必須	説明
profileName	string	はい	デバイスプロファイル名
profileId	string	はい	デバイスプロファイルオブジェクトの ID 参照
profileExecuted	Boolean	はい	プロファイルが完全に適用されているかどうかを示すインジケーター。このコンテキストでは false にする

3つの各セクションを完了した後、デバイスはフラグメントc8y_Firmware、c8y_SoftwareList、および c8y_Configuration_<type> を使用した個々のオペレーションで説明された同じ方法で、独自のマネージドオブジェクトで現在の状態を通知する必要があります。次に、デバイスは、profileExecuted プロパティを true に更新して、マネージドオブジェクトにインストールされているプロファイルの状態を更新する必要があります。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Profile": {
       "profileName": "my profile",
       "profileId": "158751",
       "profileExecuted": true
   }
}

名称	タイプ	必須	説明
profileName	string	はい	デバイスプロファイル名
profileId	string	はい	デバイスプロファイルオブジェクトの ID 参照
profileExecuted	Boolean	はい	プロファイルが完全に適用されているかどうかを示すインジケーター。このコンテキストでは true にする

デバイスは、次のアクションを実行する必要があります。

オペレーションステータスをEXECUTINGに設定する
デバイス独自のマネージドオブジェクトに c8y_Profile フラグメントを profileExecuted = false で設定する
ファームウェアが含まれている場合はインストールし、独自のマネージドオブジェクトの c8y_Firmware フラグメントを更新してインストールを完了する
ソフトウェアが含まれている場合はインストールし、独自のマネージドオブジェクトの c8y_SoftwareList フラグメントを更新してインストールを完了する
構成が含まれている場合はインストールし、独自のマネージドオブジェクト内の構成ごとにc8y_Configuration_<type> ラグメントを更新してインストールを完了する
デバイスのマネージドオブジェクトに c8y_Profile フラグメントを profileExecuted = true で設定する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST 例

Things Cloud で提供されるファームウェア、ソフトウェア、および構成の静的テンプレートに加えて、デバイスプロファイルの処理に使用できる特定のテンプレートがあります。527 応答テンプレートは、オペレーションを受信するように設計されています。121 静的テンプレートを使用して、デバイスプロファイルの現在の状態を設定できます。

c8y_DeviceProfile オペレーションを受信する

527,DeviceSerial,$FW,device_fw,1.0.1,https://cumulocity.com/fw,false,,$SW,curl,2.3.4,http://my.url.com,install,cumulocity_agent,1.2.3,https://cumulocity.com/agent,install,$CONF,http://cumulocity.com/conf,ssh_conf,https://demos.cumulocity.com/inventory/binaries/156719,agent_conf

オペレーションのステータスを EXECUTING に設定する
501,c8y_DeviceProfile
ターゲットプロファイルを設定する
121,false,
ダウンロード、インストールおよびファームウェアのインストール状態を確認する
115,device_fw,1.0.1,https://cumulocity.com/fw
ダウンロード、インストールおよびソフトウェアのインストール状態を確認する
116,curl,2.3.4,http://my.url.com,cumulocity_agent,1.2.3,https://cumulocity.com/agent
ダウンロード、インストールおよび各構成のインストール状態を確認する
120,ssh_conf,http://cumulocity.com/conf,config,
120,agent_conf,https://demos.cumulocity.com/inventory/binaries/156719,agent.cfg,
ターゲットプロファイルを実行済みとして設定する
121,true,
オペレーションのステータスを SUCCESSFUL に設定する
503,c8y_DeviceProfile

ファームウェア

ファームウェアタブには、現在インストールされているファームウェアが表示され、ユーザーは別のバージョンをインストールすることができます。デバイスは、一度に1つのファームウェアしかインストールすることができません。Things Cloudでどのようなファームウェアが使用できるかは、デバイスに依存します。典型的な使用例としては、オペレーティングシステム、マイクロコントローラファームウェア、またはBIOSがあります。

ファームウェアは、完全インストールまたはパッチを使用してインストールできます。どのバリアントがデバイスに送信されるかは、ファームウェアがファームウェアリポジトリでどのように作成されたかによって異なります。

インストールされたファームウェア

デバイスは、最初に現在の状態をプラットフォームに通知する必要があります。次に、インストールされたファームウェアをデバイス独自のマネージドオブジェクトのc8y_Firmwareフラグメントに入力する必要があります。デバイスは、起動時およびローカルの変更が検出されたときに、現在の状態を Things Cloud にアップロードする必要があります。これには、更新がリモートでトリガーされた場合も含まれます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Firmware": {
       "name": "ubuntu core",
       "version": "20.04.2",
       "url": "http://test.com"
   }
}

フィールド	データ型	必須	詳細
name	string	はい	ファームウェアパッケージ名
version	string	はい	ファームウェアのバージョン識別子
url	string	いいえ	ファームウェアファイルの取得元の場所を示す URL

ソフトウェアと同様に、URLフィールドはオプションであり、デバイスによって省略できます。

SmartREST例

115静的テンプレートは、デバイスが現在インストールされているファームウェアの状態を通信するために使用できます。

115,ubuntu core,20.04.3,http://test.com

ファームウェアイメージのインストール

ユーザーがインストールするために完全なファームウェアイメージを選択すると、デバイスのマネージドオブジェクトで見つけたものと同様の c8y_Firmwareフラグメントを持つオペレーションが作成されます。このオペレーションは、デバイスによって達成される必要がある望ましい状態と見なす必要があります。

{
   "c8y_Firmware": {
       "name": "ubuntu core",
       "version": "20.04.3",
       "url": "http://test.com"
   }
}

フィールド	データ型	必須	詳細
name	string	はい	ファームウェアパッケージ名
version	string	はい	ファームウェアのバージョン識別子
url	string	はい	ファームウェアファイルのダウンロード元の場所を示す URL

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
ファームウェアイメージをインストールする
デバイス独自のマネージドオブジェクトにインストールされているファームウェアの状態を更新する
オペレーションのステータスを SUCCESSFUL に設定する

デバイスを更新すると、基本的なシステムコンポーネントが変更されることがよくあります。これは、常に重要なオペレーションと見なす必要があります。デバイスは、Things Cloudへのすべての接続パラメータがアップグレード中も保持され、後で接続を再開できることを確認する必要があります。デバイスが、必要に応じてロールバックできるA/Bファームウェア切り替えメカニズムを使用しているかを確認することをお勧めします。

SmartREST例

Things Cloudには、ファームウェアイメージのインストールを処理するための 515 静的応答テンプレートが用意されています。

c8y_Firmware オペレーション（イメージ）を受信する
515,DeviceSerial,ubuntu core,20.04.3,http://test.com
オペレーションのステータスを EXECUTING に設定する
501,c8y_Firmware
ファームウェアイメージをインストールする
インベントリでデバイスのインストール済みファームウェア状態を更新する
115,ubuntu core,20.04.3,http://test.com
オペレーションのステータスを SUCCESSFUL に設定する
503,c8y_Firmware

ファームウェアパッチのインストール

ユーザーがデバイスにインストールするファームウェアパッチを選択した場合、c8y_Firmwareオペレーションが作成されます。この場合、ファームウェアパッチのインストールに役立つ2つの追加パラメータが含まれています。デバイスエージェントは、通常のインストールではなく、ファームウェアパッチプロセスを担当します。

{
   "c8y_Firmware": {
       "name": "ubuntu core",
       "version": "20.04.4",
       "url": "http://test.com",
       "dependency": "20.04.3",
       "isPatch": true
   }
}

フィールド	データ型	必須	詳細
name	string	はい	ファームウェア名
version	string	はい	ファームウェアバージョン識別子
url	string	はい	ファームウェアファイルの場所を示す URL
dependency	string	はい	パッチが依存するファームウェアのバージョン
isPatch	Boolean	はい	ファームウェアパッケージがパッチであることを示すインジケーター

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
現在インストールされているファームウェアのバージョンが依存バージョンと一致するかどうかを確認する
ファームウェアパッチをインストールする
デバイス独自のマネージドオブジェクトにインストールされているファームウェアの状態を更新する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

Things Cloudは、ファームウェアパッチのインストールを処理するための 525 静的応答テンプレートを提供します。これは、515 テンプレートと類似の動作を行いますが、5 番目のパラメータとして依存性パラメータが追加されています。このテンプレートはパッチに対してのみトリガーされるため、完全なイメージではなくパッチがインストールされるべきという事実は暗黙の了解となっています。

c8y_Firmware オペレーション（パッチ）を受信する
525,DeviceSerial,ubuntu core,20.04.3,http://test.com,20.04.3
オペレーションのステータスを EXECUTING に設定する
501,c8y_Firmware
現在インストールされているファームウェアのバージョンと依存バージョンが一致するかどうかを確認する
ファームウェアイメージをインストールする
インベントリでデバイスのインストール済みファームウェア状態を更新する
115,ubuntu core,20.04.3,http://test.com
オペレーションのステータスを SUCCESSFUL に設定する
503,c8y_Firmware

識別子

識別子 タブには、デバイスに関連付けられているすべての ID が表示されます。使用可能な ID がない場合、タブは表示されません。ID は一意のデバイス識別子 (IMEI や SN など) から Things Cloudのデバイスのマネージドオブジェクトにマップされます。これにより、デバイスはマネージドオブジェクトを見つけることができます。

REST

MQTT (SmartREST 2.0)

MQTT のコンテキストでは、クライアント ID はデバイスの外部 ID として使用されます。接続時に、MQTT クライアント ID を使用して、接続をインベントリ内のデバイスに自動的に関連付けられます。デバイスで追加の ID バインドを作成する必要はありません。これらは、100 および 101 テンプレートが使用されるときに内部的に作成されます。データを作成するすべてのメッセージは、デバイスコンテキストに自動的に関連付けられます。

Things Cloudに接続されたデバイスによるデバイス作成:

100,createdDeviceName,deviceType

Things Cloud に接続されているデバイスの子デバイス作成:

101,uniqueChildId,myChildDevice,myChildType

ログ

ログタブは、デバイスからログを抽出するために使用されます。ログタブは、デバイスの c8y_SupportedOperations に c8y_LogfileRequest フラグメントが存在する場合に使用できます。サポートするログの種類の配列を保持する c8y_SupportedLogs フラグメントが含まれている必要があります。ログの種類は、後でログがリクエストされたときに参照されます。

サポートされているログ設定

サポートされているログタイプは、デバイスが独自のマネージドオブジェクトの c8y_SupportedLogs フラグメントを使用して、デバイスによって通知されます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_SupportedLogs": [
      "syslog",
      "dmesg"
   ]
}

フィールド	データ型	必須	詳細
c8y_SupportedLogs	array	はい	サポートされているログタイプの文字列の配列

SmartREST例

118 静的テンプレートは、デバイスのサポートされているログを通知するために使用できます。

118,syslog,dmesg

ログファイルのアップロード

ユーザーがログタブを使用してデバイスからログファイルをリクエストすると、c8y_LogfileRequest オペレーションが作成されます。

{
   "c8y_LogfileRequest": {
       "searchText": "kernel",
       "logFile": "syslog",
       "dateTo": "2021-09-22T11:40:27+0200",
       "dateFrom": "2021-09-21T11:40:27+0200",
       "maximumLines": 1000
   }
}

フィールド	データ型	必須	詳細
dateFrom	string	はい	ログ行の開始日
dateTo	string	はい	ログ行の終了日
logFile	string	はい	特定デバイスのログの種類 (c8y_SupportedLogs)
searchText	string	はい	個々のログ行に適用するテキストフィルター
maximumLines	string	はい	転送する最大行数

デバイスがログを収集すると、それらをファイルとして Things Cloudにアップロードします。イベントを作成し、ログファイルをそのイベントのバイナリ添付ファイルとしてアップロードすることをお勧めします。バイナリ添付ファイルを持つ他のイベントとの競合を避けるため (例えば、型指定されたファイルベースの構成など)、イベントタイプとして c8y_Logfile を使用することをお勧めします。このようなイベントの例を次に示します。

POST /event/events

{
   "source": {
       "id": "4801"
   },
   "type": "c8y_Logfile",
   "time": "2021-09-15T15:57:41.311Z",
   "text": "syslog log file"
}

フィールド	データ型	必須	詳細
source	string	はい	デバイスID
type	string	はい	ログファイルを保持するイベントのタイプは常に `c8y_Logfile` である必要があります
time	string	はい	イベントが発生した時間
text	string	はい	イベントテキスト

必要に応じて、デバイスはオペレーションから c8y_LogfileRequest フラグメントまたはオペレーション ID をイベントに含めることもできます。ファイルは、イベント ID とイベントバイナリAPI を使用してイベントに添付されます。

POST /event/events/<eventId>/binaries

Host: https://<TENANT_DOMAIN>
Authorization: <AUTHORIZATION>
Accept: application/json
Content-Type: multipart/form-data;boundary="boundary"

--boundary
Content-Disposition: form-data; name="object"

{ "name": "syslog.txt", "type": "text/plain" }
--boundary
Content-Disposition: form-data; name="file"; filename="syslog.txt"
Content-Type: text/plain

Oct 25 13:28:53 wtp kernel: [  719.554855] sd 6:0:0:0: [sdb] Write Protect is off
Oct 25 13:28:53 wtp kernel: [  719.554864] sd 6:0:0:0: [sdb] Mode Sense: 03 00 00 00
Oct 25 13:28:53 wtp kernel: [  719.555033] sd 6:0:0:0: [sdb] No Caching mode page found
--boundary--

アップロードが正常に完了したら、デバイスはアップロードされたファイルへの URL をオペレーションの c8y_LogfileRequestフラグメントに含める必要があります。リンクはプロパティ “file” として表示する必要があります。このアクションは、オペレーションのステータスのSUCCESSFUL 設定と組み合わせることができます。

PUT /devicecontrol/operations/<operationId>

{
   "status": "SUCCESSFUL",
   "c8y_LogfileRequest": {
       "searchText": "kernel",
       "logFile": "syslog",
       "dateTo": "2021-09-22T11:40:27+0200",
       "dateFrom": "2021-09-21T11:40:27+0200",
       "maximumLines": 1000,
       "file": "https://demos.cumulocity.com/event/events/157700/binaries"
   }
}

フィールド	データ型	必須	詳細
status	string	はい	オペレーションのステータス
dateFrom	string	はい	ログ行の開始日
dateTo	string	はい	ログ行の終了日
logFile	string	はい	特定デバイスのログの種類 (c8y_SupportedLogs)
searchText	string	はい	個々のログ行に適用するテキストフィルター
maximumLines	integer	はい	転送する最大行数
file	string	はい	ログファイルがアップロードされた URL

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
オペレーションで指定されたログファイルの読み込み、フィルター処理、およびトリミングする
ログファイルイベントを作成する
ログファイルをバイナリ添付ファイルとして上記のイベントにアップロードする
オペレーションのステータスを SUCCESSFUL に設定し、アップロードされたログファイルの URL を含める

SmartREST例

Things Cloud は、c8y_LogfileRequest オペレーションを受信するための 522 静的応答テンプレートを提供します。ログファイルがアップロードされると、デバイスは503静的テンプレートの暗黙的なパラメータ機能を使用してオペレーションのステータスを設定し、同時にファイルリンクを提供できます。

c8y_LogfileRequest オペレーションを受信する
522,DeviceSerial,syslog,2021-09-21T11:40:27+0200,2021-09-22T11:40:27+0200,ERROR,1000
オペレーションステータスを EXECUTING に設定する
501,c8y_LogfileRequest
REST APIを使用してログファイルイベントを作成する
REST APIを使用して、イベントバイナリとして新しく作成されたイベントにログファイルをアップロードする
オペレーションのステータスを SUCCESSFUL に設定し、アップロードされたファイルの URL を指定する
503,c8y_LogfileRequest,"https://demos.cumulocity.com/event/events/157700/binaries"

手動ステータス更新

デバイスがプラットフォームにステータス更新を手動でアップロードする必要がある場合、デバイスのアクションバーにある 計測値を取得 ボタンを使用できます。これは、デバイスの c8y_SupportedOperations に c8y_MeasurementRequestOperation が含まれていると表示されます。

このアクションは、c8y_MeasurementRequestOperationオペレーションを作成します。

{
    "c8y_MeasurementRequestOperation": {}
}

リクエストされた利用可能なデータポイントのセットを指定するための、追加の構成はありません。完全なデバイス状態のアップロードをトリガーすることをお勧めします。

オペレーションを受信すると、デバイスは次のアクションを実行することが期待されます。

オペレーションのステータスを EXECUTING に設定する
すべてのデータポイントの現在のステータスをプラットフォームにアップロードする
オペレーションのステータスを SUCCESSFUL に設定する

計測値（メジャーメント）

計測値（メジャーメント） タブでは、デバイスから送信されたメジャーメントフラグメントごとに 1 つのグラフが作成されます。これは、含まれているすべてのシリーズが1つのグラフにまとめて表示されることを意味します。したがって、デバイス統合は、このグループ化を考慮して行う必要があります。その可視性は、デバイスでサポートされているメジャーメントによって制御されます。 Things Cloud は、以前に送信されたメジャーメントに基づいて、デバイスでサポートされているメジャーメントを自動的かつ動的に入力します。つまり、計測値（メジャーメント）タブは、デバイスが最初のメジャーメントを送信した後に効果的に表示されます。

SmartREST例

メッセージ ID の 2xx の範囲でメジャーメントを作成するために使用できる静的テンプレートがいくつかあります。200 の静的テンプレートを使用して、動的なフラグメントとシリーズを含むメジャーメントを作成します。

200,c8y_Temperature,T,25

このテンプレートは多くのユースケースで使用できますが、フラグメントとシリーズを動的に定義する必要がない場合は、すべてのユースケースでカスタムテンプレートを作成することをお勧めします。

ネットワーク

ネットワーク タブには、ネットワーク情報が表示されます。c8y_Network フラグメントがデバイスのマネージドオブジェクトに存在するかどうかが表示されます。WAN、LAN、DHCP の 3 つのサブセクションがあります。これらは、ネストされたフラグメント c8y_WAN、c8y_LAN、c8y_DHCP によって、それぞれアクティブ化できます。

ネットワークステータス

デバイスは、デバイス独自のマネージドオブジェクトのc8y_Networkフラグメントを使用して、現在のローカルネットワークのステータスと構成をプラットフォームに通知できます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Network": {
       "c8y_LAN": {
           "netmask": "255.255.255.0",
           "ip": "192.168.128.1",
           "name": "br0",
           "enabled": 1,
           "mac": "00:60:64:dd:a5:c3"
       },
       "c8y_WAN": {
           "password": "user-password",
           "simStatus": "SIM OK",
           "authType": "chap",
           "apn": "example.apn.com",
           "username": "test"
       },
       "c8y_DHCP": {
           "dns2": "1.1.1.1",
           "dns1": "8.8.8.8",
           "domainName": "my.domain",
           "addressRange": {
               "start": "192.168.128.100",
               "end": "192.168.128.199"
           },
           "enabled": 1
       }
   }
}

名称	タイプ	必須	説明
c8y_LAN	object	いいえ	ローカルネットワーク情報を含むオプションのネストされたオブジェクト
c8y_LAN.netmask	string	いいえ	ネットワークインターフェースに構成されたサブネットマスク
c8y_LAN.ip	string	いいえ	ネットワークインターフェースに構成されたIPアドレス
c8y_LAN.name	string	いいえ	ネットワークインターフェースの識別子
c8y_LAN.enabled	integer	いいえ	インターフェースが有効になっているかどうかを示すインジケーター
c8y_LAN.mac	string	いいえ	ネットワークインターフェースのMACアドレス
c8y_WAN	object	いいえ	モバイルインターネット接続インターフェースのステータスを記述する、オプションのネストされたオブジェクト
c8y_WAN.password	string	いいえ	SIM接続パスワード
c8y_WAN.simStatus	string	いいえ	SIM接続ステータス
c8y_WAN.authType	string	いいえ	SIM接続で使用される認証タイプ
c8y_WAN.apn	string	いいえ	インターネットアクセス用のAPN
c8y_WAN.username	string	いいえ	SIM 接続ユーザー名
c8y_DHCP	object	いいえ	DHCP サーバーのステータスに関する情報を含むオプションのネストされたオブジェクト
c8y_DHCP.dns1	string	いいえ	最初に構成された DNS サーバー
c8y_DHCP.dns2	string	いいえ	2 番目に構成された DNS サーバー
c8y_DHCP.domainName	string	いいえ	ドメイン名
c8y_DHCP.addressRange.start	string	いいえ	DHCP クライアントに割り当てられたアドレス範囲の開始
c8y_DHCP.addressRange.end	string	いいえ	DHCP クライアントに割り当てられたアドレス範囲の終了
c8y_DHCP.enabled	integer	いいえ	DHCPサーバーが有効になっているかどうかを示すインジケーター

ネットワーク構成の設定

デバイスがc8y_SupportedOperationsにc8y_Networkオペレーションを含んでいる場合、ユーザーはネットワークタブでデバイスのネットワーク構成を更新できます。変更された構成は、デバイスのマネージドオブジェクトに存在するものと非常に似たフラグメントとしてc8y_Networkオペレーションとして送信されます。このオペレーション内のc8y_Networkフラグメントには、1つ以上のネストされたフラグメントが含まれる場合があります。

{
   "c8y_Network": {
       "c8y_LAN": {
           "netmask": "255.255.255.0",
           "ip": "192.168.128.1",
           "enabled": 1
       },
       "c8y_WAN": {
           "password": "user-password",
           "authType": "chap",
           "apn": "example.apn.com",
           "username": "ee"
       },
       "c8y_DHCP": {
           "dns2": "1.1.1.1",
           "dns1": "8.8.8.8",
           "domainName": "my.domain",
           "addressRange": {
               "start": "192.168.128.100",
               "end": "192.168.128.199"
           },
           "enabled": 1
       }
   }
}

名称	タイプ	必須	説明
c8y_LAN	object	いいえ	ローカルネットワーク情報を含むオプションのネストされたオブジェクト
c8y_LAN.netmask	string	はい	ネットワークインターフェース用に構成されたサブネットマスク
c8y_LAN.ip	string	はい	ネットワークインターフェース用に構成された IP アドレス
c8y_LAN.enabled	integer	はい	インターフェースが有効になっているかどうかを示すインジケーター
c8y_WAN	object	いいえ	モバイルインターネット接続インターフェースのステータスを記述するオプションのネストされたオブジェクト
c8y_WAN.password	string	はい	SIM 接続パスワード
c8y_WAN.authType	string	はい	SIM 接続で使用される認証タイプ
c8y_WAN.apn	string	はい	インターネットアクセスに使用される APN
c8y_WAN.username	string	はい	SIM 接続ユーザー名
c8y_DHCP	object	いいえ	DHCP サーバーのステータスに関する情報を含むオプションのネストされたオブジェクト
c8y_DHCP.dns1	string	いいえ	最初に構成された DNS サーバー
c8y_DHCP.dns2	string	いいえ	2 番目に構成された DNS サーバー
c8y_DHCP.domainName	string	いいえ	ドメイン名
c8y_DHCP.addressRange.start	string	いいえ	DHCP クライアントに割り当てられたアドレス範囲の開始
c8y_DHCP.addressRange.end	string	いいえ	DHCP クライアントに割り当てられたアドレス範囲の終了
c8y_DHCP.enabled	integer	いいえ	DHCPサーバーが有効になっているかどうかを示すインジケーター

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
WAN、LAN、および DHCP 構成を適用する
デバイスのマネージドオブジェクトの新しいネットワーク構成ステータスを設定する
オペレーションのステータスを SUCCESSFUL に設定する

ネットワーク構成の変更は、デバイスが Things Cloudプラットフォームに接続する機能に影響を与える可能性があります。新しい設定で接続テストを実行することをお勧めします。テストが失敗した場合、デバイスは設定を以前の状態にロールバックし、オペレーションのステータスを FAILED に設定する必要があります。

SmartREST 例

ネットワークフラグメントの設定やネットワークオペレーションの受信に使用できる静的テンプレートはありません。代わりにカスタムテンプレートを使用できます。

10,100,PUT,INVENTORY,false,c8y_Network.c8y_LAN.name,STRING,,c8y_Network.c8y_LAN.ip,STRING,,c8y_Network.c8y_LAN.netmask,STRING,,c8y_Network.c8y_LAN.mac,STRING,,c8y_Network.c8y_LAN.enabled,STRING,,c8y_Network.c8y_WAN.simStatus,STRING,,c8y_Network.c8y_WAN.apn,STRING,,c8y_Network.c8y_WAN.username,STRING,,c8y_Network.c8y_WAN.password,STRING,,c8y_Network.c8y_WAN.authType,STRING,,c8y_Network.c8y_DHCP.addressRange.start,STRING,,c8y_Network.c8y_DHCP.addressRange.end,STRING,,c8y_Network.c8y_DHCP.domainName,STRING,,c8y_Network.c8y_DHCP.dns1,STRING,,c8y_Network.c8y_DHCP.dns2,STRING,,c8y_Network.c8y_DHCP.enabled,STRING,

11,200,,c8y_Network.c8y_WAN,c8y_Network.c8y_WAN.apn,c8y_Network.c8y_WAN.username,c8y_Network.c8y_WAN.password,c8y_Network.c8y_WAN.authType

11,201,,c8y_Network.c8y_LAN,c8y_Network.c8y_LAN.ip,c8y_Network.c8y_LAN.netmask,c8y_Network.c8y_LAN.enabled

11,202,,c8y_Network.c8y_DHCP,c8y_Network.c8y_DHCP.addressRange.start,c8y_Network.c8y_DHCP.addressRange.end,c8y_Network.c8y_DHCP.domainName,c8y_Network.c8y_DHCP.dns1,c8y_Network.c8y_DHCP.dns2,c8y_Network.c8y_DHCP.enabled

カスタムテンプレートの例では、デバイスが現在のネットワーク構成を完全にアップロードするための 100 テンプレートを提供します。デバイスエージェントの起動時および変更が検出されるたびに、このテンプレートを使用して、クラウド内の情報をローカルの実態と同期する必要があります。

このサンプルテンプレートには、3 つの異なるネストされたフラグメントをオペレーションとして受信するための 3 つの応答テンプレートも用意されています。各応答テンプレートは個別に処理できます。

WAN

WAN 構成オペレーションを受信する
200,example.apn.com,user,secret,chap
オペレーションのステータスを EXECUTING に設定する
501,c8y_Network
WAN 構成を適用する
インベントリでデバイスのネットワーク構成を更新する
100,br0,192.168.128.1,255.255.255.0,00:60:64:dd:a5:c3,1,SIM OK,example.apn.com,user,secret,chap,192.168.128.100,192.168.128.199,my.domain,8.8.8.8,1.1.1.1,1
オペレーションのステータスを SUCCESSFUL に設定する
503,c8y_Network

LAN

LAN 構成オペレーションを受信する
201,192.168.128.2,255.255.255.0,1
オペレーションのステータスを EXECUTING に設定する
501,c8y_Network
LAN 構成を適用する
インベントリでデバイスのネットワーク構成を更新する
100,br0,192.168.128.2,255.255.255.0,00:60:64:dd:a5:c3,1,SIM OK,example.apn.com,user,secret,chap,192.168.128.100,192.168.128.199,my.domain,8.8.8.8,1.1.1.1,1
オペレーションのステータスを SUCCESSFUL に設定する
503,c8y_Network

DHCP

DHCP 構成オペレーションを受信する
202,192.168.128.150,192.168.128.199,my.other.domain,1.1.1.1,8.8.8.8,1
オペレーションのステータスを EXECUTING に設定する
501,c8y_Network
DHCP 構成を適用する
インベントリでデバイスのネットワーク設定を更新する
100,br0,192.168.128.1,255.255.255.0,00:60:64:dd:a5:c3,1,SIM OK,example.apn.com,user,secret,chap,192.168.128.150,192.168.128.199,my.other.domain,1.1.1.1,8.8.8.8,1
オペレーションのステータスを SUCCESSFUL に設定する
503,c8y_Network

リモートアクセス

リモートアクセスタブは、リモートコントロールプロトコルを介してリモートコントロール用のデバイスを構成およびアクセスするために使用されます。

リモートアクセスタブは、次の条件が満たされている場合に使用できます。

クラウドリモートアクセスマイクロサービスは、必要なテナントにサブスクライブされている
ユーザーに適切なアクセス許可が付与されている (リモートアクセス管理者権限)
デバイスのc8y_RemoteAccessConnectにc8y_SupportedOperationsが追加されている

を参照してください。 -->

リモートアクセス接続

ユーザーがリモートアクセスエンドポイントを選択して接続ボタンをクリックすると、c8y_RemoteAccessConnectオペレーションが作成されます。

{
   "c8y_RemoteAccessConnect": {
     "hostname": "10.0.0.67",
     "port": 5900,
     "connectionKey": "eb5e9d13-1caa-486b-bdda-130ca0d87df8"
   }
}

フィールド	データ型	必須	詳細
connectionKey	string	はい	デバイス側からの接続要求を認証するための共有シークレット
hostname	string	はい	接続先のローカルネットワーク上のエンドポイント
port	integer	はい	ローカルネットワークエンドポイントで使用するポート

このオペレーションでは、デバイスは認証用の接続キー (wss://<c8y host>/service/remoteaccess/device/<connectionKey>) 指定されたホスト名とポートへのローカルソケットを使用して、マイクロサービスエンドポイントへの WebSocket 接続を開く必要があります。次に、WebSocket とローカルソケットの間でデータの双方向転送を確立する必要があります。

Things Cloud は現在、VNC、SSH、および Telnet をサポートしています。デバイスエージェントは、使用するリモートアクセスプロトコルとは無関係に実装する必要があります。この操作では、意図的にプロトコルは転送されません。エージェントは、確立された両方のソケット間で任意のデータを転送できる必要があります。

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
リモートアクセスマイクロサービスへの WebSocket 接続を確立する
指定したホストとポートへのローカルソケット接続を確立する
WebSocket とローカルソケット間の双方向転送を確立する
オペレーションのステータスを SUCCESSFUL に設定する

接続が確立されると、オペレーションは SUCCESSFUL に設定されます。切断はサイレントに行われます。接続が関係するコンポーネントのいずれによっても正常に終了されなかった場合でも、オペレーションのステータスは SUCCESSFUL のままである必要があります。接続の 1 つ (WebSocket または TCP) が終了するたびに、デバイスエージェントはセッション終了と見なし、両方の接続も終了する必要があります。

SmartREST例

530 静的応答テンプレートは、c8y_RemoteAccessConnectオペレーションの受信に使用できます。

c8y_RemoteAccessConnectオペレーションを受信する
530,DeviceSerial,10.0.0.67,22,eb5e9d13-1caa-486b-bdda-130ca0d87df8
デバイスがオペレーションステータスをEXECUTINGに設定する
501,c8y_RemoteAccessConnect
HTTP を使用して WebSocket 接続を確立する
ローカルソケット接続を確立する
デバイスがオペレーションステータスを SUCCESSFULに設定する
503,c8y_RemoteAccessConnect

シェル

シェル タブでは、デバイスに任意のデバイス固有のコマンドを送信することができます。デバイスのc8y_SupportedOperationsにc8y_Commandオペレーションが存在する場合に表示されます。

デバイスにコマンドを送信する

コマンドテキストには任意の文字列を入力できます。フォーマットとその解釈はデバイス統合に依存します。実行ボタンをクリックするとc8y_Commandオペレーションを作成されます。

{
   "c8y_Command": {
       "text": "get sw.version; get hw.version"
   }
}

フィールド	データ型	必須	詳細
c8y_Command.text	string	はい	デバイスによって実行されるコマンドテキスト

実行の完了後、デバイスはオペレーションのステータスを SUCCESSFUL に設定するだけでなく、コマンドの戻り値の文字列を提供する必要があります。結果は、オペレーションの c8y_Commandフラグメント内にネストされた文字列プロパティとして提供されます。

PUT /devicecontrol/operations/<operationId>

{
   "status": "SUCCESSFUL",
   "c8y_Command": {
       "text": "get sw.version; get hw.version",
       "result": "1.2.3; 9.8.7"
   }
}

フィールド	データ型	必須	詳細
status	string	はい	操作が意図した通りに完了したかどうかを示すオペレーションのステータス
c8y_Command	object	はい	最初に保留中のオペレーションを介して受信した c8y_Command オブジェクト
c8y_Command.text	string	はい	デバイスによって実行されたコマンド
c8y_Command.result	string	はい	コマンド実行後の実行結果

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
コマンドを実行して戻り値を取得する
オペレーションのステータスを SUCCESSFUL に設定し、戻り値を含める

SmartREST 例

SmartREST 接続デバイスの場合、c8y_Command オペレーションを受信するために 511 静的応答テンプレートを使用できます。さらに、503 静的テンプレートの暗黙的なパラメータ機能を使用して、戻り値を指定できます。

c8y_Commandオペレーションを受信する
511,DeviceSerial,"get sw.version; get hw.version"
オペレーションのステータスを EXECUTING に設定する
501,c8y_Command
オペレーションのステータスを SUCCESSFUL に設定し、戻り値を指定する
503,c8y_Command,"1.2.3; 9.8.7"

ソフトウェア

ソフトウェア タブでは、デバイスのソフトウェアファイル一式をインストールおよびアンインストールすることができます。ファイルは、URLを使用して配置することも、Things Cloudソフトウェアリポジトリにホストすることもできます。デバイスエージェントは、そのローカルインストール、管理、アンインストール手順、およびオペレーション中のあらゆる種類のエラー処理に対して完全に対応します。

デバイスの詳細 ページには、デバイスのマネージドオブジェクトの c8y_SupportedOperationsフラグメントでc8y_SoftwareListやc8y_SoftwareUpdateを通知するデバイスの ソフトウェア タブが表示されます。また、少なくとも1つのソフトウェアサービスが実行されているデバイスのための サービス タブも表示されます。サービスにはメジャーメント、アラーム、イベントを割り当てることができます。

インストールされているソフトウェア

インストールされたソフトウェアパッケージは、c8y_SoftwareListフラグメントにリストされ、デバイスのマネージドオブジェクトまたはc8y_InstalledSoftwareList 型の子オブジェクトに追加されます。ソフトウェアを管理する最初のアプローチを「レガシー」、2番目のアプローチを「アドバンスト」と呼びます。

ソフトウェア・パッケージ・リスト・エントリーは、次のプロパティが含まれている必要があります。

フィールド	必須	詳細
name	はい	ソフトウェア名
version	はい	ソフトウェアのバージョン識別子
url	いいえ	ソフトウェアファイルの取得元の場所を示す URL
softwareType	いいえ	ソフトウェア成果物を整理するための任意の文字列

name と version は、パッケージを識別するために使用されます。すでに述べたc8y_SupportedSoftwareTypesフラグメントは、デバイスにインストール可能なソフトウェアの種類を制限します。

レガシーソフトウェア管理

デバイスは、マネージドオブジェクトのc8y_SoftwareListフラグメントを更新することで、ソフトウェアリストを更新できます。

PUT /inventory/managedObjects/<deviceId>

{
  "c8y_SoftwareList": [
    {
      "name": "software_a",
      "version": "3.0.0",
      "url": "http://example.com/software_a",
      "softwareType": "type A"
    },
    {
      "name": "software_b",
      "version": "2.0.0",
      "url": "http://example.com/software_b",
      "softwareType": "type B"
    }
  ]
}

デバイスは、起動時にインストールされているソフトウェアの完全なリストをアップロードする必要があります。さらに、ローカルの変更がトリガーまたは検出された場合は、常にリストを更新する必要があります。これには、Things Cloud の UIから変更がリクエストされた場合も含まれます。

SmartREST例

Things Cloudは、デバイスがインストールされたソフトウェアをアップロードするために、静的なSmartRESTテンプレート116を提供します。これは、ソフトウェアパッケージごとにトリプルの動的長さのリストをパラメータとして受け取ります。各トリプルは、個々のパッケージの名前、バージョン、およびURLプロパティとして解釈されます。

116,software_a,3.0.0,http://example.com/software_a,software_b,2.0.0,http://example.com/software_b

インストール済みソフトウェアの変更

ソフトウェア タブでは、ユーザーはデバイスにインストール、更新、およびアンインストールするソフトウェアを選択することができます。確認後、目的のソフトウェア構成をオペレーションとしてデバイスに送信されます。オペレーションの形式は、デバイスのc8y_SupportedOperationsフラグに依存します。

ソフトウェア一覧

デバイスがc8y_SoftwareListオペレーションのみをサポートし、c8y_SupportedOperationsフラグメントにc8y_SoftwareUpdateを含まない場合、c8y_SoftwareListオペレーションがデバイスに送信されます。このオペレーションには、デバイス独自のマネージドオブジェクトにすでに存在するものと非常に類似したc8y_SoftwareListフラグメントが含まれます。c8y_SoftwareListオペレーションは、常にデバイスにインストールされるべきソフトウェアの全リストを含んでいます。リスト内のパッケージを正確にインストールする必要があります。また、リストに含まれていないインストール済みのパッケージは削除する必要があります。

{
  "c8y_SoftwareList": [
    {
      "name": "software_a",
      "version": "4.0.0",
      "url": "http://example.com/software_a"
    },
    {
      "name": "software_b",
      "version": "3.0.0",
      "url": "http://example.com/software_b"
    }
  ]
}

フィールド	データ型	必須	詳細
name	string	はい	ソフトウェア名
version	string	はい	ソフトウェアのバージョン識別子
url	string	はい	ソフトウェアファイルのダウンロード元の場所を示す URL

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスをEXECUTINGに設定する
アンインストールする必要があるソフトウェアをアンインストールする
インストールする必要があるソフトウェアをインストールする
デバイス独自のマネージドオブジェクトのソフトウェアリストを更新する
オペレーションのステータスをSUCCESSFULに設定する

何らかの理由で目的の状態を達成できない場合は、オペレーションをステータス FAILED で終了する必要があります。

SmartREST 例

516 静的応答テンプレートは、ソフトウェアのリスト操作に対応するために利用できます。これは、デバイス独自のマネージドオブジェクトを更新するために使用される 116 テンプレートと非常に類似して動作します。

c8y_SoftwareListオペレーションを受信する
516,DeviceSerial,software_a,4.0.0,http://example.com/software_a,software_b,3.0.0,http://example.com/software_b
オペレーションステータスをEXECUTINGに設定する
501,c8y_SoftwareList
ソフトウェアをアンインストールまたはインストールする
インベントリ内のデバイスのソフトウェアリストを更新する
116,software_a,4.0.0,http://example.com/software_a,software_b,3.0.0,http://example.com/software_b
オペレーションステータスをSUCCESSFULに設定する
503,c8y_SoftwareList

ソフトウェア更新

デバイスがc8y_SupportedOperationsフラグメントでc8y_SoftwareUpdateオペレーションをサポートしている場合、ソフトウェア タブはデバイスのc8y_SoftwareUpdateオペレーションを作成します。概念としてソフトウェア更新は、ソフトウェアリストと類似しています。ソフトウェアの望ましい状態は、パッケージのリストという形でデバイスに送信されます。その違いは、c8y_SoftwareUpdateは部分的なリストと考えるべきであるということです。各リスト要素には、パッケージをインストールするかアンインストールするかの追加指示が含まれます。ソフトウェア更新リストに記載されていないパッケージには触れないでください。

{
  "c8y_SoftwareUpdate": [
    {
      "name": "software_a",
      "version": "4.0.0",
      "url": "http://example.com/software_a",
      "action": "install"
    },
    {
      "name": "software_b",
      "version": "3.0.0",
      "url": "http://example.com/software_b",
      "action": "delete"
    }
  ]
}

フィールド	データ型	必須	詳細
name	string	はい	ソフトウェア名
version	string	はい	ソフトウェアのバージョン識別子
url	string	はい	ソフトウェアファイルのダウンロード元の場所を示す URL
action	string	はい	ソフトウェア上のデバイスから実行されるアクション（可能な値：「install」または「delete」）

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスを EXECUTING に設定する
オペレーションに含まれるパッケージのリストを反復処理し、それぞれのアクションを実行する
デバイス独自のマネージドオブジェクトのソフトウェアリストを更新する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST 例

528 静的応答テンプレートは、ソフトウェアの更新オペレーションを処理するために使用できます。

c8y_SoftwareUpdateオペレーションを受信する
528,DeviceSerial,software_a,4.0.0,http://example.com/software_a,install,software_b,3.0.0,http://example.com/software_b,delete
オペレーションステータスをEXECUTINGに設定する
501,c8y_SoftwareUpdate
ソフトウェアをアンインストールおよびインストールする
インベントリ内のデバイスのソフトウェアリストを更新する
116,software_a,3.0.0,http://example.com/software_a
オペレーションステータスをSUCCESSFULに設定する
503,c8y_SoftwareUpdate

高度なソフトウェア管理

高度なアプローチを使用することで、c8y_SoftwareListフラグメントはデバイスのマネージドオブジェクトに存在しなくなります。データはデバイスマネージドオブジェクトから切り離され、インストールされているソフトウェアのリストが非常に大きくても、デバイスのマネージドオブジェクトのサイズは小さく保たれます。デバイスにインストールされているすべてのソフトウェアは、高度なソフトウェア管理のデフォルトマイクロサービスを介して読み取って管理できます。

デバイスは、c8y_SupportedOperationsフラグメントにc8y_SoftwareUpdateオペレーションが含まれ、c8y_SupportedSoftwareTypesフラグメントにサポートされるソフトウェアタイプをリストすることによって、高度なソフトウェア管理のサポートをすることができます。

{
  "c8y_SupportedOperations": [
    "c8y_SoftwareUpdate"
  ],
  "c8y_SupportedSoftwareTypes": [
    "type_a",
    "type_b"
  ]
}

ソフトウェアパッケージのクエリ、追加、削除は、マイクロサービスのRESTエンドポイントまたはSmartREST静的テンプレートを使用して行うことができます。

ソフトウェアパッケージのクエリ

GET /service/advanced-software-mgmt/software?deviceId=<deviceId>

{
  "softwareList": [
    {
      "name": "software_a",
      "version": "3.0.0",
      "url": "http://example.com/software_a",
      "softwareType": "type A"
    },
    {
      "name": "software_b",
      "version": "2.0.0",
      "url": "http://example.com/software_b",
      "softwareType": "type B"
    }
  ],
  "statistics": {
    "currentPage": 1,
    "pageSize": 5
  }
}

クエリパラメータ	必須	詳細
deviceId	はい	デバイスID
name	いいえ	ソフトウェア名のフィルターパラメータ
version	いいえ	ソフトウェアバージョンのフィルターパラメータ
type	いいえ	ソフトウェアタイプのフィルターパラメータ
pageSize	いいえ	ページ分割された結果のページ上のアイテム数（1 から 2000 まで）
currentPage	いいえ	ページ分割された結果の現在のページ
withTotalPages	いいえ	`true` に設定すると、返される結果には統計オブジェクト内のページの合計数が含まれる

ソフトウェアパッケージの設定

高度なソフトウェア管理は、レガシーソフトウェア管理と同様に、デバイスはインストールされているソフトウェアを設定することができます。この場合、以前からプラットフォームと通信されていたソフトウェアは、新しいパッケージで完全に上書きされます。

POST /service/advanced-software-mgmt/software?deviceId=<deviceId>

[
  {
    "name": "software_a",
    "version": "3.0.0",
    "url": "http://example.com/software_a",
    "softwareType": "type A"
  },
  {
    "name": "software_b",
    "version": "2.0.0",
    "url": "http://example.com/software_b",
    "softwareType": "type B"
  }
]

SmartREST 例

デバイスは、SmartREST静的テンプレート140を代わりに使用することもできます。これは、動的な長さのソフトウェアパッケージのリストを取得し、各パッケージは、名前、バージョン、ソフトウェアタイプおよびURLによって表します。

140,software_a,3.0.0,"type A",http://example.com/software_a,software_b,2.0.0,"type B",http://example.com/software_b

ソフトウェアパッケージの追加

高度なソフトウェア管理を使用すると、デバイスはリスト全体を通知することなく、インストール済みのソフトウェアにパッケージを追加することもできます。

PUT /service/advanced-software-mgmt/software?deviceId=<deviceId>

[
  {
    "name": "software_a",
    "version": "3.0.0",
    "url": "http://example.com/software_a",
    "softwareType": "type A"
  },
  {
    "name": "software_b",
    "version": "2.0.0",
    "url": "http://example.com/software_b",
    "softwareType": "type B"
  }
]

SmartREST 例

デバイスは SmartREST の静的テンプレート 141 を代わりに使用します。140 と同様に、ソフトウェアパッケージのリストを取得します。

141,software_a,3.0.0,"type A",http://example.com/software_a,software_b,2.0.0,"type B",http://example.com/software_b

ソフトウェアの削除

インストールされているソフトウェアの部分的な更新を完了するために、高度なソフトウェア管理は、デバイスのインストールされているソフトウェアから個々のパッケージを削除するためのインターフェースを提供します。

DELETE /service/advanced-software-mgmt/software?deviceId=<deviceId>

[
  {
    "name": "software_a",
    "version": "3.0.0"
  },
  {
    "name": "software_b",
    "version": "2.0.0"
  }
]

SmartREST 例

デバイスは、SmartREST静的テンプレート142を代わりに使用することもできます。URL とソフトウェアタイプはパッケージの識別に使用されないため、動的な長さのソフトウェアパッケージのリストを取得します。各パッケージは名前とバージョンで表します。

142,software_a,3.0.0,software_b,2.0.0

インストール済みソフトウェアの変更

同様に、高度なソフトウェア管理アプローチでは、ソフトウェアパッケージを更新するには、c8y_SupportedOperationsフラグメントで指定されているオペレーションに応じて、 c8y_SoftwareUpdateまたはc8y_SoftwareListのいずれかのオペレーションをデバイスに送信する必要があります。唯一の違いは、ソフトウェアパッケージにソフトウェアタイププロパティが必要になったことです。

ソフトウェア更新

c8y_SoftwareUpdateオペレーションにはソフトウェアパッケージの一部リストが含まれ、それぞれにインストールまたはアンインストールする必要があるかどうかが指示されています。これは、レガシーソフトウェア管理と類似していますが、各パッケージのソフトウェアタイプを示す追加のパラメータも含まれています。

{
  "c8y_SoftwareUpdate": [
    {
      "name": "software_a",
      "version": "4.0.0",
      "url": "http://example.com/software_a",
      "softwareType": "type A",
      "action": "install"
    },
    {
      "name": "software_b",
      "version": "3.0.0",
      "url": "http://example.com/software_b",
      "softwareType": "type B",
      "action": "delete"
    }
  ]
}

フィールド	データ型	必須	詳細
name	string	はい	ソフトウェア名
version	string	はい	ソフトウェアのバージョン識別子
url	string	はい	ソフトウェアファイルのダウンロード元の場所を示す URL
softwareType	string	はい	ソフトウェア成果物を整理するための任意の文字列
action	string	はい	ソフトウェア上のデバイスから実行されるアクション（可能な値：「install」または「delete」）

デバイスは、次のアクションを実行する必要があります。

オペレーションのステータスをEXECUTINGに設定する
オペレーションに含まれるパッケージのリストを反復処理し、それぞれのアクションを実行する
デバイス独自のマネージメントオブジェクトのソフトウェアリストを更新する
オペレーションのステータスを SUCCESSFUL に設定する

SmartREST 例

高度なソフトウェア管理をサポートするデバイスのソフトウェア更新オペレーションに対応するために、529 静的応答テンプレートが利用できます。

c8y_SoftwareUpdateオペレーションを受信する
529,DeviceSerial,software_a,4.0.0,"type A",http://example.com/software_a,install,software_b,3.0.0,"type B",http://example.com/software_b,delete
オペレーションステータスをEXECUTINGに設定する
501,c8y_SoftwareUpdate
ソフトウェアをアンインストールおよびインストールする
アンインストールされたソフトウェアパッケージをインベントリから削除する
142,software_b,3.0.0
インストール済みソフトウェアパッケージをインベントリに追加する
141,software_a,4.0.0,"type A",http://example.com/software_a
オペレーションのステータスを SUCCESSFUL に設定する
503,c8y_SoftwareUpdate

サービス

Things Cloud UIでは、デバイス上で動作するソフトウェアサービスを監視することができます。サービスは、Things Cloud ドメインモデルにおいて、c8y_Service タイプを持つデバイスのマネージドオブジェクトの子追加として表します。

デバイスの詳細 ページには、少なくとも 1 つのソフトウェアサービスを持つデバイスの サービス タブが表示されます。サービスはメジャーメント、アラーム、イベントが割り当てられています。

マネージドオブジェクトを操作するために、Things Cloud REST API を使用してサービスのクエリ、更新、追加、削除を行います。

REST API の例

プラットフォームへのサービスを通知

インベントリ REST API を使用：

POST /inventory/managedObjects/<deviceId>/childAdditions

Content-Type: "application/vnd.com.nsn.cumulocity.managedObject+json"

{
  "name": "DatabaseService",
  "type": "c8y_Service",
  "serviceType": "systemd",
  "status": "up"
}

フィールド	必須	詳細
name	はい	サービス名
type	はい	マネージドオブジェクトのタイプは、常に `c8y_Service` でなければならない。
serviceType	はい	サービスを整理するための任意の文字列
status	はい	`up`、`down`、`unknown` または任意のカスタムサービスのステータス

SmartREST 静的テンプレート 102 を使用して s/us/<serviceId> トピックに送信：

2番目のパラメータである一意のIDは、内部数値IDではなく、プラットフォームとは異なり、デバイスによって定義される文字列ベースの外部IDを参照します。同じサービスを実行している他のデバイスとの競合を避けるため、一意のIDの前にデバイス固有のプレフィックスを付けることをお勧めします。

102,myDatabaseDevice,systemd,DatabaseService,up

サービスのステータス更新

インベントリREST APIの使用：

PUT /inventory/managedObjects/<serviceId>

Content-Type: "application/vnd.com.nsn.cumulocity.managedObject+json"

{
  "status": "down"
}

フィールド	必須	詳細
status	はい	`up`、`down`、`unknown` またはサービスのステータスを指定する任意の文字列

または、SmartREST 静的テンプレート 104を使用して s/us/<serviceId> にトピック送信：

104,down

サービスデータの送信

メジャーメントREST API：

POST /measurement/measurements

Content-Type: "application/vnd.com.nsn.cumulocity.measurement+json"

{
  "source": {
    "id": "<serviceManagedObjectId>"
  },
  "time": "2020-03-19T12:03:27.845Z",
  "type": "c8y_Memory",
  "c8y_Memory": {
    "allocated": {
      "unit": "MB",
      "value": 100
    }
  }
}

または、SmartREST静的テンプレート200を使用してs/us/<serviceId>トピックに送信:

200,c8y_Memory,allocated,100,MB

メジャーメントと同様に、サービスに関連するアラームやイベントも送信できます。

トラッキング

トラッキングタブでは、デバイスのパスを可視化することができます。これを実現するために、デバイスは定期的にトラッキングイベントを送信し、その位置を更新する必要があります。

位置履歴の追跡

デバイスは、現在または過去の位置を、c8y_Positionフラグメントの位置更新イベントとしてアップロードすることができます。これは、ルート上のデバイスを追跡したり、一般的にデバイスの位置履歴を追跡するのに便利です。

POST /event/events

{
    "c8y_Position": {
       "alt": 67,
       "lng": 6.95173,
       "lat": 51.151977
    },
    "time":"2013-06-22T17:03:14.000+02:00",
    "source": {
    	"id": "10300"
     },
    "type": "c8y_LocationUpdate",
    "text": "LocUpdate"
}

フィールド	データ型	必須	詳細
c8y_Position	object	はい	地理的な場所のプロパティを保持
c8y_Position.alt	number	いいえ	デバイス位置の高度 (メートル単位)
c8y_Position.lng	number	はい	デバイス位置の経度 (度単位)
c8y_Position.lat	number	はい	デバイス位置の緯度 (度単位)
time	string	はい	位置が測定された時間
source	object	はい	ソースデバイスID
type	string	はい	イベントを位置情報更新イベントとして指定するには、常にc8y_LocationUpdateの必要がある
text	string	はい	イベントの説明。このパラメータは、一般的なイベントに必要なため必須です。追跡デバイスのコンテキストでテキストに適用される以上の意味はありません。

SmartREST例

Things Cloud には、SmartREST を使用して位置更新イベントを送信するための 401 静的テンプレートが用意されています。

401,51.151977,6.95173,67,2013-06-22T17:03:14.000+02:00

現在位置の設定

現在のデバイス位置は、デバイス独自のマネージドオブジェクトのc8y_Positionフラグメントを使用して表されます。

PUT /inventory/managedObjects/<deviceId>

{
    "c8y_Position": {
    	"alt": 67,
      "lng": 6.95173,
      "lat": 51.151977
    }
}

フィールド	データ型	必須	詳細
alt	number	いいえ	デバイス位置の高度 (メートル単位)
lng	number	はい	デバイス位置の経度 (度単位)
lat	number	はい	デバイス位置の緯度 (度単位)

SmartREST例

デバイスは、112 静的テンプレートを使用して現在の位置を更新できます。

112,51.151977,6.95173,67,

Things Cloudでは、時間の経過に伴う追跡はイベントを使用して行われ、現在の位置はデバイス独自のマネージドオブジェクトのフラグメントとして表されます (詳細については、上記を参照)。実際には、デバイスは通常、一定間隔で現在の位置を決定し、測定された座標をアップロードします。この場合、現在の位置とその時点の位置は同じであり、402静的テンプレートを使用して同時にアップロードできます。

402,51.151977,6.95173,67,,

概要

c8y_SupportedOperations フラグメント

一般的なコンセプト

機能

現在のステータスの伝達

オペレーション処理

オペレーション処理中のエラー処理

エージェントクラッシュ後の復旧

冪等性なケース

アラーム

アラームの発生

アラームのクリア

クリティカルアラーム

子デバイス

子デバイスを親デバイスに割り当てる

子デバイスのゲートウェイ操作

構成

テキストベースの構成

現在のテキスト構成をアップロードする

テキスト構成のインストール

レガシーファイルベースの構成

現在のレガシー構成をアップロードする

レガシー構成のインストール

型指定されたファイルベースの構成

現在の構成ファイルをアップロードする

構成ファイルのインストール

接続

デバイスの可用性

可用性の監視

接続監視

デバイス情報

デバイスマーカー

エージェントマーカー

デバイスの再起動

再起動操作

ハードウェア情報

エージェント情報

リレー

リレー

単一リレー

リレー状態

リレー状態の設定

複数のリレー

複数リレーの状態

複数リレーの状態を設定する

デバイスプロファイル

ファームウェア

インストールされたファームウェア

ファームウェアイメージのインストール

ファームウェアパッチのインストール

識別子

REST

MQTT (SmartREST 2.0)

ログ

サポートされているログ設定

ログファイルのアップロード

手動ステータス更新

計測値（メジャーメント）

ネットワーク

ネットワーク ステータス

ネットワーク構成の設定

リモートアクセス

リモートアクセス接続

シェル

デバイスにコマンドを送信する

ソフトウェア

インストールされているソフトウェア

レガシーソフトウェア管理

インストール済みソフトウェアの変更

ソフトウェア一覧

ソフトウェア更新

高度なソフトウェア管理

ソフトウェアパッケージのクエリ

ソフトウェアパッケージの設定

SmartREST 例

ソフトウェアパッケージの追加

SmartREST 例

ソフトウェアの削除

SmartREST 例

インストール済みソフトウェアの変更

ネットワークステータス