Scenario: aggiornamento di un'istanza Digital Twin a una versione compatibile del modello Digital Twin

Aggiorna un'istanza gemella digitale creando una versione secondaria compatibile del modello gemello digitale, creando un nuovo adattatore gemello digitale per tale versione del modello gemello digitale e quindi aggiornando l'istanza gemello digitale per utilizzare il nuovo adattatore gemello digitale senza eliminare l'istanza gemello digitale.

Utilizzare questo scenario quando un dispositivo sostitutivo o aggiornato invia una forma di payload aggiuntivo, ad esempio un nuovo valore di telemetria, e si desidera mantenere la continuità per l'istanza digital twin esistente. Il modello digital twin rimane il contratto per i dati normalizzati. L'adattatore digital twin mappa il payload del dispositivo in entrata al contratto.

OCI IoT supporta l'aggiornamento di un'istanza digital twin attiva a un altro adattatore digital twin quando il nuovo adattatore digital twin fa riferimento alla stessa versione del modello digital twin o a una versione secondaria superiore compatibile dello stesso modello digital twin. Questo scenario mostra come costruire su un modello gemello digitale HVAC di base e come creare una nuova versione del modello gemello digitale HVAC con un sensore aggiuntivo mantenendo intatto il precedente modello gemello digitale.

Le principali modifiche alla versione del modello gemello digitale non sono compatibili per questo flusso di aggiornamento. I downgrade non sono supportati.

HVAC sta per riscaldamento, ventilazione e condizionamento dell'aria, riferendosi ai diversi sistemi utilizzati negli edifici per regolare la temperatura interna, l'umidità e la qualità dell'aria complessiva.

Task

Esaminare le regole di controllo delle versioni dei modelli digital twin compatibili.
Crea il modello di gemello digitale HVAC di base.
Creare l'adattatore digital twin HVAC di base.
Creare l'istanza digital twin.
Invia telemetria all'istanza digital twin di base.
Creare una versione compatibile del modello di gemello digitale secondario.
Creare un adattatore digital twin per la nuova versione del modello digital twin.
Aggiornare l'istanza digital twin per utilizzare il nuovo adattatore digital twin.
Convalidare la telemetria dell'istanza digital twin dopo l'upgrade.
Consulta le domande frequenti.
Risolvere i problemi di aggiornamento dei modelli digital twin.

Procedure ottimali

Aggiunta di valori a un modello gemello digitale esistente: utilizzare i passi di questo scenario per creare una versione DTMI minore per le modifiche del modello gemello digitale additivo, ad esempio modificare la versione. numero da 1 a 1.1, mantiene la versione DTMI principale uguale quando si aggiorna un'istanza gemella digitale esistente a un nuovo adattatore gemello digitale, come supportato nella specifica DTDL v3:
Da dtmi:com:oracle:example:hvac;1 a dtmi:com:oracle:example:hvac;1.1
Creazione di nuovi valori nel modello di gemello digitale, quindi creazione di una nuova istanza di gemello digitale: utilizzare una nuova versione DTMI principale quando è necessario creare un modello di gemello digitale con valori diversi. Per questo tipo di aggiornamento, è necessario creare una nuova istanza di gemello digitale con una modifica della versione principale del nuovo modello di gemello digitale, ad esempio:
Da dtmi:com:oracle:example:hvac;1 a dtmi:com:oracle:example:hvac;2
Ereditarietà consigliata: per gli aggiornamenti minori, l'aggiunta di nuovi valori, si consiglia di utilizzare l'ereditarietà per le modifiche dei modelli gemelli digitali additivi, ad esempio un modello gemello digitale che estende la versione precedente del modello gemello digitale. Invece di ridefinire gli attributi di base come @id, la posizione o lo stato di base per ogni nuova versione del modello digital twin, il nuovo modello digital twin eredita automaticamente i valori, riducendo gli errori e risparmiando tempo di sviluppo.
Mantenere compatibile la telemetria, le proprietà, i comandi, le relazioni e gli schemi esistenti. Non rinominare, rimuovere, limitare o modificare gli elementi del contratto esistenti durante un aggiornamento secondario.
Creare un nuovo adattatore digital twin per la nuova versione del modello digital twin e mantenere disponibile il precedente adattatore digital twin per il rollback fino alla convalida dei dispositivi aggiornati.
Test dei payload con telemetria rappresentativa prima di un rollout di produzione.

