Szenario: Maßeinheiten mit einem digitalen Zwillingsadapter normalisieren

Code-Snippets, die Sie in Ihrem digitalen Zwillingsmodell verwenden können, auf das in den folgenden Schritten verwiesen wird:

• model.json: Digitales Zwillingsmodell basierend auf DTDL v3-Spezifikationen mit einer Telemetrieeigenschaft speed in Meilen pro Stunde, die eine Validierungserweiterung verwendet, die Grenzwerte für den Wertebereich von 0 bis 100 anwendet.
• envelope.json: Envelope-Konfiguration, die einen Referenzendpunkt und eine Beispiel-Payload-Ausprägung deklariert.
• routes.json: Routenbedingungen und Payload-Zuordnungen, die Kilometer pro Stunde in Meilen pro Stunde umrechnen.
• script.sh: In diesem Beispiel können Sie alle unten aufgeführten OCI-CLI-Befehle speichern, um ein digitales Zwillingsmodell, einen Adapter und Instanzen sowie die curl-Befehle zur POST-Beispieltelemetrie zu erstellen und dann als Shellskript script.sh auszuführen.

• Um die Schritte in diesem Szenario abzuschließen, können Sie die OCI-CLI und die curl-Befehle erstellen und speichern, die in den folgenden Schritten aufgeführt sind, und dieses Szenario als Shellskript ausführen: script.sh

In diesem Beispiel verwendet das Code-Snippet für das digitale Zwillingsmodell model.json eine benutzerdefinierte Erweiterung dtmi:com:oracle:dtdl:extension:validation;1, die Validierungsregeln für das JSON-Schema für die "Telemetry", "Historized", "Validated", "Velocity"-Elemente anwendet. Wenn die Daten nicht mit den erwarteten Werten übereinstimmen, die in dieser Validierung definiert sind, werden die Daten abgelehnt.

Eine vollständige Liste der unterstützten Validierungseigenschaftsregeln finden Sie unter Referenz zu DTMI Validation Extension.

model.json

{
  "@context":[
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:historization;1",
    "dtmi:com:oracle:dtdl:extension:validation;1",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "@id":"dtmi:com:oracle:iot:poc:testmodel;1",
  "@type":"Interface",
  "contents":[
    {
      "@type":[ "Telemetry", "Historized", "Validated", "Velocity" ],
      "displayName":"Speed",
      "name":"speed",
      "schema":"integer",
      "unit":"milePerHour",
      "minimum":0,
      "maximum":100
    }
  ]
}

envelope.json

{
  "referenceEndpoint": "telemetry/automotive/usa-standard-units",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "speed": 65
    }
  }
}

[
  {
    "description" : "Automotive data using metric units (kilometers) that's converted to miles, with a different external key in the digital twin instance",
    "condition" : "${endpoint(3) == \"metric-units\"}",
    "payloadMapping" : { 
      "$.speed": "${(.velocity_kph / 1.609) | floor}"

    },
    "referencePayload" : {
      "dataFormat" : "JSON",
      "data" : { "velocity_kph": 104 }
    }
  },
  {
    "description" : "Auto 1 and Auto 2 use USA standard units, shows speed as is.", 
    "condition" : "*",
    "payloadMapping" : { "$.speed": "$.speed" }
  }
]

Verwenden Sie diesen CLI-Befehl oci iot digital-twin-model create, um ein digitales Zwillingsmodell mit der Datei model.json zu erstellen. Dieses digitale Zwillingsmodell standardisiert speed in Meilen pro Stunde.

Dieser Befehl registriert das digitale Zwillingsmodell mit dieser DTMI-URI dtmi:com:oracle:iot:poc:testmodel;1, wie oben in model.json definiert.

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-ocid> \
  --display-name "Test Digital Twin Model" \
  --description "Model for testing automotive telemetry routing and unit normalization" \
  --spec file://~/model.json

