Oracle Cloud Infrastructure-Dokumentation

Szenario: JSON-Schemavalidierung zu einem digitalen Zwillingsmodell hinzufügen

Verwenden Sie eine benutzerdefinierte Oracle DTDL-Validierungserweiterung, um JSON-Schemadatenvalidierungsregeln auf Geräte-Payloads in Ihrem digitalen Zwillingsmodell anzuwenden.

Wenn Sie die Validierungserweiterung in Ihrem digitalen Zwillingsmodell referenzieren, indem Sie die Digital Twin Model Identifier (DTMI) anhängen: dtmi:com:oracle:dtdl:extension:validation;1 und Validierungsmetadaten @type zu den Eigenschaften, Telemetrie oder Befehlselementen in Ihrem digitalen Zwillingsmodell hinzufügen, können Sie Validierungsregeln und Constraints auf Wertebereiche, reguläre Ausdrucksmuster, Aufzählungen, erforderliche Felder oder Bedingungslogik anwenden. Diese Validierungsregeln werden zur Laufzeit durchgesetzt, um gültige Daten, die aufgenommen und an Anwendungen übergeben werden, zu normalisieren.

Eine vollständige Liste der unterstützten Validierungseigenschaftenregeln finden Sie unter DTMI Validation Extension Reference.

Bevor Sie beginnen

Stellen Sie sicher, dass Sie über die erforderlichen Berechtigungen verfügen und die OCI-CLI konfiguriert ist. Weitere Informationen finden Sie unter Voraussetzungen, Policy-Details für die Internet of Things-(IoT-)Plattform und JSON-Datei für komplexe Eingaben verwenden.

Code-Snippets in diesem Szenario verstehen

Die folgenden Code-Snippets sind Beispiele aus einem digitalen Zwillingsmodell, das auf DTDL v3 basiert und zeigt, wie die benutzerdefinierte Oracle-Validierungserweiterung verwendet wird.

Schritt 1: Definieren der Validierungserweiterung im @context des digitalen Zwillingsmodells

Der erforderliche Kontext des digitalen Zwillingsmodells, der angibt, dass das digitale Zwillingsmodell DTDL-Spezifikationen v3 verwendet: dtmi:dtdl:context;3

Um die Validierungserweiterung zu definieren, hängen Sie beim Erstellen eines digitalen Zwillingsmodells oder beim Aktualisieren eines digitalen Zwillingsmodells die Validierungserweiterung an den DTMI-URI-Wert in der @context an. Das digitale Zwillingsmodell liest diese Validierungsblöcke, um Validierungsregeln für eingehende Gerätedaten durchzusetzen. Alle Daten, die eine Validierungsregel nicht erfüllen, werden abgelehnt. Die Daten normalisiert und abgelehnt befinden sich im IoT-Datenbankschema. 

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

Schritt 2: Hinzufügen einer Eigenschaft validation zu Elementen in einem digitalen Zwillingsmodell

Verwenden Sie in digitalen Zwillingsmodellen JSON-Schemavalidierungsspezifikationen, um Validierungseigenschaften zu den validierten aufgenommenen Daten hinzuzufügen.
  • Bei primitiven Eigenschaften wie Zeichenfolgen oder Ganzzahlen werden Validierungs-Constraints als gleichgeordnete Eigenschaften neben dem Schemafeld in der Eigenschaft oder Telemetriedefinition hinzugefügt.
  • Bei Arrays gelten Validierungen für das Array selbst, wie minItems oder uniqueItems, und werden als gleichgeordnete Elemente des Arrayschemas definiert. Constraints, die für jedes Element gelten, wie Wertebereiche oder Zeichenfolgenmuster, werden innerhalb des Arrayschemas platziert, als gleichgeordnete Eigenschaften für elementSchema.

Verwenden Sie die folgenden Code-Snippets als Beispiele für Ihre digitalen Zwillingsmodelle. Eine vollständige Liste der unterstützten Validierungseigenschaften und -regeln finden Sie unter Referenz zu DTMI Validation Extension.

Digital Twin Model Snippet: Telemetrie mit Zahlenvalidierung

Dieses Code-Snippet eines digitalen Zwillingsmodells zeigt, wie der gültige Druck eines Sensors zwischen 950,0 und 1050,0 einschließlich und muss ein Vielfaches von 0,1 sein.

{
  "@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
  ]
  }

Digitales Zwillingsmodell-Snippet: Zeichenfolgenmustervalidierung

In diesem Beispiel wird die Seriennummer nach einem bestimmten Zeichenfolgenmuster validiert. In diesem Beispiel ist das Zeichenfolgenmuster ein regulärer Ausdruck, mit dem eingehende Seriennummernwerte übereinstimmen müssen. Der Seriennummernwert muss mit "SN-" beginnen, gefolgt von 4 bis 8 Großbuchstaben (A-Z) oder Ziffern (0-9) und darf vor oder nach folgenden Zeichen nicht mehr verwendet werden:

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

Digital Twin Model Snippet: Array-Validierung mit Element-Constraints

Validiert, dass die Alarmcodes ein Array von Ganzzahlen zwischen 100 und 900 sein müssen. Das Array muss mindestens 1, nicht mehr als 5 Elemente enthalten, und alle Elemente müssen eindeutig sein.
{
  "@type": ["Property", "Validated"]
  "name": "alarmCodes",
  "schema": {
    "@type": "Array",
    "elementSchema": "integer",
      "minimum": 100,
      "maximum": 900
  },
  "minItems": 1,
  "maxItems": 5,
  "uniqueItems": true
}

Digitales Zwillingsmodell-Snippet: Telemetrie mit doppelter Genauigkeit und expliziter Validierung

In diesem Beispiel wird validiert, ob der Wert eine doppelte Ganzzahl sein muss und zwischen -50,0 und 150,0 enthalten sein muss.
{
  "@type": ["Telemetry", "Validated"]
  "name": "temperature_double",
  "schema": "double",
  "minimum": -50.0,
  "maximum": 150.0
}

Digital Twin Model Snippet: Telemetrie mit einfacher Präzision und expliziter Validierung

In diesem Beispiel wird validiert, ob der Wert ein float sein muss, und der Wert muss im angegebenen Bereich zwischen -50.0 und 150.0 liegen.
{
  "@type": ["Telemetry", "Validated"]
  "name": "temperature_float",
  "schema": "float",
  "minimum": -50.0,
  "maximum": 150.0
}

Digital Twin Model Snippet: Telemetrie mit Typ, Reichweite und Schrittvalidierung

In diesem Beispiel wird der Wert double, eine ganze Zahl und zwischen 0 und 360 Grad und in Schritten von 0.1 validiert.

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