拡張可能なデバイス登録
増え続ける IoT プロトコルと、一般的な単一または一括のデバイス登録における特定の制限に対処するため、Things Cloud では拡張可能なデバイス登録機能が提供されています。
一般的なコンセプトは、メタデータベースのアプローチを使用してデバイス登録を拡張することに基づいています。現在のデバイス登録を実装するマイクロサービスとエージェントは、必要な登録属性の簡単な説明を提供することで、デバイス登録ウィザードにカスタムフォームを追加できます。その後、メタデータは UI によって使用され、対応するデバイス登録ウィザードが表示されます。
UIを拡張するには 2 つの方法があります。
必要条件
拡張可能なデバイス登録には、
アプリケーション拡張 が定義され、デバイス登録メタデータの取得とデバイスの作成に使用される定義済みのエンドポイントを実装するマイクロサービスが必要です。
拡張デバイス登録の利点
拡張デバイス登録には次のような利点があります。
-
デバイス登録ウィザードの拡張性： デバイス管理アプリケーションの UI 内で、デバイス登録ウィザードに独自のフォームを簡単に追加できます。ユーザー指定のフォームに入力される値は、デバイス統合開発者によって自由にカスタマイズできます。
-
カスタム CSV による一括登録への対応： 一括登録をカスタマイズすることで、異なるフォーマットのCSVファイルのサポートを実装することができます。
-
UIコードの変更が不要： UI の Angular コードを書く必要はありません。このため、統合作業は可能な限り少なくて済みます。デバイス統合開発者は、独自のウィザードを提供するマイクロサービスをサブスクライブするだけでよく、ウィザードは自動的に表示されます。
拡張機能の有効化
デバイス登録フローを拡張する最初のステップとして、アプリケーション表現で拡張機能を定義する必要があります。
備考
extensions フラグメントはルートレベルか、アプリケーション表現の manifest フラグメントの中に置くことができます。
拡張機能には 2 つのタイプがあります。
- 単一デバイス登録タイプ：例：
extensibleDeviceRegistration
"extensions": [
{
"name": "<extension name>",
"description": "<description>",
"type": "extensibleDeviceRegistration"
},
...
]
- 一括デバイス登録タイプ：例：
extensibleBulkDeviceRegistration
"extensions": [
{
"name": "<extension name>",
"description": "<description>",
"type": "extensibleBulkDeviceRegistration"
},
...
]
単一デバイスの登録
extensibleDeviceRegistration拡張タイプを有効にすると、デバイス管理アプリケーションの デバイス > デバイス登録 メニューに拡張タイプ name プロパティに対応する項目が追加されます。
今後は、カスタムマイクロサービス経由で提供されるデータに基づいて、すべてがレンダリングされます。追加されたメニュー項目は、以下のエンドポイントを使用してフォーム定義を取得するウィンドウを開きます。
GET /service/<contextPath>/deviceRegistration/metadata&lang=<user-language>
マイクロサービスの lang クエリパラメータを使用して、翻訳済みの JSON Schema メタデータで応答してください。詳細は、制約事項を参照してください。
UIは、自動的にマイクロサービスのアプリケーション定義から GET リクエストの contextPath を取得します。
{
"contextPath": "<relative path>",
"availability": "MARKET",
"type": "MICROSERVICE",
"name": "<agent name>",
...
}
メタデータの定義例：
{
"c8y_DeviceRegistration": {
"title": "Example extensible registration",
"description": "The required and optional properties to register and setup devices",
"pages": [
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"title": "Mandatory settings",
"properties": {
"security": {
"default": "NO_SEC",
"type": "string",
"title": "Security mode",
"enum": [
"NO_SEC",
"SEC"
]
},
"imei": {
"examples": [
"012345678901234"
],
"type": "string",
"title": "Imei number"
}
},
"required": [
"imei",
"security"
]
},
{...}
]
}
}
重要なパートである pages 配列には、モーダルが JSON Schema 定義に従ってレンダリングするウィザードのステップが含まれます：https://json-schema.org/
その結果、以下のウィザードが表示されます。
最後のステップでは、ウィザードを介して収集されたすべてのデータは、次の REST エンドポイントを使用してマイクロサービスに返送されます。
POST /service/<contextPath>/deviceRegistration
{
"imei": "012345678901234",
"security": "NO_SEC",
...
}
フォームは、JSON スキーマで定義されたものをマイクロサービスに送信することができます。マイクロサービスはフォームの定義を提供し、送信されたデータの適切な処理を担当します。
API仕様
デバイス統合マイクロサービスは、以下の REST エンドポイントを実装する必要があります。
GET /service/<contextPath>/deviceRegistration/metadata?lang=<user-language>
Accept: application/json
JSON スキーマの語彙でメタデータを返します。
POST /service/<contextPath>/deviceRegistration
Content-type: application/json
収集されたデータに基づいて、単一のデバイスを作成します。キーと値のペアで application/json を送信します。
単一デバイス登録フロー図
以下の図は、単一デバイス登録フローを視覚化しています。
一括デバイスの登録
多くのデバイス統合では、多数のデバイスを同時に登録する必要があります。現在のところ、すべてのプロトコルはプラットフォームの一括登録メカニズムに頼らざるを得ず、多くのフィールドを必要とするか、カスタムフィールドを追加する必要があります。ただし、後者はコアが直接デバイスを作成し、マイクロサービスやエージェントはマネージドオブジェクトに書き込まれるプロパティを制御できないため、検証することができません。
extensibleBulkDeviceRegistration 拡張タイプを有効にすると、デバイス管理と接続 > デバイス > デバイス登録 の 一括デバイス登録 モーダルが表示され、拡張の name プロパティに対応する拡張ウィザード項目が表示されます。
さらに、マイクロサービスはウィザードステップのタイトルと一括ファイルの例を提供します。
{
"c8y_DeviceRegistration": {
"title": "<title>",
"description": "<description>",
"bulk": {
"title": "<bulk form title>",
"exampleFileUrls": [{
"title": "<example title>",
"description": "<example description>",
"url": "<publicly-reachable-URL>"
}]
}
}
}
その結果、以下のウィザードが表示されます。
API仕様
デバイス統合マイクロサービスは、以下の REST エンドポイントを実装する必要があります。
GET /service/<contextPath>/deviceRegistration/metadata?lang=<user-language>
Accept: application/json
JSONスキーマの語彙でメタデータを返します。
POST /service/<contextPath>/deviceRegistration/bulk
Content-Type: multipart/form-data; boundary=boundary
--boundary
Content-Disposition: form-data; name="file"; filename="<input csv file>"
Content-Type: text/csv
--boundary--
CSV ファイルタイプの multipart form-data を送信します。
一括デバイス登録フロー図
次の図は、一括デバイス登録フローを視覚化しています。
制約事項
- このコンセプトでは、マイクロサービスがデバイスの登録解除／廃止にフックすることはできません。
- デバイス統合マイクロサービスは、ガベージ コレクションを実行するなど、デバイスが削除されたかどうかを確認する必要があります。
- インタラクティブなステップ（「Bluetooth ペアリング」など）は、今のところ実装できません。その理由は、このコンセプトでは、デバイス登録に必要なのは静的プロパティのみであり、ユーザーとの相互作用を必要とするプロセスは想定していないためです。
- 理論的には、メタデータベースのアプローチは、フォームをレンダリングするために使用される JSON が静的ではなく、マイクロサービスによって動的に生成される方法で簡単に拡張できます。例えば、与えられたすべてのユーザー入力をそこに投稿した後、エンドポイントから動的に次の仕様を描画する「ページ」を指定することができます。
- データモデルとマイクロサービスが満たすべき要件が複雑になるため、このようなソリューションからは一旦距離を置きます。
- JSON スキーマ語彙による入力検証以外に、UI でのカスタム検証がありません。
- カスタムのスタイリングはできません。
- UI による国際化は処理されません。マイクロサービス開発者は、翻訳済みの JSON スキーマ メタデータを提供する責任があります。