Erstellen Sie einen Adapter, der die Spezifikation des digitalen Zwillingsmodells DTMI referenziert und den eingehenden Umschlag und die Routen verwendet, um die eingehende Telemetrie zu normalisieren.

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-ocid> \
  --display-name "automotive-speed-adapter" \
  --description "Routes by units" \
  --digital-twin-model-spec-uri "dtmi:com:oracle:iot:poc:testmodel;1" \
  --inbound-envelope file://~/envelope.json \
  --inbound-routes file://~/routes.json

Die referenceEndpoint in envelope.json ist telemetry/automotive/usa-standard-units. Die Datei routes.json:

• Leitet Anforderungen an das dritte Pfadsegment weiter, das metric-units entspricht, z.B. /telemetry/automotive/metric-units, und konvertiert dann velocity_kph in mph in speed und legt das Ergebnis fest.
• Verwendet eine standardmäßige Catch-All-Bedingung (*), um speed unverändert für Automobile zu durchlaufen, die Meilen pro Stunde verwenden.

Digitale Zwillingsinstanz für die USA-Standardeinheiten, Meilen pro Stunde (mph), beachten Sie den externen Schlüssel:

oci iot digital-twin-instance create \
  --iot-domain-id <IoT-domain-ocid> \
  --display-name "auto using miles per hour" \
  --external-key american-auto-standard-units \
  --digital-twin-adapter-id <same-digital-twin-adapter-ocid> \
  --auth-id <secret-ocid-or-certificate-ocid>

european-auto-metric-units

oci iot digital-twin-instance create \
  --iot-domain-id <IoT-domain-ocid> \
  --display-name "auto using kilometers per hour" \
  --external-key european-auto-metric-units \
  --digital-twin-adapter-id <same-digital-twin-adapter-ocid> \
  --auth-id <secret-ocid-or-certificate-ocid>

Um Telemetrie zu senden, benötigen Sie den externen Schlüssel aus der Antwort der digitalen Zwillingsinstanz aus Schritt 3, das Gerätekennwort und den Gerätehostendpunkt.

Wenn die Instanz des digitalen Zwillings das Vault Secret zur Authentifizierung verwendet, müssen Sie als Basiskodierungs-Secret-Wert mit 64 als Gerätekennwort verwenden.

-u "external-key:device-password-secret-contents-or-certificate"

curl -i -X POST \
  -u "european-auto-metric-units:device-password-secret-or-certificate" \
  -H "Content-Type: application/json" \
  "https://device-host/telemetry/automotive/metric-units" \
  -d '{ "velocity_kph": 0 }'

curl -i -X POST \
  -u "european-auto-metric-units:device-password-secret-or-certificate" \
  -H "Content-Type: application/json" \
  "https://device-host/telemetry/automotive/metric-units" \
  -d '{ "velocity_kph": 110 }'

curl -i -X POST \
  -u "american-auto-standard-units:device-password-secret-or-certificate" \
  -H "Content-Type: application/json" \
  "https://device-host/telemetry/automotive/usa-standard-units" \
  -d '{ "speed": 0 }'

curl -i -X POST \
  -u "american-auto-standard-units:device-password-vault-secret-base-64-or-certificate-OCID" \
  -H "Content-Type: application/json" \
  "https://device-host/telemetry/automotive/usa-standard-units" \
  -d '{ "speed": 60 }'

Die Routingbedingung ${endpoint(3) == "metric-units"} wertet die Daten aus und wendet die folgende Payload-Zuordnung auf den Datenendpunkt der Metrikeinheiten an:

"$.speed": "${(.velocity_kph / 1.609) | floor}"

Erwartetes Ergebnis:

• Die Zuordnung des Adapters konvertiert Kilometer pro Stunde (kph) in Meilen pro Stunde (mph) und wendet dann die Etage an, um ein Ganzzahlenschema zu erfüllen:

  speed_mph = floor(velocity_kph / 1.609)

