Scénario : mise à niveau d'une instance de jumeau numérique vers une version de modèle de jumeau numérique compatible

Mettez à niveau une instance de jumeau numérique en créant une version mineure compatible du modèle de jumeau numérique, en créant un nouvel adaptateur de jumeau numérique pour cette version de modèle de jumeau numérique, puis en mettant à jour l'instance de jumeau numérique pour utiliser le nouvel adaptateur de jumeau numérique sans supprimer l'instance de jumeau numérique.

Utilisez ce scénario lorsqu'un périphérique de remplacement ou mis à niveau envoie une forme de charge utile supplémentaire, telle qu'une nouvelle valeur de télémétrie, et que vous souhaitez préserver la continuité pour l'instance de jumeau numérique existante. Le modèle de jumeau numérique reste le contrat pour les données normalisées. L'adaptateur jumeau numérique mappe la charge utile de l'appareil entrant avec ce contrat.

OCI IoT prend en charge la mise à jour d'une instance de jumeau numérique active vers un autre adaptateur de jumeau numérique lorsque le nouvel adaptateur de jumeau numérique référence la même version de modèle de jumeau numérique ou une version mineure supérieure compatible du même modèle de jumeau numérique. Ce scénario montre comment construire sur un modèle de jumeau numérique HVAC de base et comment créer une nouvelle version de modèle de jumeau numérique HVAC avec un capteur supplémentaire tout en conservant le modèle de jumeau numérique précédent intact.

Les modifications majeures de la version du modèle de jumeau numérique sont incompatibles pour ce flux de mise à niveau. Les rétrogradations ne sont pas prises en charge.

HVAC signifie Chauffage, Ventilation et Climatisation, en référence aux différents systèmes utilisés dans les bâtiments pour réguler la température intérieure, l'humidité et la qualité de l'air globale.

Tâches

Vérifiez les règles de gestion des versions des modèles de jumeaux numériques compatibles.
Créez le modèle de jumeau numérique HVAC de base.
Créez l'adaptateur jumeau numérique HVAC de base.
Créez l'instance de jumeau numérique.
Envoyer la télémétrie à l'instance de jumeau numérique de base.
Créez une version de modèle de jumeau numérique mineur compatible.
Créez un adaptateur jumeau numérique pour la nouvelle version du modèle jumeau numérique.
Mettez à jour l'instance de jumeau numérique pour utiliser le nouvel adaptateur de jumeau numérique.
Validez la télémétrie d'instance de jumeau numérique après la mise à niveau.
Consultez les FAQ.
Résoudre les problèmes de mise à niveau des modèles de jumeaux numériques.

Meilleures pratiques

Ajout de valeurs à un modèle de jumeau numérique existant : suivez les étapes de ce scénario pour créer une version DTMI mineure pour les modifications de modèle de jumeau numérique additif, par exemple, modifier la version numéro compris entre 1 et 1.1, la version principale de DTMI reste la même lors de la mise à jour d'une instance de jumeau numérique existante vers un nouvel adaptateur de jumeau numérique, comme pris en charge dans la spécification DTDL v3 :
dtmi:com:oracle:example:hvac;1 à dtmi:com:oracle:example:hvac;1.1
Création de nouvelles valeurs dans votre modèle de jumeau numérique, puis création d'une nouvelle instance de jumeau numérique : utilisez une nouvelle version DTMI majeure lorsque vous devez créer un modèle de jumeau numérique avec des valeurs différentes. Pour ce type de mise à jour, vous devez créer une nouvelle instance de jumeau numérique avec un nouveau modèle de jumeau numérique changement majeur de version, par exemple :
dtmi:com:oracle:example:hvac;1 à dtmi:com:oracle:example:hvac;2
Héritage recommandé : pour les mises à jour mineures, l'ajout de nouvelles valeurs, il est recommandé d'utiliser l'héritage pour les modifications de modèle de jumeau numérique additif, telles qu'un modèle de jumeau numérique qui étend la version de modèle de jumeau numérique précédente. Au lieu de redéfinir les attributs de base tels que @id, l'emplacement ou le statut de base pour chaque nouvelle version de modèle de jumeau numérique, le nouveau modèle de jumeau numérique hérite automatiquement des valeurs, réduisant ainsi les erreurs et réduisant le temps de développement.
Gardez la télémétrie, les propriétés, les commandes, les relations et les schémas existants compatibles. Ne renommez pas, ne supprimez pas, ne réduisez pas ou ne modifiez pas les éléments de contrat existants lors d'une mise à niveau mineure.
Créez un nouvel adaptateur jumeau numérique pour la nouvelle version du modèle jumeau numérique et conservez l'adaptateur jumeau numérique précédent disponible pour annulation jusqu'à ce que les périphériques mis à niveau soient validés.
Tester les charges utiles avec une télémétrie représentative avant un déploiement de production.

Comprendre les fichiers de ce scénario

hvac-model.json : Modèle double numérique DTDL de base pour la télémétrie de température et d'humidité.
hvac-envelope.json : enveloppe d'adaptateur double numérique de base qui extrait timeObserved.
hvac-routes.json : cartographie de route de l'adaptateur double numérique de base pour la température et l'humidité.
hvac-e-model.json : Version mineure compatible de modèle double numérique de DTDL qui ajoute la télémétrie de consommation d'énergie.
hvac-e-envelope.json : enveloppe d'adaptateur double numérique mise à niveau qui accepte le champ de télémétrie supplémentaire.
hvac-e-routes.json : mise à niveau de la cartographie d'itinéraire de l'adaptateur double numérique pour la température, l'humidité et la consommation d'énergie.

Étape 1 : Examiner les règles de gestion des versions des modèles numériques jumelles compatibles

Lorsque vous créez un modèle de jumeau numérique, OCI IoT vérifie si un modèle de jumeau numérique actif existe déjà pour la même version majeure.

S'il en existe un, un nouveau modèle jumeau numérique de version mineure doit être un modèle strictement additif avec un numéro de version et des valeurs compatibles. Lorsque vous mettez à jour une instance de jumeau numérique pour utiliser un autre adaptateur de jumeau numérique, l'adaptateur doit référencer la même version de modèle de jumeau numérique ou une version mineure supérieure compatible.

Les vérifications de compatibilité suivantes s'appliquent entre l'ancienne version du modèle de jumeau numérique et la nouvelle version du modèle de jumeau numérique :

Lorsque vous créez une interface de jumeau numérique mise à niveau et une version de modèle, la nouvelle version mineure doit correspondre exactement à la version mineure précédente plus .1, par exemple :

dtmi:com:oracle:example:hvac;1 à dtmi:com:oracle:example:hvac;1.1

Toutes les valeurs de l'interface @id, y compris le schéma et le chemin, doivent correspondre, la nouvelle version mineure ne peut être nouvelle que le numéro de version avec des incréments mineurs et toutes les valeurs supplémentaires ajoutées au modèle existant. Les mises à niveau ne sont compatibles que lorsque la version principale reste constante et reste inchangée.

Elément DTDL	Règle de compatibilité	Remarque
`Interface`	Les valeurs `extends` existantes doivent rester identiques. Les extensions supplémentaires sont autorisées. Tous les contenus de modèle existants doivent porter le même nom. Un nouveau contenu est autorisé. Les ensembles de schémas doivent avoir la même taille et les mêmes chemins d'ID de schéma.	L'ajout de schémas d'interface réutilisables n'est pas pris en charge et rejeté.
`Telemetry`	La télémétrie existante doit conserver le même nom, la même classe DTDL, les mêmes types sémantiques ou auxiliaires, le même chemin `@id`, la même unité, le même schéma et les mêmes contraintes de validation.	`comment`, `displayName` et `description` ne sont pas comparés.
`Property`	Les propriétés existantes doivent conserver les mêmes règles de contenu, paramètres d'écriture, schéma, unité et contraintes de validation.	S'applique aux propriétés d'interface et de relation.
`Command`	Les commandes existantes doivent rester. La présence de demandes et de réponses, les noms, les schémas et les contraintes de validation doivent correspondre.	L'ajout, la suppression ou la modification d'une demande ou d'une réponse est incompatible.
`Relationship`	Les relations existantes doivent conserver les mêmes paramètres d'écriture, cible, multiplicité minimale, multiplicité maximale et propriétés de relation existantes.	Les nouvelles propriétés de relation sont autorisées.
`Component`	Le schéma de composant doit rester le même.	L'interface de composant référencée n'est pas comparée de manière récursive dans cette vérification.
`Schema`	Le type de schéma concret doit rester le même. Les schémas `primitive`, `geospatial`, `array`, `enum`, `map`, `object` et `field` existants doivent conserver des types et des contraintes de validation compatibles.	Les modifications `Primitive-to-object`, `enum-to-map` et similaires sont incompatibles.
`Enum`	Les valeurs `enum` existantes doivent rester avec le même nom et la même valeur littérale.	Les nouvelles valeurs `enum` sont autorisées.
`Object`	Les champs existants doivent rester. Chaque schéma de champ et chaque contrainte de validation existants doivent correspondre.	Les nouveaux champs `object` sont autorisés.
`Interface schemas`	Chaque ancien schéma réutilisable doit exister dans le nouveau modèle de jumeau numérique par le même schéma et le même chemin DTMI et transmettre sa comparaison spécifique au schéma.	La suppression ou la modification d'un schéma réutilisable existant est incompatible. Les nouveaux schémas réutilisables sont autorisés lorsqu'ils sont pris en charge.

Étape 2 : Créer le modèle de jumeau numérique HVAC de base

Créez le modèle jumeau numérique de base avec la télémétrie de température et d'humidité.

Utilisez la console pour créer le modèle de jumeau numérique HVAC de base dans le domaine IoT.

Sur la page de liste Domaines IoT, ouvrez le domaine IoT avec lequel vous voulez travailler.
Sélectionnez l'onglet Modèles de jumeaux numériques, puis sélectionnez Créer.
Téléchargez ou collez le fichier JSON DTDL à partir de hvac-model.json.
Choisissez Créer.

hvac-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}

Utilisez la commande oci iot digital-twin-model create pour créer le modèle de jumeau numérique HVAC de base dans le domaine IoT.

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://hvac-model.json

hvac-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}

Exécutez l'opération CreateDigitalTwinModel pour créer le modèle de jumeau numérique HVAC de base dans le domaine IoT.
Utilisez la même charge utile DTDL que celle indiquée dans hvac-model.json lorsque vous appelez l'API.

Etape 3 : Création de l'adaptateur jumeau numérique HVAC de base

Créez un adaptateur jumeau numérique qui référence la version du modèle jumeau numérique HVAC de base et mappe la charge utile de l'appareil aux champs de télémétrie du modèle jumeau numérique.

Utilisez la console pour créer l'adaptateur jumeau numérique HVAC de base et charger ou coller l'enveloppe entrante et acheminer le fichier JSON.
1. Sur la page de liste Domaines IoT, ouvrez le domaine IoT avec lequel vous voulez travailler.
2. Sélectionnez l'onglet Adaptateurs de jumeaux numériques, puis Créer.
3. Entrez un nom et une description facultative pour l'adaptateur jumeau numérique HVAC de base.
4. Sélectionnez le modèle de jumeau numérique HVAC de base avec le DTMI dtmi:com:oracle:example:hvac;1.
5. Activez Spécifier l'enveloppe et les routages entrants, puis chargez ou collez hvac-envelope.json et hvac-routes.json.
6. Choisissez Créer.
hvac-envelope.json
{ "referenceEndpoint": "/telemetry", "referencePayload": { "dataFormat": "JSON", "data": { "time": 1773768299143534, "temp": 0, "hum": 0 } }, "envelopeMapping": { "timeObserved": "$.time" } }
hvac-routes.json
[ { "condition": "*", "payloadMapping": { "$.temperature": "$.temp", "$.humidity": "$.hum" } } ]

Utilisez la commande oci iot digital-twin-adapter create pour créer l'adaptateur jumeau numérique HVAC de base.

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1" \
  --inbound-envelope file://hvac-envelope.json \
  --inbound-routes file://hvac-routes.json

hvac-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temp": 0,
      "hum": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}

hvac-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temp",
      "$.humidity": "$.hum"
    }
  }
]

Exécutez l'opération CreateDigitalTwinAdapter pour créer l'adaptateur de jumeau numérique HVAC de base dans le domaine IoT.
Utilisez les mêmes charges utiles d'enveloppe entrante et d'acheminement entrant que celles indiquées dans les fichiers téléchargeables.

Etape 4 : création de l'instance de jumeau numérique

Créez une instance de jumeau numérique qui utilise l'adaptateur de jumeau numérique HVAC de base. La clé externe est le nom d'utilisateur que l'appareil utilise lorsqu'il se connecte.

Utilisez la console pour créer l'instance de jumeau numérique pour le périphérique HVAC.
1. Sur la page de liste Domaines IoT, ouvrez le domaine IoT avec lequel vous voulez travailler.
2. Sélectionnez l'onglet Instances de jumeaux numériques, puis sélectionnez Créer.
3. Entrez le nom d'affichage LG HVAC 1.
4. Sélectionnez l'adaptateur jumeau numérique HVAC de base créé à l'Step 3.
5. Sélectionnez l'ID d'authentification ou collez l'OCID de certificat ou de clé secrète.
6. Entrez hvac1 comme clé externe.
7. Choisissez Créer.

Utilisez la commande oci iot digital-twin-instance create pour créer l'instance de jumeau numérique.

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --display-name "LG HVAC 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <base-digital-twin-adapter-OCID> \
  --external-key hvac1

Exécutez l'opération CreateDigitalTwinInstance pour créer l'instance de jumeau numérique.
Utilisez l'OCID de l'adaptateur jumeau numérique HVAC de base et l'ID d'authentification pour les informations d'identification de l'appareil.

Etape 5 : envoi de télémétrie à l'instance de jumeau numérique de base

Envoyez une charge utile correspondant au mapping d'adaptateur de jumeau numérique de base, puis obtenez le contenu de l'instance de jumeau numérique pour vérifier la télémétrie normalisée.

Utilisez MQTTX pour envoyer des télémesures sur MQTTS.

mqttx pub \
  -t "data" \
  -m '{
    "temp": 70,
    "hum": 60
  }' \
  -u hvac1 \
  -P '<secret-contents>'

Utilisez curl pour envoyer la télémétrie via HTTPS. Cet exemple utilise l'authentification de base HTTP avec la clé externe de l'instance de jumeau numérique et le contenu de la clé secrète en texte brut.

curl -i -u "hvac1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
    "temp": 70,
    "hum": 60
  }'

Obtenez le contenu de l'instance de jumeau numérique pour vérifier les dernières valeurs normalisées.

Dans l'onglet Instances de jumeaux numériques, ouvrez la page de détails de l'instance de jumeaux numériques pour LG HVAC 1 et vérifiez les dernières valeurs de contenu.
Utilisez la commande oci iot digital-twin-instance get-content pour obtenir du contenu à partir de l'instance de jumeau numérique.
```
oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>
```
Exécutez l'opération GetDigitalTwinInstanceContent pour obtenir du contenu à partir de l'instance de jumeau numérique.

Étape 6 : Créer une version de modèle de jumeau numérique compatible HVAC mineur

Créez une version de modèle de jumeau numérique mineur compatible qui extends le modèle de jumeau numérique HVAC de base et ajoute la télémétrie pour la consommation d'énergie. La version majeure reste 1 et la version mineure passe à 1.1.

Utilisez la console pour créer la version de modèle de jumeau numérique HVAC mineur compatible dans le domaine IoT.
1. Sur la page de liste Domaines IoT, ouvrez le domaine IoT avec lequel vous voulez travailler.
2. Sélectionnez l'onglet Modèles de jumeaux numériques, puis sélectionnez Créer.
3. Téléchargez ou collez le fichier JSON DTDL à partir de hvac-e-model.json.
4. Choisissez Créer.
hvac-e-model.json
{ "@context": [ "dtmi:dtdl:context;3" ], "@id": "dtmi:com:oracle:example:hvac;1.1", "@type": "Interface", "extends": "dtmi:com:oracle:example:hvac;1", "displayName": "HVACe", "description": "A digital twin model for HVACe", "contents": [ { "@type": "Telemetry", "name": "energyConsumption", "schema": "integer" } ] }

Utilisez la commande oci iot digital-twin-model create pour créer la version de modèle de jumeau numérique HVAC mineur compatible.

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://hvac-e-model.json

hvac-e-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1.1",
  "@type": "Interface",
  "@extends": "dtmi:com:oracle:example:hvac;1",
  "displayName": "HVACe",
  "description": "A digital twin model for HVACe",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "energyConsumption",
      "schema": "integer"
    }
  ]
}

Exécutez l'opération CreateDigitalTwinModel pour créer la version de modèle de jumeau numérique HVAC mineur compatible dans le domaine IoT.
Utilisez la même charge utile DTDL que celle indiquée dans hvac-e-model.json lorsque vous appelez l'API.

Étape 7 : Créer un adaptateur de jumeau numérique pour la nouvelle version de modèle de jumeau numérique

Créez un nouvel adaptateur jumeau numérique qui référence la version de modèle de jumeau numérique HVAC mineur compatible et mappe le champ de télémétrie supplémentaire.

Utilisez la console pour créer l'adaptateur jumeau numérique HVAC mis à niveau et charger ou coller l'enveloppe entrante et acheminer le fichier JSON.
1. Sur la page de liste Domaines IoT, ouvrez le domaine IoT avec lequel vous voulez travailler.
2. Sélectionnez l'onglet Adaptateurs de jumeaux numériques, puis Créer.
3. Entrez un nom et une description facultative pour l'adaptateur jumeau numérique HVAC mis à niveau.
4. Sélectionnez la version du modèle de jumeau numérique HVAC avec le DTMI dtmi:com:oracle:example:hvac;1.1.
5. Activez Spécifier l'enveloppe et les routages entrants, puis chargez ou collez hvac-e-envelope.json et hvac-e-routes.json.
6. Choisissez Créer.
hvac-e-envelope.json
{ "referenceEndpoint": "/telemetry", "referencePayload": { "dataFormat": "JSON", "data": { "time": 1773768299143534, "temp": 0, "hum": 0, "ec": 0 } }, "envelopeMapping": { "timeObserved": "$.time" } }
hvac-e-routes.json
[ { "condition": "*", "payloadMapping": { "$.temperature": "$.temp", "$.humidity": "$.hum", "$.energyConsumption": "$.ec" } } ]

Utilisez la commande oci iot digital-twin-adapter create pour créer l'adaptateur jumeau numérique HVAC mis à niveau.

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1.1" \
  --inbound-envelope file://hvac-e-envelope.json \
  --inbound-routes file://hvac-e-routes.json

hvac-e-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temp": 0,
      "hum": 0,
      "ec": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}

hvac-e-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temp",
      "$.humidity": "$.hum",
      "$.energyConsumption": "$.ec"
    }
  }
]

Exécutez l'opération CreateDigitalTwinAdapter pour créer l'adaptateur de jumeau numérique HVAC mis à niveau dans le domaine IoT.
Utilisez les mêmes charges utiles d'enveloppe entrante et d'acheminement entrant que celles indiquées dans les fichiers téléchargeables.

Etape 8 : Mise à jour de l'instance de jumeau numérique pour utiliser le nouvel adaptateur de jumeau numérique

Mettez à jour l'instance de jumeau numérique existante pour référencer l'adaptateur de jumeau numérique pour la version de modèle de jumeau numérique mineur compatible. L'instance de jumeau numérique conserve la même identité, la même clé externe et la même continuité des données tout en acceptant les charges utiles pour le nouveau contrat de modèle de jumeau numérique.

Remarque

Utilisez une nouvelle instance de jumeau numérique au lieu de mettre à jour l'instance de jumeau numérique existante lorsque le modèle de jumeau numérique de remplacement utilise une nouvelle version majeure, supprime les éléments existants, renomme les champs, réduit les contraintes ou modifie le contrat de modèle de jumeau numérique de manière non additive.

Utilisez la console pour mettre à jour l'instance de jumeau numérique existante afin d'utiliser l'adaptateur de jumeau numérique CVC mis à niveau.
1. Sur la page de liste Domaines IoT, ouvrez le domaine IoT avec lequel vous voulez travailler.
2. Sélectionnez l'onglet Instances de jumeaux numériques.
3. Ouvrez la page de détails de l'instance de jumeau numérique pour LG HVAC 1.
4. Sélectionnez Modifier.
5. Remplacez l'adaptateur de jumeau numérique par l'adaptateur de jumeau numérique HVAC mis à niveau créé à l'Step 7.
6. Enregistrez les modifications.

Utilisez la commande oci iot digital-twin-instance update pour mettre à jour l'instance de jumeau numérique.

oci iot digital-twin-instance update \
  --digital-twin-instance-id <lg-hvac-1-OCID> \
  --digital-twin-adapter-id <upgraded-digital-twin-adapter-OCID>

Exécutez l'opération UpdateDigitalTwinInstance pour mettre à jour l'instance de jumeau numérique.
Définissez l'ID du jumeau numérique sur l'OCID de l'adaptateur jumeau numérique HVAC mis à niveau.

Etape 9 : validation de la télémétrie d'instance de jumeau numérique après la mise à niveau

Envoyez une charge utile qui inclut le nouveau champ de télémétrie et vérifiez que le contenu de l'instance de jumeau numérique inclut les valeurs mappées par l'adaptateur de jumeau numérique mis à niveau.

Si la validation échoue, comparez le modèle de jumeau numérique DTMI, l'adaptateur de jumeau numérique --digital-twin-model-spec-uri, le mappage d'enveloppes et le mappage de charge utile de routage. L'adaptateur jumeau numérique mis à niveau doit référencer la version du modèle jumeau numérique mineur compatible et mapper les champs de charge utile aux noms définis par ce modèle jumeau numérique.

Utilisez MQTTX pour envoyer des télémesures sur MQTTS.

mqttx pub \
  -t "data" \
  -m '{
    "temp": 70,
    "hum": 60,
    "ec": 38
  }' \
  -u hvac1 \
  -P '<secret-contents>'

curl -i -u "hvac1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
    "temp": 70,
    "hum": 60,
    "ec": 38
  }'

Etape facultative : obtention du contenu

Obtenez le contenu de l'instance de jumeau numérique pour vérifier les dernières valeurs normalisées.

Dans l'onglet Instances de jumeaux numériques, ouvrez la page de détails de l'instance de jumeaux numériques pour LG HVAC 1 et vérifiez les dernières valeurs de contenu.
Utilisez la commande oci iot digital-twin-instance get-content pour obtenir du contenu à partir de l'instance de jumeau numérique.
```
oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>
```
Exécutez l'opération GetDigitalTwinInstanceContent pour obtenir du contenu à partir de l'instance de jumeau numérique.

FAQ

Cette FAQ décrit les mises à niveau de modèles de jumeaux numériques compatibles et les formes de charge utile additive.

