Modificare un modello di dispositivo

Un modello di dispositivo include un modello che descrive come un dispositivo interagisce con IoT Central. Questo modello definisce le funzionalità del dispositivo e come IoT Central interagisce con loro. I dispositivi possono inviare dati di telemetria e valori delle proprietà a IoT Central, IoT Central può inviare aggiornamenti e comandi delle proprietà a un dispositivo. IoT Central usa anche il modello per definire le interazioni con le funzionalità di IoT Central, ad esempio processi, regole ed esportazioni.

Le modifiche apportate al modello in un modello di dispositivo possono influire sull'intera applicazione, inclusi tutti i dispositivi connessi. Le modifiche apportate a una funzionalità usata da regole, esportazioni, gruppi di dispositivi o processi potrebbero comportare comportamenti imprevisti o non funzionano affatto. Ad esempio, se si rimuove una definizione di telemetria da un modello:

• IoT Central non è più in grado di interpretare tale valore. IoT Central mostra i dati del dispositivo che non possono interpretare come dati non modellati nella pagina Dati non elaborati del dispositivo.
• IoT Central non include più il valore in alcuna esportazione di dati.

Per evitare conseguenze impreviste dalla modifica di un modello di dispositivo, questo articolo include raccomandazioni basate sulla fase corrente del ciclo di vita dello sviluppo. In generale, più si è all'inizio del ciclo di vita dello sviluppo, maggiore è la tolleranza alle modifiche del modello di dispositivo.

Per altre informazioni sui modelli di dispositivo e su come crearne uno, vedere Che cosa sono i modelli di dispositivo? e Creare un modello di dispositivo nell'applicazione Azure IoT Central.

Per informazioni su come gestire i modelli di dispositivo usando l'API REST di IoT Central, vedere Come usare l'API REST di IoT Central per gestire i modelli di dispositivo.

Modificare un modello di dispositivo

Le modifiche aggiuntive, ad esempio l'aggiunta di una funzionalità o un'interfaccia a un modello, sono modifiche che non causano interruzioni. È possibile apportare modifiche aggiuntive a un modello in qualsiasi fase del ciclo di vita dello sviluppo.

Le modifiche di rilievo includono la rimozione di parti di un modello o la modifica di un nome di funzionalità o di un tipo di schema. Queste modifiche potrebbero far sì che alcune funzionalità dell'applicazione, come regole, esportazioni o dashboard, visualizzino messaggi di errore e smettano di funzionare.

Nelle prime fasi di sviluppo dei dispositivi, mentre si sta ancora progettando e testando il modello, esiste una maggiore tolleranza per apportare modifiche direttamente al modello di dispositivo. Prima di connettere i dispositivi di produzione a un modello di dispositivo, è possibile modificare direttamente il modello di dispositivo. IoT Central applica queste modifiche automaticamente ai dispositivi quando si pubblica il modello di dispositivo.

Dopo aver collegato i dispositivi di produzione a un modello di dispositivo, valutare l'impatto di eventuali modifiche prima di modificare un modello di dispositivo. Non è consigliabile apportare modifiche di rilievo a un modello di dispositivo nell'ambiente di produzione. Per apportare tali modifiche, creare una nuova versione del modello di dispositivo. Testare il nuovo modello di dispositivo e quindi eseguire la migrazione dei dispositivi di produzione al nuovo modello in un tempo di inattività pianificato.

Aggiornare un modello di dispositivo IoT Edge

Per un dispositivo IoT Edge, il modello raggruppa le funzionalità in base ai moduli che corrispondono ai moduli IoT Edge in esecuzione nel dispositivo. Il manifesto della distribuzione è un documento JSON separato che indica a un dispositivo IoT Edge quali moduli installare, come configurarli e quali proprietà ha il modulo. Se si modifica un manifesto della distribuzione, è possibile aggiornare il modello di dispositivo in modo da includere i moduli e le proprietà definiti nel manifesto:

1. Passare al nodo Moduli nel modello di dispositivo.
2. Nella pagina Riepilogo moduli selezionare Importa moduli dal manifesto.
3. Selezionare il manifesto di distribuzione appropriato e selezionare Importa.

Per altre informazioni, vedere Dispositivi IoT Edge e IoT Central.

Modificare e pubblicare azioni

Le azioni seguenti sono utili quando si modifica un modello di dispositivo:

• Salva. Quando si modifica parte del modello di dispositivo, salvare le modifiche crea una bozza in cui è possibile tornare. Queste modifiche non influiscono ancora sui dispositivi connessi. Tutti i dispositivi creati da questo modello non dispongono delle modifiche salvate fino alla pubblicazione.
• Pubblica. Quando si pubblica il modello di dispositivo, vengono applicati eventuali modifiche salvate alle istanze del dispositivo esistenti. Le istanze di dispositivo appena create usano sempre il modello pubblicato più recente.
• Versione di un modello. Quando si esegue la versione di un modello di dispositivo, viene creato un nuovo modello con tutte le modifiche salvate più recenti. Le modifiche apportate a una nuova versione non influiscono sulle istanze del dispositivo esistenti. Per ulteriori informazioni, vedere Versionare un modello di dispositivo.
• Versionare un'interfaccia. Quando si esegue la versione di un'interfaccia, viene creata una nuova interfaccia con tutte le funzionalità salvate più recenti. È possibile riutilizzare un'interfaccia in più posizioni all'interno di un modello. Questo riutilizzo è il motivo per cui una modifica apportata a un riferimento a un'interfaccia modifica tutte le posizioni nel modello che usano l'interfaccia . Quando si esegue la versione di un'interfaccia, questo comportamento cambia perché la nuova versione è ora un'interfaccia separata. Per altre informazioni, vedere Versione di un'interfaccia.
• Eseguire la migrazione di un dispositivo. Quando si esegue la migrazione di un dispositivo, l'istanza del dispositivo viene scambiata da un modello di dispositivo a un altro. La migrazione dei dispositivi può causare un breve periodo di elaborazione delle modifiche da parte di IoT Central. Per altre informazioni, vedere Eseguire la migrazione di un dispositivo tra versioni diverse.

Numeri di versione

Sia i modelli di dispositivo che le interfacce hanno numeri di versione. Numeri di versione diversi consentono ai modelli o alle interfacce di condividere un @id valore, fornendo al tempo stesso una cronologia degli aggiornamenti. I numeri di versione vengono incrementati solo se si sceglie di eseguire la versione del modello o dell'interfaccia oppure se si modifica deliberatamente il numero di versione. È consigliabile modificare un numero di versione quando si apporta una modifica importante a un modello o a un'interfaccia.

Il frammento di codice seguente mostra il modello di dispositivo per un dispositivo termostato. Il modello di dispositivo ha una singola interfaccia. È possibile visualizzare il numero di versione, 1, alla fine del@id campo.

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    // ...
  ]
}

Per visualizzare queste informazioni nell'interfaccia utente di IoT Central, selezionare Modifica identità nell'editor dei modelli di dispositivo:

Versionamento di un modello di dispositivo

Per eseguire la versione di un modello di dispositivo:

1. Passare alla pagina Modelli di dispositivo .
2. Seleziona il modello di dispositivo che si vuole versionare.
3. Selezionare Versione nella parte superiore della pagina e assegnare al modello un nuovo nome. IoT Central suggerisce un nuovo nome, che è possibile modificare.
4. Fare clic su Crea.

A questo punto è stato creato un nuovo modello con un'identità univoca che non è collegata ad alcun dispositivo esistente.

Versione di un'interfaccia

Per eseguire la versione di un'interfaccia:

1. Passare alla pagina Modelli di dispositivo .
2. Selezionare il modello di dispositivo disponibile in modalità bozza.
3. Selezionare l'interfaccia pubblicata da aggiornare e modificare.
4. Selezionare Versione nella parte superiore della pagina dell'interfaccia.
5. Fare clic su Crea.

Ora che è stata creata una nuova interfaccia con un'identità univoca non è sincronizzata con la versione precedente dell'interfaccia.

Eseguire la migrazione di un dispositivo tra versioni

È possibile creare più versioni del modello di dispositivo. Nel corso del tempo, si avranno più dispositivi connessi usando questi modelli di dispositivo. È possibile eseguire la migrazione dei dispositivi da una versione del modello di dispositivo a un'altra. I passaggi seguenti descrivono come eseguire la migrazione di un dispositivo:

1. Passare alla pagina Dispositivi .

2. Selezionare il dispositivo di cui è necessario eseguire la migrazione a un'altra versione.

3. Scegliere Esegui migrazione:

   

4. Selezionare il modello di dispositivo con la versione in cui si vuole eseguire la migrazione del dispositivo e selezionare Esegui migrazione.

Suggerimento

È possibile usare un processo per eseguire la migrazione di tutti i dispositivi in un gruppo di dispositivi a un nuovo modello di dispositivo contemporaneamente.