Informazioni sui file in questo scenario

hvac-model.json: Modello gemello digitale DTDL di base per la telemetria di temperatura e umidità.
hvac-envelope.json: busta dell'adattatore digital twin di base che estrae timeObserved.
hvac-routes.json: mappatura del percorso dell'adattatore gemello digitale di base per temperatura e umidità.
hvac-e-model.json: versione del modello gemello digitale DTDL minore compatibile che aggiunge la telemetria del consumo energetico.
hvac-e-envelope.json: busta dell'adattatore digital twin aggiornata che accetta il campo di telemetria aggiuntivo.
hvac-e-routes.json: mappatura del percorso dell'adattatore gemello digitale aggiornato per temperatura, umidità e consumo energetico.

Passo 1: rivedere le regole di controllo delle versioni del modello Digital Twin compatibili

Quando crei un modello di gemello digitale, OCI IoT controlla se esiste già un modello di gemello digitale attivo per la stessa versione principale.

Se ne esiste uno, un nuovo modello gemello digitale di versione secondaria deve essere strettamente additivo con un numero di versione e valori compatibili. Quando si aggiorna un'istanza digital twin per utilizzare un altro adattatore digital twin, l'adattatore deve fare riferimento alla stessa versione del modello digital twin o a una versione secondaria superiore compatibile.

I seguenti controlli di compatibilità si applicano tra la vecchia versione del modello digital twin e la nuova versione del modello digital twin:

Quando si crea un'interfaccia gemella digitale aggiornata e una versione del modello, la nuova versione secondaria deve essere esattamente la versione secondaria precedente più .1, ad esempio:

Da dtmi:com:oracle:example:hvac;1 a dtmi:com:oracle:example:hvac;1.1

Tutti i valori dell'interfaccia @id, inclusi schema e percorso, devono corrispondere, la nuova versione secondaria le uniche cose che possono essere nuove sono il numero di versione con incrementi minori e qualsiasi valore aggiuntivo aggiunto al modello esistente. Gli aggiornamenti sono compatibili solo quando la versione principale rimane costante e rimane invariata.

