Usare i modelli Plug and Play IoT in una soluzione IoT
Questo articolo descrive come è possibile identificare l'ID modello di un dispositivo Plug and Play IoT in una soluzione IoT e recuperarne la definizione del modello.
Esistono due categorie generali di soluzione IoT:
Una soluzione appositamente creata funziona con un set noto di modelli per i dispositivi Plug and Play IoT che si connettono alla soluzione. Questi modelli vengono usati quando si sviluppa la soluzione.
Una soluzione basata su modello funziona con il modello di qualsiasi dispositivo Plug and Play IoT. La creazione di una soluzione basata su modello è più complessa, ma il vantaggio è che la soluzione funziona con tutti i dispositivi aggiunti in futuro. Una soluzione IoT basata su modello recupera un modello e la usa per determinare i dati di telemetria, le proprietà e i comandi implementati dal dispositivo.
Per usare i modelli Plug and Play IoT in una soluzione IoT:
Identifica l'ID modello del modello implementato dal dispositivo Plug and Play IoT, dal modulo o dal modulo IoT Edge connesso alla soluzione.
Usa l'ID modello per recuperare la definizione del modello del dispositivo connesso da un repository di modelli o da un archivio personalizzato.
Quando un dispositivo Plug and Play IoT si connette a Hub IoT, registra l'ID modello del modello implementato con l'hub IoT.
Hub IoT notifica alla soluzione l'ID del modello di dispositivo come parte del flusso di connessione del dispositivo.
Una soluzione è in grado ottenere l'ID modello del dispositivo Plug and Play IoT usando uno dei tre metodi seguenti:
La soluzione può usare l'API Ottieni dispositivo gemello per recuperare l'ID modello del dispositivo Plug and Play IoT.
Suggerimento
Per i moduli e i moduli IoT Edge, usare ModuleClient.getTwin.
Nel frammento di risposta del dispositivo gemello seguente, modelId
contiene l'ID modello di un dispositivo Plug and Play IoT:
{
"deviceId": "sample-device",
"etag": "AAAAAAAAAAc=",
"deviceEtag": "NTk0ODUyODgx",
"status": "enabled",
"statusUpdateTime": "0001-01-01T00:00:00Z",
"connectionState": "Disconnected",
"lastActivityTime": "2020-07-17T06:12:26.8402249Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"modelId": "dtmi:com:example:TemperatureController;1",
"version": 15,
"properties": {...}
}
}
La soluzione è in grado di usare l'APIOttieni dispositivo gemello per recuperare l'ID modello del modello implementato dal dispositivo Plug and Play IoT.
Nel frammento di risposta del gemello digitale seguente $metadata.$model
contiene l'ID modello di un dispositivo Plug and Play IoT:
{
"$dtId": "sample-device",
"$metadata": {
"$model": "dtmi:com:example:TemperatureController;1",
"serialNumber": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}
Una connessione al dispositivo genera una notifica degli eventi di modifica del gemello digitale. Una soluzione deve sottoscrivere questa notifica degli eventi. Per informazioni sull'abilitazione del routing per gli eventi di gemello digitale, vedere Usare il routing dei messaggi di Hub IoT per inviare messaggi da dispositivo a cloud a endpoint differenti.
La soluzione è in grado di usare l'evento illustrato nel frammento di codice seguente per informazioni sul dispositivo Plug and Play IoT che si connette e ottiene il relativo ID modello:
iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/22/2020 8:02:27 PM
iothub-message-source:digitalTwinChangeEvents
correlation-id:100f322dc2c5
content-type:application/json-patch+json
content-encoding:utf-8
[
{
"op": "replace",
"path": "/$metadata/$model",
"value": "dtmi:com:example:TemperatureController;1"
}
]
Una soluzione usa l'ID modello identificato in precedenza per recuperare la definizione del modello corrispondente.
Una soluzione è in grado di ottenere la definizione del modello usando una delle opzioni seguenti:
Le soluzioni sono in grado di recuperare i modelli DTDL dal repository dei modelli di dispositivi (DMR). Il DMR è un repository pubblico, ospitato da Microsoft, che contiene una raccolta di modelli DTDL curati. I modelli di dispositivi pubblici archiviati nel DMR sono disponibili per tutti gli utenti per l'uso e l'integrazione nelle applicazioni dall'endpoint pubblico https://devicemodels.azure.com.
Dopo aver identificato l'ID modello per una nuova connessione al dispositivo, seguire questa procedura:
Recuperare la definizione del modello usando l'ID modello dal repository dei modelli. Per altre informazioni, vedere Risolvere i modelli.
Usando la definizione del modello del dispositivo connesso, è possibile enumerare le funzionalità del dispositivo.
Usando le funzionalità enumerate del dispositivo, è possibile consentire agli utenti di interagire con il dispositivo.
Le convenzioni DMR includono altri artefatti per semplificare l'utilizzo di modelli ospitati. Queste funzionalità sono facoltative per repository personalizzati o privati.
- Index. Tutte le DTMI disponibili vengono esposte tramite un indice composto da una sequenza di file json, ad esempio: https://devicemodels.azure.com/index.page.2.json
- Esteso. Per ogni interfaccia è disponibile un file con tutte le dipendenze, ad esempio: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
- Metadata. Questo file espone gli attributi chiave di un repository e viene aggiornato periodicamente con lo snapshot dei modelli pubblicati più recente. Include funzionalità implementate da un repository, ad esempio se sono disponibili l'indice del modello o i file di modello espansi. È possibile accedere ai metadati DMR all'indirizzo https://devicemodels.azure.com/metadata.json
Per accedere a livello di codice ai modelli DTDL pubblici nel DMR, è possibile usare ModelsRepositoryClient
disponibile nel pacchetto NuGet Azure.IoT.ModelsRepository. Questo client è configurato per impostazione predefinita per eseguire una query sul DMR pubblica disponibile in devicemodels.azure.com ed è possibile configurarlo in qualsiasi repository personalizzato.
Il client accetta un DTMI
come input e restituisce un dizionario con tutte le interfacce necessarie:
using Azure.IoT.ModelsRepository;
var client = new ModelsRepositoryClient();
ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));
L'output previsto visualizza la DTMI
delle tre interfacce trovate nella catena di dipendenze:
dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1
È possibile configurare il ModelsRepositoryClient
per eseguire query su un DMR personalizzata disponibile tramite https---e per specificare la risoluzione delle dipendenze usando il flag ModelDependencyResolution
:
- Disabilitati. Restituisce solo l'interfaccia specificata, senza alcuna dipendenza.
- Abilitati. Restituisce tutte le interfacce nella catena di dipendenze
Suggerimento
I repository personalizzati potrebbero non esporre il file .expanded.json
. Quando questo file non è disponibile, il client eseguirà il fallback per elaborare ogni dipendenza in locale.
Il codice di esempio seguente illustra come inizializzare il ModelsRepositoryClient
usando un URL di base del repository personalizzato, in questo caso usando gli URL raw
dall'API GitHub senza usare il modulo expanded
poiché non è disponibile nell'endpoint raw
. Il AzureEventSourceListener
viene inizializzato per controllare la richiesta HTTP eseguita dal client:
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();
var client = new ModelsRepositoryClient(
new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));
ModelResult model = await client.GetModelAsync(
"dtmi:com:example:TemperatureController;1",
dependencyResolution: ModelDependencyResolution.Enabled);
model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));
Sono disponibili altri esempi nel repository GitHub di Azure SDK: Azure.Iot.ModelsRepository/samples.
Le soluzioni possono archiviare queste definizioni di modello in un file system locale, in un archivio file pubblico o usare un'implementazione personalizzata.
Dopo aver identificato l'ID modello per una nuova connessione al dispositivo, seguire questa procedura:
Recuperare la definizione del modello usando l'ID modello dall'archivio personalizzato.
Usando la definizione del modello del dispositivo connesso, è possibile enumerare le funzionalità del dispositivo.
Usando le funzionalità enumerate del dispositivo, è possibile consentire agli utenti di interagire con il dispositivo.
Ora che si è appreso come integrare i modelli Plug and Play IoT in una soluzione IoT, alcuni passaggi successivi suggeriti sono: