Créer 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 de jumeau numérique définit la sémantique d'un jumeau numérique et est basé sur les spécifications DTDL v3.

Un modèle de jumeau numérique utilise un identificateur de modèle de jumeau numérique (DTMI) comme identificateur unique. Par exemple : dtmi:com:oracle:iot:connectable;1
Le contexte de modèle de jumeau numérique requis indique que le modèle de jumeau numérique utilise DTDL v3 : dtmi:dtdl:context;3
Dans les modèles de jumeaux numériques, utilisez les spécifications de validation de schéma JSON pour ajouter des propriétés de validation aux données incluses de validation. Pour savoir comment utiliser l'extension DTMI dans votre modèle de jumeau numérique, reportez-vous à Scénario : ajout d'une validation de schéma JSON à un modèle de jumeau numérique.

Une instance de jumeau numérique nécessite un modèle de jumeau numérique et un adaptateur de jumeau numérique pour recevoir des données d'un périphérique qui envoie des données structurées. Pour obtenir des exemples spécifiques, reportez-vous à Scénarios.

Remarque

Le langage DTDL (Digital Twins Definition Language) v3 est pris en charge sur GitHub par le consortium Digital Twin. Il est important de noter les points suivants :

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 définie sur false.
Seule la valeur content du composant peut être annotée en tant que historized, ce qui indique que la plate-forme IoT doit conserver la télémétrie de série temporelle de ce capteur. Reportez-vous à l'exemple de modèle de jumeau numérique dtdl-model-specifications.json ci-dessous.

Si vous souhaitez 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 de jumeau numérique et sans le paramètre d'ID d'authentification, --auth-id. Le modèle jumeau numérique associé ne doit pas contenir de télémétrie ni de propriétés. Ensuite, vous pouvez créer une instance de jumeau numérique, puis créer une relation de jumeau numérique pour simuler votre environnement IoT sans la complexité des données ni de l'authentification.

1. Dans la page de liste Domaines IoT, sélectionnez le domaine IoT avec lequel vous voulez travailler. Si vous avez besoin d'aide pour trouver la page de liste des domaines IoT, reportez-vous à Liste des domaines IoT.
2. Sélectionnez l'onglet Modèles de jumeaux numériques, puis Créer.
3. Entrez un nom et éventuellement une description conviviale. Evitez de saisir des informations confidentielles.
4. Sélectionnez une option pour ajouter la spécification DTDL du modèle :
  Pour télécharger le fichier dtdl-specification.json, sélectionnez Télécharger la spécification. Glissez-déplacez ou sélectionnez un fichier .json avec la spécification DTDL pour ce modèle de jumeau numérique.
  Pour ajouter JSON pour le modèle de jumeau numérique, sélectionnez coller la spécification.
5. Balises : (facultatif) ajoutez des balises au modèle de jumeau numérique. Si vous êtes autorisé à créer une ressource, vous disposez également des droits d'accès nécessaires pour lui appliquer des balises à format libre. Pour appliquer une balise définie, vous devez disposer de droits d'accès permettant d'utiliser l'espace de noms de balise. Pour plus d'informations sur le balisage, reportez-vous à Balises de ressource. Si vous n'êtes pas certain d'appliquer des balises, ignorez cette option ou demandez à un administrateur. Vous pouvez appliquer des balises ultérieurement.
6. Choisissez Créer.
Afficher les détails du modèle de jumeau numérique. Copiez l'OCID de domaine IoT associé, le modèle de jumeau numérique DTMI ou l'OCID de modèle de jumeau numérique.
Sélectionnez l'onglet associé pour afficher la spécification DTDL, les instances de jumeaux numériques associées, les adaptateurs de jumeaux numériques associés ou les balises pour ce modèle de jumeaux numériques.
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 en ligne : 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 contenant 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 des fichiers. Reportez-vous à 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 :
- La valeur humidity est annotée en tant que télémétrie historized. Chaque lecture d'humidité est donc stockée en tant que mesure de série temporelle avec un horodatage timeObserved, au lieu d'enregistrer uniquement la dernière valeur.
- Il est également validé comme étant un integer dans la plage 0–100. Seul le contenu d'un composant peut être annoté comme l'indique l'historique de 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 de CVC, 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'historique, les types qualitatifs et les contextes d'extension de validation. Reportez-vous à Référence d'extension de validation DTMI.
- Comme décrit dans le fragment de code ci-dessus, la télémétrie humidity est annotée en tant que Historized, de sorte que les lectures d'humidité sont conservées en tant que données de séries temporelles, lectures au fil du temps.
- La télémétrie location est annotée en tant que Historized. Les modifications apportées à l'emplacement sont donc également conservées au fil du temps. L'historique de l'emplacement de la propriété est enregistré avec une trace d'audit.
- La télémétrie temperature n'est pas annotée avec Historized, enregistrant uniquement la dernière valeur connue, une autre persistance en aval configurée ailleurs.
- La propriété serialNumber est marquée comme Validated à l'aide d'un modèle d'expression régulière et n'est pas annotée comme Historisée. Par conséquent, seule la valeur en cours ou la dernière valeur est maintenue et non 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 CLI 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 obtenir la liste complète des paramètres et des valeurs des commandes de la CLI, reportez-vous à Référence des commandes de la CLI

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

Documentation Oracle Cloud Infrastructure

Créer un modèle de jumeau numérique