Oracle Cloud Infrastructure-Dokumentation

Digitales Zwillingsmodell erstellen

Erstellen Sie ein digitales Zwillingsmodell für Ihr Internet of Things (IoT).

Ein digitales Zwillingsmodell definiert die Semantik eines digitalen Zwillings und basiert auf den DTDL v3-Spezifikationen.

Eine digitale Zwillingsinstanz erfordert ein digitales Zwillingsmodell und einen digitalen Zwillingsadapter, um Daten von einem Gerät zu empfangen, das strukturierte Daten sendet. Spezielle Beispiele finden Sie unter Szenarios.

Hinweis

Digital Twins Definition Language (DTDL) v3 wird auf GitHub vom Digital Twin Consortium unterstützt. Achten Sie unbedingt darauf:
  • MQTT-Erweiterungen und beschreibbare Eigenschaften werden nicht unterstützt. Wenn eine Eigenschaft writable enthalten ist, muss sie auf false gesetzt werden.
  • Nur die content innerhalb der Komponente kann als historized annotiert werden. Dies gibt an, dass die IoT-Plattform die Telemetrie der Zeitreihen dieses Sensors beibehalten muss (siehe Beispiel für das digitale Zwillingsmodell dtdl-model-specifications.json unten).

Wenn Sie eine digitale Zwillingsinstanz erstellen möchten, ohne Daten von einem Gerät aufzunehmen, können Sie eine digitale Zwillingsinstanz ohne einen digitalen Zwillingsadapter und ohne den Authentifizierungs-ID-Parameter --auth-id erstellen. Das zugehörige digitale Zwillingsmodell darf keine Telemetrie oder Eigenschaften enthalten. Nachdem Sie eine Instanz für digitale Zwillinge erstellt haben, können Sie eine Beziehung für digitale Zwillinge erstellen, um Ihre IoT-Umgebung ohne die Komplexität von Daten oder Authentifizierung zu simulieren.

    1. Wählen Sie auf der Listenseite IoT-Domains die IoT-Domain aus, mit der Sie arbeiten möchten. Informationen zum Suchen der Listenseite für IoT-Domains finden Sie unter IoT-Domains auflisten.
    2. Wählen Sie die Registerkarte Digitale Zwillingsmodelle und dann Erstellen aus.
    3. Geben Sie einen Namen und optional eine benutzerfreundliche Beschreibung ein. Geben Sie dabei keine vertraulichen Informationen ein.
    4. Wählen Sie eine Option, um die DTDL-Spezifikation des Modells hinzuzufügen:
      • Um die Datei dtdl-specification.json hochzuladen, wählen Sie Spezifikation hochladen aus. Ziehen Sie eine .json-Datei mit der DTDL-Spezifikation für dieses digitale Zwillingsmodell per Drag-and-Drop, oder wählen Sie sie aus.
      • Um die JSON für das digitale Zwillingsmodell hinzuzufügen, wählen Sie Spezifikation einfügen aus.
    5. Tags: (Optional) Fügen Sie dem digitalen Zwillingsmodell ein oder mehrere Tags hinzu. Wenn Sie über Berechtigungen zum Erstellen einer Ressource verfügen, sind Sie auch berechtigt, Freiformtags auf diese Ressource anzuwenden. Um ein definiertes Tag zuzuweisen, benötigen Sie die Berechtigungen zum Verwenden des Tag-Namespace. Weitere Informationen zum Tagging finden Sie unter Ressourcentags. Wenn Sie nicht sicher sind, ob Tags angewendet werden sollen, überspringen Sie diese Option, oder fragen Sie einen Administrator. Sie können Tags später anwenden.
    6. Wählen Sie Erstellen.

    Details des digitalen Zwillingsmodells anzeigen. Kopieren Sie die zugehörige IoT-Domain-OCID, das digitale Zwillingsmodell DTMI oder die OCID des digitalen Zwillingsmodells.

    Wählen Sie die zugehörige Registerkarte aus, um die DTDL-Spezifikation, die zugehörigen digitalen Zwillingsinstanzen, zugehörige digitale Zwillingsadapter oder Tags für dieses digitale Zwillingsmodell anzuzeigen.

  • Verwenden Sie den Befehl oci iot digital-twin-model create und die erforderlichen Parameter, um ein digitales Zwillingsmodell in einer bestimmten IoT-Domain zu erstellen. Geben Sie die Spezifikationen als JSON-Inhalt direkt in der Befehlszeile oder als Datei an, die in der Befehlszeile referenziert wird:

    Inlinebeispiel: Dieses Beispiel zeigt, wie Sie die JSON-Spezifikationen direkt in der Befehlszeile angeben:

    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec '{"@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:historization;1", "dtmi:dtdl:extension:quantitativeTypes;1", "dtmi:com:oracle:dtdl:extension:validation;1"], "@id": "dtmi:com:oracle:iot:sample:hvac:UgNaNWHbzK;1", "@type": "Interface", "contents": [{"@type": ["Telemetry", "Temperature"], "name": "temperature", "schema": "integer", "unit": "degreeFahrenheit"}, {"@type": ["Telemetry", "Historized", "Validated"], "name": "humidity", "schema": "integer", "minimum": 0, "maximum": 100}, {"@type": ["Property", "Historized"], "name": "location", "schema": "point", "writable": true}, {"@type": ["Property", "Validated"], "name": "serialNumber", "schema": "string", "pattern": "^([0-9]){2}([0-9]){5}([0-9]){6}$"}]}'

    Beispiel für Dateireferenzen: In diesem Beispiel wird gezeigt, wie Sie eine Datei dtdl-model-specifications.json erstellen, die Ihre Spezifikationen enthält, und wie Sie die Datei .json im Befehl referenzieren. Das Format kann je nach Betriebssystem variieren. Weitere Informationen zum Referenzieren von Dateien finden Sie unter JSON-Datei für komplexe Eingaben verwenden:

    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://dtdl-model-specifications.json
    In diesem Snippet aus dem Beispiel des digitalen Zwillingsmodells unten:
    • Beachten Sie, dass der Wert humidity als historized-Telemetrie annotiert wird. Daher wird jeder Feuchtigkeitsstand als Zeitreihenmessung mit einem timeObserved-Zeitstempel gespeichert, anstatt nur den neuesten Wert aufzuzeichnen.
    • Außerdem wird validiert, dass es sich um eine integer im Bereich 0–100 handelt. Nur der Inhalt innerhalb einer Komponente kann als historisierter Hinweis auf diese @type-Deklaration im folgenden Beispiel mit Anmerkungen versehen werden.
    {
  "@type": ["Telemetry","Historized","Validated"],
  "name": "humidity",
  "schema": "integer",
  "minimum": 0,
  "maximum": 100
}
    In diesem HLK-Modell, dtdl-model-specifications.json
    • Dieses Modell basiert auf der DTDL v3-Spezifikation und enthält einen Digital Twin Model Identifier (DTMI) als eindeutige ID: @id: "dtmi:com:oracle:iot:sample:hvac:<unique-id>;1"
    • Dieses Beispielmodell für digitale Zwillinge ermöglicht die Historisierung, qualitative Typen und Validierungserweiterungskontexte. Siehe Referenz zu DTMI Validation Extension.
    • Wie im Snippet oben beschrieben, wird die humidity-Telemetrie mit Historized annotiert, sodass die Feuchtigkeitswerte als Zeitreihendaten beibehalten werden, und die Messwerte im Zeitverlauf.
    • Die Telemetrie location wird als Historized annotiert, sodass Änderungen am Speicherort auch im Laufe der Zeit beibehalten werden. Dabei wird die Standorthistorie der Eigenschaft mit einem Audittrail aufgezeichnet.
    • Die temperature-Telemetrie wird nicht mit "Historisiert" annotiert. Dabei wird nur der letzte bekannte Wert aufgezeichnet, der für eine andere Downstream-Persistence konfiguriert wurde.
    • Die Eigenschaft serialNumber wird mit einem regulären Ausdrucksmuster als Validated markiert und nicht als "Historisiert" annotiert. Daher wird nur der aktuelle oder der letzte Wert beibehalten, keine historische Verfolgung von Änderungen.
    {
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:historization;1",
    "dtmi:dtdl:extension:quantitativeTypes;1",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  "@id": "dtmi:com:oracle:iot:sample:hvac:UgNaNWHbzK;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "schema": "integer",
      "unit": "degreeFahrenheit"
    },
    {
      "@type": [
        "Telemetry",
        "Historized",
        "Validated"
      ],
      "name": "humidity",
      "schema": "integer",
      "minimum": 0,
      "maximum": 100
    },
    {
      "@type": [
        "Property",
        "Historized"
      ],
      "name": "location",
      "schema": "point",
      "writable": false
    },
    {
      "@type": [
        "Property",
        "Validated"
      ],
      "name": "serialNumber",
      "schema": "string",
      "pattern": "^([0-9]){2}([0-9]){5}([0-9]){6}$"
    }
  ]
}

    Diese CLI-Beispielantwort zeigt, dass das digitale Zwillingsmodell für die Domain IoT mit einer DTMI-URI erstellt wurde: dtmi:com:oracle:iot:sample:hvac:unique-id;1:

    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user",
        "CreatedOn": "2025-08-05T17:43:00.438Z"
      }
    },
    "description": null,
    "display-name": "HVAC",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:iot:sample:hvac:unique-id;1",
    "system-tags": {},
    "time-created": "2025-08-05T17:43:00.508000+00:00",
    "time-updated": "2025-08-05T17:43:00.508000+00:00"
  },
  "etag": "<unique-id>"
}

    Eine vollständige Liste der Parameter und Werte für CLI-Befehle finden Sie in CLI-Befehlsreferenz

  • Führen Sie den Vorgang CreateDigitalTwinModel aus, um ein Modell für digitale Zwillinge in der spezifischen IoT-Domain zu erstellen.

    Beispielanforderung:

    POST /20250531/digitalTwinModels
