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:

1. Identifica l'ID modello del modello implementato dal dispositivo Plug and Play IoT, dal modulo o dal modulo IoT Edge connesso alla soluzione.

2. Usa l'ID modello per recuperare la definizione del modello del dispositivo connesso da un repository di modelli o da un archivio personalizzato.

Identificare l'ID modello

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:

Ottenere l'API del dispositivo gemello

La soluzione può usare l'API Ottieni dispositivo gemello per recuperare l'ID modello del dispositivo Plug and Play IoT.

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": {...}
    }
}

Ottenere l'API del gemello digitale

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

Notifica degli eventi di modifica del gemello digitale

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

Recuperare un modello di dati

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:

Repository modelli

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:

1. Recuperare la definizione del modello usando l'ID modello dal repository dei modelli. Per altre informazioni, vedere Risolvere i modelli.

2. Usando la definizione del modello del dispositivo connesso, è possibile enumerare le funzionalità del dispositivo.

3. Usando le funzionalità enumerate del dispositivo, è possibile consentire agli utenti di interagire con il dispositivo.

Risolvere i modelli

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

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.

Archivio personalizzato

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:

1. Recuperare la definizione del modello usando l'ID modello dall'archivio personalizzato.

2. Usando la definizione del modello del dispositivo connesso, è possibile enumerare le funzionalità del dispositivo.

3. Usando le funzionalità enumerate del dispositivo, è possibile consentire agli utenti di interagire con il dispositivo.

Passaggi successivi

Ora che si è appreso come integrare i modelli Plug and Play IoT in una soluzione IoT, alcuni passaggi successivi suggeriti sono:

• Interagire con un dispositivo dalla soluzione
• API REST dei gemelli digitali IoT
• Azure IoT Explorer