Elemento DTDL	Regola compatibilità	Nota
`Interface`	I valori `extends` esistenti devono rimanere invariati. Sono consentite ulteriori proroghe. Tutti i contenuti del modello esistenti devono rimanere con lo stesso nome. Sono consentiti nuovi contenuti. Le raccolte di schemi devono avere le stesse dimensioni e gli stessi percorsi ID schema.	L'aggiunta di schemi di interfaccia riutilizzabili non è supportata e rifiutata.
`Telemetry`	La telemetria esistente deve mantenere lo stesso nome, la classe DTDL, i tipi semantici o aggiuntivi, il percorso `@id`, l'unità, lo schema e i vincoli di convalida.	`comment`, `displayName` e `description` non vengono confrontati.
`Property`	Le proprietà esistenti devono mantenere gli stessi vincoli di regole di contenuto, impostazione scrivibile, schema, unità e convalida.	Si applica alle proprietà dell'interfaccia e alle proprietà della relazione.
`Command`	I comandi esistenti devono rimanere. La presenza di richieste e risposte, i nomi, gli schemi e i vincoli di convalida devono corrispondere.	L'aggiunta, la rimozione o la modifica di una richiesta o di una risposta non è compatibile.
`Relationship`	Le relazioni esistenti devono mantenere la stessa impostazione scrivibile, la stessa destinazione, la molteplicità minima, la massima molteplicità e le proprietà delle relazioni esistenti.	Sono consentite nuove proprietà di relazione.
`Component`	Lo schema componente deve rimanere invariato.	L'interfaccia del componente di riferimento non viene confrontata in modo ricorsivo in questo controllo.
`Schema`	Il tipo di schema concreto deve rimanere invariato. Gli schemi `primitive`, `geospatial`, `array`, `enum`, `map`, `object` e `field` esistenti devono mantenere i tipi compatibili e i vincoli di convalida.	`Primitive-to-object`, `enum-to-map` e modifiche simili sono incompatibili.
`Enum`	I valori `enum` esistenti devono rimanere con lo stesso nome e valore letterale.	Sono consentiti nuovi valori `enum`.
`Object`	I campi esistenti devono rimanere. Ogni schema di campo esistente e vincolo di convalida devono corrispondere.	Sono consentiti nuovi campi `object`.
`Interface schemas`	Ogni vecchio schema riutilizzabile deve esistere nel nuovo modello digital twin dallo stesso schema e percorso DTMI e passare il relativo confronto specifico dello schema.	La rimozione o la modifica di uno schema riutilizzabile esistente non è compatibile. Sono consentiti nuovi schemi riutilizzabili quando supportati.

Passo 2: Creare il modello base HVAC Digital Twin

Crea il modello gemello digitale di base con telemetria di temperatura e umidità.

Utilizzare la console per creare il modello gemello digitale HVAC di base nel dominio IoT.

Nella pagina della lista Domini IoT aprire il dominio IoT con cui si desidera lavorare.
Selezionare la scheda Modelli gemelli digitali, quindi selezionare Crea.
Caricare o incollare il file JSON DTDL da hvac-model.json.
Selezionare Crea.

hvac-modello.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"
    }
  ]
}

Utilizzare il comando oci iot digital-twin-model create per creare il modello gemello digitale HVAC di base nel dominio IoT.

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

hvac-modello.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"
    }
  ]
}

Eseguire l'operazione CreateDigitalTwinModel per creare il modello gemello digitale HVAC di base nel dominio IoT.
Utilizzare lo stesso payload DTDL visualizzato in hvac-model.json quando si chiama l'API.

Passo 3: Creare l'adattatore base HVAC Digital Twin

Crea un adattatore digital twin che fa riferimento alla versione di base del modello digital twin HVAC e mappa il payload del dispositivo ai campi di telemetria del modello digital twin.

Utilizzare la console per creare l'adattatore digital twin HVAC di base e caricare o incollare l'envelope in entrata e instrada JSON.
1. Nella pagina della lista Domini IoT aprire il dominio IoT con cui si desidera lavorare.
2. Selezionare la scheda Adattatori gemelli digitali, quindi selezionare Crea.
3. Immettere un nome e una descrizione facoltativa per l'adattatore digitale HVAC di base.
4. Selezionare il modello di base HVAC digital twin con il DTMI dtmi:com:oracle:example:hvac;1.
5. Attivare Specifica buste e instradamenti in entrata, quindi caricare o incollare hvac-envelope.json e hvac-routes.json.
6. Selezionare Crea.
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" } } ]

Utilizzare il comando oci iot digital-twin-adapter create per creare l'adattatore digital twin HVAC di 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"
    }
  }
]

Eseguire l'operazione CreateDigitalTwinAdapter per creare l'adattatore gemello digitale HVAC di base nel dominio IoT.
Utilizzare gli stessi payload di instradamento in entrata e in entrata visualizzati nei file scaricabili.

Passo 4: Creare l'istanza Digital Twin

Crea un'istanza digital twin che utilizza l'adattatore digital twin HVAC di base. La chiave esterna è il nome utente utilizzato dal dispositivo quando si connette.