content-type: application/json+ld
{
    "@context": ["dtmi:dtdl:context;3"],
    "@id": "dtmi:com:oracle:labauto:SmartSpecimenVault;1",
    "@type": "Interface",
    "extends": "dtmi:com:oracle:iot:connectable;1",
    "displayName": "HVAC",
    "contents": [
        {"@type": "Telemetry", "name": "temperature", "schema": "integer"},
        {"@type": "Telemetry", "name": "humidity", "schema": "integer", "minimum":0, "maximum": 100},
        {"@type": "Property", "name": "desiredTemperature", "schema": "integer", "writable": false},
        {"@type": "Property", "name": "serialNumber", "schema": "string"} 
    ]
}

    Beispielantwort:

    header:
content-type: application/json
Body:
{
    "id": "<digital-twin-model-OCID>"
    "displayName": "<your-HVAC-display-name>",
    "description": "<digital-twin-model-for-HVAC>"
    "lifecycleState": "ACTIVE",
    "freeformTags": {},
    "definedTags": {
       "Oracle-Tags": {
         "CreatedBy": "default/user@oracle.com",
         "CreatedOn": "2024-07-22T10:24:53.446Z"
       }
    },
    "specUri": "dtmi:com:oracle:labauto:SmartSpecimenVault;1"
    "timeCreated": "2025-01-13T10:24:53Z",
    "timeUpdated": "2025-01-14T17:15:21Z"
}