• In diesem Beispiel wird velocity_kph = 0: speed_mph = floor(0 / 1.609) = floor(0) = 0 mph

  Nach dem Stockwerk wird der Rundungsschritt angezeigt, der das Ergebnis zu einer ganzen Zahl zwingt und auf eine negative Unendlichkeit abrundet. Dies ist erforderlich, wenn Ihr DTDL-Modell die Geschwindigkeitstelemetrie als schema: "integer" deklariert, sodass der Wert eine Ganzzahl ist, keine Gleitkommazahl oder Zeichenfolge.

• velocity_kph = 110 → speed = floor(110 / 1.609) = 68 mph
• Standarddatenposts mit speed werden unverändert übergeben. Beispiel: Die Werte aus diesem Beispiel: 0, 60

Wenn die Modellvalidierung minimum: 0, maximum: 100 aktiviert ist, werden Out-of-Range-Werte gemäß den Validierungsregeln abgelehnt.

Verwendet die Konvertierung von Soft-Typen:

• Durchgang (mph, Schema "integer"): {"speed": "60"} und {"speed": 60.0} werden als 60 gespeichert. {"speed": "60.2"} wird abgelehnt, es sei denn, Coerces werden einer Ganzzahl zugeordnet (z.B. mit floor).
• Metrikroute (kph → mph): {"velocity_kph": 110} → 68; {"velocity_kph": "110"} → 68, da das Mapping floor eine Ganzzahl ausgibt. Behalten Sie arithmetische Eingaben numerisch bei, um Ausdrucksfehler zu vermeiden. Verwenden Sie nach Möglichkeit 110 gegenüber "110".
• Rundung bleibt explizit: Bei der Soft-Konvertierung wird 68.35 nicht automatisch in 68 gerundet. Verwenden Sie floor als Ganzzahlenschema, oder wechseln Sie das Modell zu schema: "double", um Brüche beizubehalten.

• Referenz-JSON-Dateien für Spezifikationen und Adapter für digitale Zwillingsmodelle: Wenn Sie einen Adapter mit der CLI hochladen, können Sie mit JSON-Dateien Datenmapping angeben. In CLI-Befehlen können Sie Dateien als file://~/name.json referenzieren oder je nach Shellumgebung einen absoluten oder relativen Pfad angeben. Abhängig von Ihrem Betriebssystem können Sie eine etwas andere Syntax mit Anführungszeichen, Schrägstrichen oder dem Speicherort der Datei standardmäßig verwenden. Siehe CLI-Eingabe und -Ausgabe verwalten und JSON-Datei für komplexe Eingaben verwenden.
• JSON-Konfigurationsdateien (Envelope, Routen) verwenden API-Feldnamen in camelCase (Beispiel: referenceEndpoint). Die OCI-CLI übergibt diese Dateien unverändert über die Argumente file://, sodass die Verwendung von camelCase JSON mit der CLI erwartet und korrekt ist.
• Die referenceEndpoint in envelope.json muss einen typischen Endpunkt für Ihren Adapter widerspiegeln.
• Wildcard-Routenbedingung (*) wird nach bestimmten Bedingungen ausgewertet. Ordnen Sie die Routendefinitionen entsprechend an.
• Soft Conversion Scope: Numerische Zeichenfolgen und ganzzahlige Doppelzeichenfolgen werden akzeptiert, wenn sie mit dem Modelltyp übereinstimmen (z.B. Ganzzahl). Casting-Helfer wie number() und toInteger werden in Routenausdrücken weiterhin nicht unterstützt. Verlassen Sie sich auf arithmetische Werte und floor, oder übernehmen Sie schema: "double", um Fraktionen beizubehalten.

Diese Variation zeigt, wie sich das Festlegen des Modelleigenschaftsschemas auf double auf die Adapterzuordnung und die aufgezeichneten Werte auswirkt. Bei double akzeptiert der Validator jeden numerischen Integral- oder Bruchteilwert, der den Bereichs-Constraints entspricht, ohne dass automatisch gerundet wird. Sie können die Bruchstellengenauigkeit (Roh) beibehalten oder mit floor auf ganze Zahlen zwingen. Beide übergeben die Validierung, solange die Werte im definierten Bereich verbleiben.

Was bewirkt die schema=double-Validierung?