Utilizzare la console per creare l'istanza digital twin per il dispositivo HVAC.
1. Nella pagina della lista Domini IoT aprire il dominio IoT con cui si desidera lavorare.
2. Selezionare la scheda Istanze gemelle digitali, quindi selezionare Crea.
3. Immettere LG HVAC 1 come nome visualizzato.
4. Selezionare l'adattatore gemello digitale HVAC di base creato al Passo 3.
5. Selezionare l'ID di autenticazione o incollare l'OCID certificato o segreto.
6. Immettere hvac1 come chiave esterna.
7. Selezionare Crea.

Utilizzare il comando oci iot digital-twin-instance create per creare l'istanza digital twin.

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

Eseguire l'operazione CreateDigitalTwinInstance per creare l'istanza gemello digitale.
Utilizzare l'OCID dell'adattatore Digital Twin HVAC di base e l'ID di autenticazione per le credenziali del dispositivo.

Passo 5: Invia telemetria all'istanza gemella digitale di base

Inviare un payload corrispondente al mapping dell'adattatore digital twin di base, quindi ottenere il contenuto dell'istanza digital twin per verificare la telemetria normalizzata.

Utilizzare MQTTX per inviare telemetria tramite MQTTS.

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

Utilizzare curl per inviare la telemetria tramite HTTPS. In questo esempio viene utilizzata l'autenticazione di base HTTP con la chiave esterna dell'istanza gemella digitale e il contenuto del segreto di testo normale.
```
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
  }'
```

Ottieni il contenuto dell'istanza digital twin per verificare i valori normalizzati più recenti.

Nella scheda Istanze gemelle digitali aprire la pagina dei dettagli dell'istanza gemella digitale per LG HVAC 1 e rivedere i valori di contenuto più recenti.
Utilizzare il comando oci iot digital-twin-instance get-content per ottenere contenuti dall'istanza digital twin.
```
oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>
```
Eseguire l'operazione GetDigitalTwinInstanceContent per ottenere il contenuto dall'istanza digital twin.

Passaggio 6: creare una versione del modello gemello digitale HVAC minore compatibile

Crea una versione del modello gemello digitale minore compatibile che extends il modello gemello digitale HVAC di base e aggiunge la telemetria per il consumo energetico. La versione principale rimane 1 e la versione minore aumenta a 1.1.

Utilizzare la console per creare la versione del modello gemello digitale HVAC minore compatibile nel dominio IoT.

Nella pagina della lista Domini IoT aprire il dominio IoT con cui si desidera lavorare.
Selezionare la scheda Modelli gemelli digitali, quindi selezionare Crea.
Caricare o incollare il file JSON DTDL da hvac-e-model.json.
Selezionare Crea.

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

Utilizzare il comando oci iot digital-twin-model create per creare la versione del modello gemello digitale HVAC minore compatibile.

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

Eseguire l'operazione CreateDigitalTwinModel per creare la versione del modello gemello digitale HVAC secondario compatibile nel dominio IoT.
Utilizzare lo stesso payload DTDL visualizzato in hvac-e-model.json quando si chiama l'API.

Passaggio 7: creare un adattatore Digital Twin per la nuova versione del modello Digital Twin

Crea un nuovo adattatore gemello digitale che fa riferimento alla versione del modello gemello digitale HVAC minore compatibile e mappa il campo di telemetria aggiuntivo.

Utilizzare la console per creare l'adattatore digital twin HVAC aggiornato e caricare o incollare l'envelope in entrata e instrada JSON.
1. Nella pagina della lista Domini IoT aprire il dominio IoT con cui si desidera lavorare.
2. Selezionare la scheda Adattatori gemelli digitali, quindi selezionare Crea.
3. Immettere un nome e una descrizione facoltativa per l'adattatore gemello digitale HVAC aggiornato.
4. Selezionare la versione del modello gemello digitale HVAC con DTMI dtmi:com:oracle:example:hvac;1.1.
5. Attivare Specifica buste e instradamenti in entrata, quindi caricare o incollare hvac-e-envelope.json e hvac-e-routes.json.
6. Selezionare Crea.
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" } } ]

