Documentation sur Oracle Cloud Infrastructure

Création d'un modèle de jumeau numérique

Créez un modèle de jumeau numérique pour votre Internet of Things (IoT).

Un modèle à jumeau numérique définit la sémantique d'un jumeau numérique et est basé sur les spécifications DTDL v3.

Une instance jumeau numérique nécessite un modèle jumeau numérique et un adaptateur jumeau numérique pour recevoir des données d'un appareil qui envoie des données structurées. Pour des exemples spécifiques, voir Scénarios.

Note

DTDL (Digital Twins Definition Language) v3 est pris en charge sur GitHub par le consortium Digital Twin. Il est important de noter :
  • Les extensions MQTT et les propriétés accessibles en écriture ne sont pas prises en charge. Si une propriété writable est incluse, elle doit être réglée à false.
  • Seule la valeur content dans le composant peut être annotée en tant que historized, indiquant que la plate-forme IoT doit conserver la télémétrie de série chronologique de ce capteur. Voir l'exemple de modèle de jumeau numérique dtdl-model-specifications.json ci-dessous.

Si vous voulez créer une instance de jumeau numérique sans données ingérables à partir d'un appareil, vous pouvez créer une instance de jumeau numérique sans adaptateur jumeau numérique et sans le paramètre ID d'authentification, --auth-id. Le modèle jumeau numérique associé ne doit pas contenir de télémétrie ou de propriétés. Après avoir créé une instance de jumeau numérique, vous pouvez créer une relation de jumeau numérique pour simuler votre environnement IdO sans la complexité des données ou de l'authentification.

    1. Dans la page de liste Domaines IdO, sélectionnez le domaine IdO avec lequel vous voulez travailler. Si vous avez besoin d'aide pour trouver la page de liste des domaines IoT, voir Liste des domaines IoT.
    2. Sélectionnez l'onglet Modèles jumeaux numériques, sélectionnez Créer.
    3. Entrez un nom et, facultativement, une description conviviale. Évitez d'entrer des informations confidentielles.
    4. Sélectionner une option pour ajouter la spécification DTDL du modèle :
      • Pour charger votre fichier dtdl-specification.json, sélectionnez Charger la spécification. Glissez-déposez ou sélectionnez un fichier .json avec la spécification DTDL pour ce modèle de jumeau numérique.
      • Pour ajouter la valeur JSON pour le modèle de jumeau numérique, sélectionnez Coller la spécification.
    5. Marqueurs : (Facultatif) Ajoutez un ou plusieurs marqueurs au modèle de jumeau numérique. Si vous êtes autorisé à créer une ressource, vous disposez également des autorisations nécessaires pour appliquer des marqueurs à structure libre à cette ressource. Pour appliquer un marqueur défini, vous devez être autorisé à utiliser l'espace de noms de marqueur. Pour plus d'informations sur le marquage, voir Marqueurs de ressource. Si vous ne savez pas si vous devez appliquer des marqueurs, ignorez cette option ou demandez à un administrateur. Vous pouvez appliquer des marqueurs plus tard.
    6. Sélectionnez Créer.

    Voir les détails du modèle de jumeau numérique. Copiez l'OCID du domaine de l'Internet des objets associé, le modèle de jumeau numérique DTMI ou l'OCID du modèle de jumeau numérique.

    Sélectionnez l'onglet connexe pour voir la spécification DTDL, les instances de jumeau numérique associées, les adaptateurs de jumeau numérique associés ou les marqueurs pour ce modèle de jumeau numérique.

  • Utilisez la commande oci iot digital-twin-model create et les paramètres requis pour créer un modèle de jumeau numérique dans un domaine IoT spécifique. Fournissez les spécifications en tant que contenu JSON directement dans la ligne de commande ou en tant que fichier référencé dans la ligne de commande :

    Exemple inséré : Cet exemple montre comment fournir les spécifications JSON directement dans la ligne de commande :

    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}$"}]}'

    Exemple de référence de fichier : Cet exemple montre comment créer un fichier dtdl-model-specifications.json qui contient vos spécifications et comment référencer le fichier .json dans la commande. Le format peut varier en fonction de votre système d'exploitation pour plus d'informations sur le référencement de fichiers, voir Utilisation d'un fichier JSON pour une entrée complexe :

    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://dtdl-model-specifications.json
    Dans cet extrait de l'exemple de modèle de jumeau numérique ci-dessous :
    • Notez que la valeur humidity est annotée en tant que télémétrie historized, de sorte que chaque lecture d'humidité est stockée en tant que mesure de série chronologique avec un horodatage timeObserved, au lieu d'enregistrer uniquement la dernière valeur.
    • Il est également validé pour être un integer dans l'intervalle 0–100. Seul le contenu d'un composant peut être annoté en tant qu'historique. Notez cette déclaration @type dans l'exemple ci-dessous.
    {
  "@type": ["Telemetry","Historized","Validated"],
  "name": "humidity",
  "schema": "integer",
  "minimum": 0,
  "maximum": 100
}
    Dans ce modèle HVAC, dtdl-model-specifications.json
    • Ce modèle est basé sur la spécification DTDL v3 et contient un identificateur de modèle jumeau numérique (DTMI) en tant qu'identificateur unique : @id: "dtmi:com:oracle:iot:sample:hvac:<unique-id>;1"
    • Cet exemple de modèle de jumeau numérique permet l'historisation, les types qualitatifs et les contextes d'extension de validation. Voir Informations de référence sur l'extension de validationDTMI.
    • Comme décrit dans l'extrait de code au-dessus de la télémétrie humidity est annoté comme Historized, de sorte que les lectures d'humidité sont conservées comme des données de série chronologique, des lectures au fil du temps.
    • La télémétrie location étant annotée en tant que Historized, les modifications apportées à l'emplacement sont également conservées au fil du temps, en enregistrant l'historique des emplacements de la propriété avec une piste de vérification.
    • La télémétrie temperature n'est pas annotée avec Historized, enregistrant uniquement la dernière valeur connue d'une autre persistance en aval configurée ailleurs.
    • La propriété serialNumber est marquée Validated à l'aide d'un modèle d'expression rationnelle et n'est pas annotée en tant qu'historisée. Par conséquent, seule la valeur courante ou la plus récente est tenue à jour et ne constitue pas un suivi historique des modifications.
    {
  "@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}$"
    }
  ]
}

    Cet exemple de réponse de l'interface de ligne de commande montre que le modèle de jumeau numérique a été créé pour le domaine IoT, avec un URI DTMI : 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>"
}

    Pour la liste complète des paramètres et des valeurs pour les commandes de l'interface de ligne de commande, voir Informations de référence sur les commandes de l'interface de ligne de commande.

  • Exécutez l'opération CreateDigitalTwinModel pour créer un modèle de jumeau numérique dans le domaine IoT spécifique.

    Exemple de demande :

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

    Exemple de réponse :

    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"
}