Qu'est-ce qu'une forme de charge utile additive ?: Une forme de charge utile additive conserve les champs de charge utile existants et ajoute de nouveaux champs sans modifier les noms de champ, les types de données, la signification, les unités ou les contraintes existants. Dans ce scénario, la charge utile de base { "temp": 70, "hum": 60 } devient { "temp": 70, "hum": 60, "ec": 38 }. La charge utile est additive car temp et hum signifient toujours la même chose et l'appareil ajoute uniquement ec pour la consommation d'énergie.
Comment une forme de charge utile additive est-elle liée à la version du modèle jumeau numérique ?: La charge utile de l'appareil et le modèle de jumeau numérique doivent évoluer ensemble. La nouvelle version du modèle de jumeau numérique ajoute energyConsumption tout en conservant la compatibilité des télémesures temperature et humidity existantes. L'adaptateur jumeau numérique mis à niveau met en correspondance le nouveau champ de charge utile ec avec le nouveau champ de modèle jumeau numérique energyConsumption.
Qu'est-ce qui n'est pas additif ?: Une modification n'est pas additive si elle renomme un champ existant, supprime un champ existant, modifie un type de schéma, modifie des unités ou une signification, réduit les contraintes de validation, modifie les contrats de demande de commande ou de réponse ou passe à une autre version de modèle de jumeau numérique majeur. Par exemple, la modification de hum en humidityPct ou la modification de temp d'un entier en chaîne n'est pas additive.
Les anciens appareils peuvent-ils continuer à envoyer la charge utile d'origine ?: Oui, les anciens périphériques peuvent continuer à envoyer les champs d'origine si le mappage de jumeaux numériques mis à niveau les gère toujours. Le nouveau champ n'est renseigné que lorsque l'appareil mis à niveau l'envoie et que l'adaptateur jumeau numérique le mappe au nouveau champ de modèle jumeau numérique.

Dépannage

La demande de création de modèle de jumeau numérique est rejetée

La nouvelle version du modèle de jumeau numérique mineur peut avoir modifié un élément de contrat existant au lieu d'ajouter uniquement du nouveau contenu. Comparez l'ancien et le nouveau modèle numérique jumelé DTDL. Les contraintes de télémétrie, de propriétés, de commandes, de relations, de schémas et de validation existantes doivent rester compatibles.

La demande de mise à jour d'instance de jumeau numérique est rejetée

Le nouvel adaptateur jumeau numérique peut référencer une version de modèle jumeau numérique incompatible, une version majeure différente ou une version antérieure. Vérifiez que l'adaptateur jumeau numérique utilise la même version de modèle jumeau numérique ou la prochaine version mineure compatible, telle que dtmi:com:oracle:example:hvac;1.1.

La mise à niveau a réussi, mais le nouveau champ n'est pas stocké

L'instance de jumeau numérique peut toujours utiliser l'ancien adaptateur de jumeau numérique, ou le mappage de routage mis à niveau peut ne pas mapper le nouveau champ de charge utile. Vérifiez l'OCID de l'adaptateur de jumeau numérique de l'instance de jumeau numérique et vérifiez que hvac-e-routes.json met en correspondance $.energyConsumption et $.ec.

La télémétrie existante est manquante après la mise à niveau

Le mapping de jumeaux numériques mis à niveau a peut-être supprimé les mappings de charge utile existants ou modifié le chemin de charge utile. Conservez les mappings existants pour temperature et humidity, puis ajoutez le nouveau mapping pour energyConsumption.

Les anciens périphériques échouent après le déplacement de l'instance de jumeau numérique vers l'adaptateur jumeau numérique mis à niveau

L'adaptateur jumeau numérique mis à niveau peut nécessiter le nouveau champ ou ne plus prendre en charge la forme de charge utile d'origine. Rendre le mapping d'adaptateur jumeau numérique tolérant les charges utiles qui n'incluent pas le nouveau champ ou déplacer les périphériques dans des groupes plus petits après avoir validé la forme de charge utile de chaque périphérique.

Documentation Oracle Cloud Infrastructure