• Typannahme: Akzeptiert JSON-Zahlen mit oder ohne Bruchteilen. Beispiel: 60, 68.35. Zeichenfolgen wie "68" bleiben ungültig.
• Bereich: Mindest- und Höchstwert. Beispiel: In diesem Beispiel wird 0–100 durchgesetzt.
• Keine automatische Rundung: Die IoT-Plattform rundet keine Werte. Sie steuern die Rundung in der Zuordnung des digitalen Zwillingsadapters oder den Downstream mit APEX oder SQL, je nachdem, welche Systeme zur Anzeige Ihrer Daten konfiguriert sind.

In dieser Variante verwendete Dateien:

• model_double.json: DTDL-Modell mit schema: "double".

  {
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:historization;1",
      "dtmi:com:oracle:dtdl:extension:validation;1",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "@id": "dtmi:com:oracle:iot:poc:testmodeldouble;1",
    "@type": "Interface",
    "contents": [
      {
        "@type": [
          "Telemetry",
          "Historized",
          "Validated",
          "Velocity"
        ],
        "displayName": "Speed",
        "name": "speed",
        "schema": "double",
        "unit": "milePerHour",
        "minimum": 0,
        "maximum": 100
      }
    ]
  }

• routes_double_raw.json: Beim Mapping wird die fraktionale Genauigkeit beibehalten: "$.speed": "${.velocity_kph / 1.609}".

  [
    {
      "description": "Double model: European metric units to miles per hour (mph); preserving fractional precision (no floor).",
      "condition": "${endpoint(3) == \"metric-units\"}",
      "payloadMapping": {
        "$.speed": "${.velocity_kph / 1.609}"
      },
      "referencePayload": {
        "dataFormat": "JSON",
        "data": { "velocity_kph": 110 }
      }
    },
    {
      "description": "Double model: USA standard units passthrough.",
      "condition": "*",
      "payloadMapping": { "$.speed": "$.speed" }
    }
  ]

• routes_double_floor.json: Mapping-Coerces zu ganzzahliger mph: "$.speed": "${(.velocity_kph / 1.609) | floor}" als Double gespeichert.

  [
    {
      "description": "Double model: European metric units to miles per hour (mph); floor to whole number (stored as double).",
      "condition": "${endpoint(3) == \"metric-units\"}",
      "payloadMapping": {
        "$.speed": "${(.velocity_kph / 1.609) | floor}"
      },
      "referencePayload": {
        "dataFormat": "JSON",
        "data": { "velocity_kph": 110 }
      }
    },
    {
      "description": "Double model: USA standard units passthrough.",
      "condition": "*",
      "payloadMapping": { "$.speed": "$.speed" }
    }
  ]
  

Schritt A: Erstellen Sie das digitale Zwillingsmodell mit Doppel

oci iot digital-twin-model create \
  --iot-domain-id iot-domain-ocid \
  --display-name "TestModelSpeedDouble" \
  --spec file://model_double.json

Schritt B: Erstellen Sie zwei Adapter, die dem Doppelmodell zugeordnet sind

Verwenden Sie Rohwerte, um die Nachkommastellen für Bruchteile beizubehalten:

oci iot digital-twin-adapter create \
  --iot-domain-id iot-domain-ocid \
  --display-name "auto-adapter-double-raw" \
  --digital-twin-model-id double-model-ocid \
  --inbound-envelope file://envelope.json \
  --inbound-routes file://routes_double_raw.json

Floor verwendet eine ganze Zahl als MPH, das ist ein Double:

oci iot digital-twin-adapter create \
  --iot-domain-id iot-domain-ocid \
  --display-name "auto-adapter-double-floor" \
  --digital-twin-model-id double-model-ocid \
  --inbound-envelope file://envelope.json \
  --inbound-routes file://routes_double_floor.json

Schritt C: Erstellen Sie digitale Zwillingsinstanzen für jeden Adapter

oci iot digital-twin-instance create \
  --iot-domain-id iot-domain-ocid \
  --display-name "american-auto-raw" \
  --external-key american-auto-raw \
  --digital-twin-adapter-id adapter-double-raw-ocid \
  --auth-id vault-secret-ocid