Utilizzare il comando oci iot digital-twin-adapter create per creare l'adattatore digital twin HVAC aggiornato.

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

Eseguire l'operazione CreateDigitalTwinAdapter per creare l'adattatore gemello digitale HVAC aggiornato nel dominio IoT.
Utilizzare gli stessi payload di instradamento in entrata e in entrata visualizzati nei file scaricabili.

Passo 8: aggiornare l'istanza Digital Twin per utilizzare il nuovo adattatore Digital Twin

Aggiornare l'istanza gemello digitale esistente per fare riferimento all'adattatore gemello digitale per la versione del modello gemello digitale secondario compatibile. L'istanza digital twin mantiene la stessa identità, la stessa chiave esterna e la stessa continuità dei dati, mentre inizia ad accettare i payload per il nuovo contratto del modello digital twin.

Nota

Utilizzare una nuova istanza gemella digitale invece di aggiornare l'istanza gemella digitale esistente quando il modello gemello digitale sostitutivo utilizza una nuova versione principale, rimuove gli elementi esistenti, rinomina i campi, limita i vincoli o altrimenti modifica il contratto del modello gemello digitale in modo non additivo.

Utilizzare la console per aggiornare l'istanza gemella digitale esistente per utilizzare l'adattatore gemello digitale HVAC aggiornato.
1. Nella pagina della lista Domini IoT aprire il dominio IoT con cui si desidera lavorare.
2. Selezionare la scheda Istanze gemelle digitali.
3. Aprire la pagina dei dettagli dell'istanza Digital Twin per LG HVAC 1.
4. Selezionare Modifica.
5. Modificare l'adattatore digital twin nell'adattatore digital twin HVAC aggiornato creato al Passo 7.
6. Salvare le modifiche.

Utilizzare il comando oci iot digital-twin-instance update per aggiornare l'istanza digital twin.

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

Eseguire l'operazione UpdateDigitalTwinInstance per aggiornare l'istanza digital twin.
Impostare l'ID dell'adattatore digital twin sull'OCID dell'adattatore digital twin HVAC aggiornato.

Passo 9: convalida della telemetria dell'istanza Digital Twin dopo l'aggiornamento

Invia un payload che include il nuovo campo di telemetria e verifica che il contenuto dell'istanza digital twin includa i valori mappati dall'adattatore digital twin aggiornato.

Se la convalida non riesce, confrontare il modello digital twin DTMI, l'adattatore digital twin --digital-twin-model-spec-uri, il mapping dell'envelope e il mapping del payload di instradamento. L'adattatore digital twin aggiornato deve fare riferimento alla versione del modello digital twin secondario compatibile e mappare i campi del payload ai nomi definiti da tale modello digital twin.

Utilizzare MQTTX per inviare telemetria tramite MQTTS.

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

Utilizzare curl per inviare la telemetria tramite HTTPS. In questo esempio viene utilizzata l'autenticazione di base HTTP con la chiave esterna dell'istanza gemella digitale e il contenuto del segreto di testo normale.

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

Passo facoltativo: Recupera contenuti

Ottieni il contenuto dell'istanza digital twin per verificare i valori normalizzati più recenti.

Nella scheda Istanze gemelle digitali aprire la pagina dei dettagli dell'istanza gemella digitale per LG HVAC 1 e rivedere i valori di contenuto più recenti.
Utilizzare il comando oci iot digital-twin-instance get-content per ottenere contenuti dall'istanza digital twin.
```
oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>
```
Eseguire l'operazione GetDigitalTwinInstanceContent per ottenere il contenuto dall'istanza digital twin.

Domande più frequenti

Queste domande frequenti descrivono gli aggiornamenti compatibili del modello digital twin e le forme di payload additivo.

