シナリオ: デジタル・ツイン・モデルへのJSONスキーマ検証の追加

カスタムOracle DTDL検証拡張を使用して、JSONスキーマ・データ検証ルールをデジタル・ツイン・モデルのデバイス・ペイロードに適用します。

If you reference the validation extension in your digital twin model using by appending the Digital Twin Model Identifier (DTMI): dtmi:com:oracle:dtdl:extension:validation;1 and adding validation metadata @type to the properties, telemetry, or command elements in your digital twin model then you can apply validation rules and constraints to value ranges, regex patterns, enumerations, required fields, or conditional logic. これらの検証ルールは実行時に適用され、アプリケーションに収集されて渡される有効なデータが正規化されます。

サポートされている検証プロパティ・ルールの完全なリストは、DTMI検証拡張機能リファレンスを参照してください。

始める前に

必要な権限があり、OCI CLIが構成されていることを確認します。詳細は、「前提条件」、Internet of Things (IoT)プラットフォームのポリシー詳細および複雑な入力のためのJSONファイルの使用を参照してください。

このシナリオのコード・スニペットの理解

次のコード・スニペットは、DTDL v3に基づくデジタル・ツイン・モデルの例であり、カスタムOracle検証拡張の使用方法を示しています。

ステップ1: デジタル・ツイン・モデルの`@context`での検証拡張の定義

デジタル・ツイン・モデルがDTDL仕様v3を使用していることを示す、必要なデジタル・ツイン・モデル・コンテキスト: dtmi:dtdl:context;3

検証拡張を定義するには、デジタル・ツイン・モデルの作成またはデジタル・ツイン・モデルの更新時に、検証拡張を@contextのDTMI URI値に追加します。デジタル・ツイン・モデルは、これらの検証ブロックを読み取って、受信デバイス・データに検証ルールを適用します。検証ルールに失敗したデータはすべて拒否されます。正規化データおよび拒否データは、IoTデータベース・スキーマ内にあります。

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  ...
  }

ステップ2: デジタル・ツイン・モデルの要素への`validation`プロパティの追加

デジタル・ツイン・モデルでは、JSONスキーマ検証仕様を使用して、収集データの検証に検証プロパティを追加します。

文字列や整数などのプリミティブ・プロパティの場合、検証制約は、プロパティまたはテレメトリ定義内のスキーマ・フィールドの横に兄弟プロパティとして追加されます。
配列の場合、検証はminItemsやuniqueItemsなどの配列自体に適用され、配列スキーマの兄弟として定義されます。一方、値の範囲や文字列パターンなどの各要素に適用される制約は、elementSchemaの兄弟プロパティとして配列スキーマ内に配置されます。

次のコード・スニペットをデジタル・ツイン・モデルの例として使用します。サポートされている検証プロパティおよびルールの完全なリストは、DTMI検証拡張機能リファレンスを参照してください。

デジタルツインモデルスニペット: 数値検証によるテレメトリ

デジタルツインモデルのこのコードスニペットは、950.0から1050.0までのセンサーからの圧力を有効にする方法を示し、0.1の倍数である必要があります。

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  "@id": "dtmi:com:example:Sensor;1",
  "@type": "Interface",
  "displayName": "Example Sensor",
  "contents": [
    {
      "@type": ["Telemetry", "Validated"],
      "name": "pressure",
      "schema": "double",
      "displayName": "Pressure",
      "minimum": 950.0,
      "maximum": 1050.0,
      "multipleOf": 0.1
  ]
  }

デジタル・ツイン・モデル・スニペット: 文字列パターン検証

この例では、特定の文字列パターンに従ってシリアル番号を検証します。この例では、文字列パターンは、受信シリアル番号値が一致する必要がある正規表現です。シリアル番号の値は「SN- 」で始まり、その後に4から8文字の大文字(A-Z)または数字(0-9)が続く必要があり、次の前後に何も許可されません。

"pattern": "^SN-[A-Z0-9]{4,8}$"

{
  "@type": ["Property", "Validated"]
  "name": "serialNumber",
  "schema": "string",
  "pattern": "^SN-[A-Z0-9]{4,8}$"
  }

デジタル・ツイン・モデル・スニペット: 要素制約を使用した配列検証

アラーム・コードは、100から900までの整数の配列である必要があります。配列には少なくとも1つ、5つ以下の項目が含まれ、すべての項目が一意である必要があります。

{
  "@type": ["Property", "Validated"]
  "name": "alarmCodes",
  "schema": {
    "@type": "Array",
    "elementSchema": "integer",
      "minimum": 100,
      "maximum": 900
  },
  "minItems": 1,
  "maxItems": 5,
  "uniqueItems": true
}

デジタルツインモデルスニペット: 明示的検証による倍精度テレメトリ

この例では、値が二重整数である必要があり、-50.0から150.0までの範囲内にあることが検証されます。

{
  "@type": ["Telemetry", "Validated"]
  "name": "temperature_double",
  "schema": "double",
  "minimum": -50.0,
  "maximum": 150.0
}

デジタルツインモデルスニペット: 明示的検証による単精度テレメトリ

この例では、値がfloatである必要があり、値が-50.0から150.0までの指定された範囲内にあることが検証されます。

{
  "@type": ["Telemetry", "Validated"]
  "name": "temperature_float",
  "schema": "float",
  "minimum": -50.0,
  "maximum": 150.0
}

デジタル・ツイン・モデル・スニペット: タイプ、範囲およびステップ検証によるテレメトリ

この例では、値がdouble、整数、および0から360の度、および0.1の増分であることを検証します。

{
  "@type": ["Telemetry", "Validated"]
  "name": "angle",
  "schema": "double",
  "minimum": 0.0,
  "maximum": 360.0,
  "multipleOf": 0.1
}

Oracle Cloud Infrastructureドキュメント