oci iot digital-twin-instance create \
  --iot-domain-id iot-domain-ocid \
  --display-name "european-auto-raw" \
  --external-key european-auto-raw \
  --digital-twin-adapter-id adapter-double-raw-ocid \
  --auth-id vault-secret-ocid

oci iot digital-twin-instance create \
  --iot-domain-id iot-domain-ocid \
  --display-name "american-auto-dfloor" \
  --external-key american-auto-dfloor \
  --digital-twin-adapter-id adapter-double-floor-ocid \
  --auth-id vault-secret-ocid

oci iot digital-twin-instance create \
  --iot-domain-id iot-domain-ocid \
  --display-name "european-auto-dfloor" \
  --external-key european-auto-dfloor \
  --digital-twin-adapter-id adapter-double-floor-ocid \
  --auth-id vault-secret-ocid

Schritt D: Posten Sie Beispieltelemetrie und vergleichen Sie Ergebnisse

 -u "external-key:device-password" \

RAW-Werte (double, no floor):

curl -i -X POST \
  -u "american-auto-raw:device-password" \
  -H "Content-Type: application/json" \
  "https://device-host/telemetry/automotive/usa-standard-units" \
  -d '{ "speed": 60 }'

curl -i -X POST \
  -u "european-auto-raw:device-password" \
  -H "Content-Type: application/json" \
  "https://device-host/telemetry/automotive/metric-units" \
  -d '{ "velocity_kph": 110 }'

Erwartetes Ergebnis: Der zweite Beitrag erzeugt ca. 68.35… mph (fraktional) und wird akzeptiert, da schema=double Bruchzahlen innerhalb des Bereichs akzeptiert.

Boden (Doppelzimmer, mit Boden):

curl -i -X POST \
  -u "american-auto-dfloor:device-password" \
  -H "Content-Type: application/json" \
  "https://device-host/telemetry/automotive/usa-standard-units" \
  -d '{ "speed": 60 }'

curl -i -X POST \
  -u "european-auto-dfloor:device-password" \
  -H "Content-Type: application/json" \
  "https://device-host/telemetry/automotive/metric-units" \
  -d '{ "velocity_kph": 110 }'

Erwartetes Ergebnis: Der zweite Beitrag erzeugt 68 eine ganzzahlige Zahl und ist akzeptiert. Der Wert wird als Double-Wert gespeichert, z.B. 68.0, obwohl er eine Ganzzahl ist.

Hinweise zu Benutzernamenangeboten und nachgelagerten Auswirkungen

• Externer Schlüssel entspricht Authentifizierungsbenutzernamen: Wenn eine digitale Zwillingsinstanz mit Anführungszeichen im externen Schlüsselwert erstellt wird, z.B. "\"american-auto-standard-units\"", muss der Basisauthentifizierungsbenutzername in der curl-Anforderung die Anführungszeichen enthalten, oder es tritt eine Unstimmigkeit auf und führt zu einem 401 Unauthorized-Fehler. Um Probleme bei der Angebotserstellung zu vermeiden, sollten Sie in Ihrem externen Schlüsselwert keine Anführungszeichen verwenden, wie in den Beispielen in diesem Szenario.
• Downstream in APEX oder mit SQL: Mit schema=double werden fraktionierte MPH-Werte beibehalten. Wenn Sie Ganzzahlen in Berichten benötigen, wenden Sie FLOOR und ROUND in SQL an. Beispiel: SELECT FLOOR(speed) FROM …. Stellen Sie mit schema=integer sicher, dass das Mapping beispielsweise Integralwerte ausgibt, indem Sie floor verwenden, um die Ganzzahltypierung zu erfüllen.
• Ausdrucksunterstützung: inbound-route akzeptiert arithmetische Werte und floor. Funktionen wie toInteger oder number wurden abgelehnt und werden nicht unterstützt. Verwenden Sie floor, oder übernehmen Sie schema: "double" für die partielle Annahme.