Che cos'è una forma di payload additivo?: Una forma di payload additivo mantiene i campi di payload esistenti e aggiunge nuovi campi senza modificare i nomi dei campi, i tipi di dati, il significato, le unità o i vincoli esistenti. In questo scenario, il payload di base { "temp": 70, "hum": 60 } diventa { "temp": 70, "hum": 60, "ec": 38 }. Il payload è additivo perché temp e hum significano ancora la stessa cosa e il dispositivo aggiunge solo ec per il consumo energetico.
In che modo una forma di payload additivo si riferisce alla versione del modello digital twin?: Il payload del dispositivo e il modello digital twin devono evolversi insieme. La nuova versione del modello gemello digitale aggiunge energyConsumption mantenendo compatibile la telemetria temperature e humidity esistente. L'adattatore digital twin aggiornato mappa il nuovo campo payload ec al nuovo campo modello digital twin energyConsumption.
Che cosa non è additivo?: Una modifica non è additiva se rinomina un campo esistente, rimuove un campo esistente, modifica un tipo di schema, modifica le unità o il significato, limita i vincoli di convalida, modifica i contratti di richiesta di comando o di risposta o passa a una versione del modello gemello digitale principale diversa. Ad esempio, la modifica di hum in humidityPct o la modifica di temp da un numero intero a una stringa non è additiva.
I vecchi dispositivi possono continuare a inviare il payload originale?: Sì, i vecchi dispositivi possono continuare a inviare i campi originali se il mapping dell'adattatore gemello digitale aggiornato li gestisce ancora. Il nuovo campo viene popolato solo quando il dispositivo aggiornato lo invia e l'adattatore gemello digitale lo mappa al nuovo campo modello gemello digitale.

Risoluzione dei problemi

La richiesta di creazione del modello gemello digitale è stata rifiutata

La nuova versione del modello gemello digitale secondario potrebbe aver modificato un elemento contratto esistente invece di aggiungere solo nuovo contenuto. Confronta i vecchi e nuovi modelli di gemelli digitali DTDL. I vincoli esistenti di telemetria, proprietà, comandi, relazioni, schemi e convalida devono rimanere compatibili.

La richiesta di aggiornamento dell'istanza digital twin è stata rifiutata

Il nuovo adattatore gemello digitale potrebbe fare riferimento a una versione del modello gemello digitale incompatibile, a una versione principale diversa o a un downgrade. Verificare che l'adattatore digital twin utilizzi la stessa versione del modello digital twin o la successiva versione secondaria superiore compatibile, ad esempio dtmi:com:oracle:example:hvac;1.1.

Aggiornamento riuscito, ma il nuovo campo non viene memorizzato

L'istanza digital twin potrebbe comunque utilizzare il vecchio adattatore digital twin oppure il mapping di instradamento aggiornato potrebbe non mappare il nuovo campo payload. Verificare l'OCID dell'adattatore digital twin dell'istanza digital twin e controllare che hvac-e-routes.json esegua il mapping tra $.energyConsumption e $.ec.

La telemetria esistente risulta mancante dopo l'aggiornamento

Il mapping dell'adattatore digital twin aggiornato potrebbe aver eliminato i mapping del payload esistenti o modificato il percorso del payload. Conservare i mapping esistenti per temperature e humidity, quindi aggiungere il nuovo mapping per energyConsumption.

I vecchi dispositivi non riescono dopo che l'istanza digital twin si è spostata sull'adattatore digital twin aggiornato

L'adattatore digital twin aggiornato potrebbe richiedere il nuovo campo o non supportare più la forma di payload originale. Rendere tollerante il mapping dell'adattatore digital twin dei payload che non includono il nuovo campo o spostare i dispositivi in gruppi più piccoli dopo aver convalidato ogni forma di payload del dispositivo.

Documentazione dell'infrastruttura Oracle Cloud