Guida per sviluppatori del servizio Plug and Play IoT

Plug and Play IoT consente di creare dispositivi IoT che annunciano le proprie funzionalità alle applicazioni Azure IoT. Plug and Play IoT dispositivi non richiedono la configurazione manuale quando un cliente le connette alle applicazioni abilitate per Plug and Play IoT.

Plug and Play IoT consente di usare i dispositivi che hanno annunciato l'ID modello con l'hub IoT. Ad esempio, è possibile accedere direttamente alle proprietà e ai comandi di un dispositivo.

Se si usa IoT Central, è possibile usare l'interfaccia utente di IoT Central e l'API REST per interagire con i dispositivi Plug and Play IoT connessi all'applicazione.

SDK per servizi

Usare gli SDK del servizio Azure IoT nella soluzione per interagire con dispositivi e moduli. Ad esempio, è possibile usare gli SDK del servizio per leggere e aggiornare le proprietà dei dispositivi gemelli e richiamare i comandi. I linguaggi supportati includono C#, Java, Node.js e Python.

I componenti Azure Iot SDK per servizi contengono codice che facilita la compilazione di applicazioni che interagiscono direttamente con l'hub IoT per gestire dispositivi e sicurezza.

Piattaforma	Pacchetto	Repository del codice	Esempi	Riferimento
.NET	NuGet	GitHub	Esempi	Riferimento
Java	Maven	GitHub	Esempi	Riferimento
Node	npm	GitHub	Esempi	Riferimento
Python	pip	GitHub	Esempi	Riferimento

Gli SDK del servizio consentono di accedere alle informazioni sul dispositivo da un componente della soluzione, ad esempio un'applicazione desktop o Web. Gli SDK del servizio includono due spazi dei nomi e modelli a oggetti che è possibile usare per recuperare l'ID modello:

• Client del servizio hub Iot. Questo servizio espone l'ID modello come proprietà del dispositivo gemello.

• Client di Gemelli digitali. La nuova API di Gemelli digitali opera su costrutti DTDL (Digital Twins Definition Language), ad esempio componenti, proprietà e comandi. Le API di Gemelli digitali semplificano la creazione di soluzioni da parte dei generatori di soluzioni Plug and Play IoT.

Sono disponibili anche le risorse seguenti:

• Documentazione di riferimento di .NET SDK
• Esempi di client di servizio
• Esempi di Gemelli digitali

esempi di client del servizio hub IoT

Questa sezione illustra esempi C# che usano il client del servizio hub IoT e le classi RegistryManager e ServiceClient. Usare la classe RegistryManager per interagire con lo stato del dispositivo usando i dispositivi gemelli. È anche possibile usare la classe RegistryManager per eseguire query sulle registrazioni dei dispositivi nel hub IoT. Usare la classe ServiceClient per chiamare i comandi nel dispositivo. Il modello DTDL per il dispositivo definisce le proprietà e i comandi implementati dal dispositivo. Nei frammenti di codice la deviceTwinId variabile contiene l'ID dispositivo del dispositivo Plug and Play IoT registrato con l'hub IoT.

Ottenere il dispositivo gemello e l'ID modello

Per ottenere il dispositivo gemello e l'ID modello del dispositivo Plug and Play IoT connesso all'hub IoT:

RegistryManager registryManager = RegistryManager.CreateFromConnectionString(parameters.HubConnectionString);

Twin twin = await registryManager.GetTwinAsync(deviceTwinId);
Console.WriteLine($"Device twin: \n{JsonConvert.SerializeObject(twin, Formatting.Indented)}");
Console.WriteLine($"Model ID: {twin.ModelId}.");

Aggiornamento dispositivo gemello

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un dispositivo. L'esempio mostra come è necessario ottenere il gemello prima di ETag aggiornarlo. La proprietà è definita nel componente predefinito del dispositivo:

Twin twin = await registryManager.GetTwinAsync(deviceTwinId);

int desiredTargetTemperature = 60;

// Update the twin
var twinPatch = new Twin();
twinPatch.Properties.Desired["targetTemperature"] = desiredTargetTemperature;

Console.WriteLine($"Update the targetTemperature property to {desiredTargetTemperature}.");

await registryManager.UpdateTwinAsync(deviceTwinId, twinPatch, twin.ETag);

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un componente. L'esempio mostra come è necessario ottenere il gemello prima di ETag aggiornarlo. La proprietà è definita nel componente Thermostat1 :

Twin twin = await registryManager.GetTwinAsync(deviceTwinId);

int desiredTargetTemperature = 60;

var twinPatch = CreatePropertyPatch("targetTemperature", desiredTargetTemperature, "thermostat1");

await registryManager.UpdateTwinAsync(deviceTwinId, twinPatch, twin.ETag);

// ...

private static Twin CreatePropertyPatch(string propertyName, object propertyValue, string componentName)
{
    var twinPatch = new Twin();
    twinPatch.Properties.Desired[componentName] = new
    {
        __t = "c"
    };
    twinPatch.Properties.Desired[componentName][propertyName] = JsonConvert.SerializeObject(propertyValue);
    return twinPatch;
}

Per una proprietà in un componente, la patch della proprietà è simile all'esempio seguente:

{
"sampleComponentName":
  {
    "__t": "c",
    "samplePropertyName": 20
  }
}

Comando Chiama

Il frammento di codice seguente illustra come richiamare il getMaxMinReport comando definito in un componente predefinito:

ServiceClient serviceClient = ServiceClient.CreateFromConnectionString(parameters.HubConnectionString);

var commandInvocation = new CloudToDeviceMethod("getMaxMinReport") { ResponseTimeout = TimeSpan.FromSeconds(30) };

// Set command payload
DateTimeOffset since = DateTimeOffset.Now.Subtract(TimeSpan.FromMinutes(2));
string componentCommandPayload = JsonConvert.SerializeObject(since);
commandInvocation.SetPayloadJson(componentCommandPayload);

try
{
  CloudToDeviceMethodResult result = await serviceClient.InvokeDeviceMethodAsync(deviceTwinId, commandInvocation);

  Console.WriteLine($"Command getMaxMinReport was invoked." +
      $"\nDevice returned status: {result.Status}. \nReport: {result.GetPayloadAsJson()}");
}
catch (DeviceNotFoundException)
{
    Console.WriteLine($"Unable to execute command getMaxMinReport on {deviceTwinId}.";
}

Il frammento di codice seguente illustra come chiamare il getMaxMinReport comando in un componente. Il comando è definito nel componente Thermostat1 :

// Create command name to invoke for component. The command is formatted as <component name>*<command name>
string commandToInvoke = "thermostat1*getMaxMinReport";
var commandInvocation = new CloudToDeviceMethod(commandToInvoke) { ResponseTimeout = TimeSpan.FromSeconds(30) };

// Set command payload
DateTimeOffset since = DateTimeOffset.Now.Subtract(TimeSpan.FromMinutes(2));
string componentCommandPayload = JsonConvert.SerializeObject(since);
commandInvocation.SetPayloadJson(componentCommandPayload);

try
{
    CloudToDeviceMethodResult result = await serviceClient.InvokeDeviceMethodAsync(deviceTwinId, commandInvocation);
    Console.WriteLine($"Command getMaxMinReport was invoked on component thermostat1." +
        $"\nDevice returned status: {result.Status}. \nReport: {result.GetPayloadAsJson()}");
}
catch (DeviceNotFoundException)
{
    Console.WriteLine("Unable to execute command getMaxMinReport on component thermostat1.");
}

hub IoT esempi di gemelli digitali

Usare la classe DigitalTwinClient per interagire con lo stato del dispositivo usando gemelli digitali. Il modello DTDL per il dispositivo definisce le proprietà e i comandi implementati dal dispositivo.

Questa sezione illustra esempi C# che usano l'API Gemelli digitali. I frammenti di codice seguenti usano le classi seguenti per rappresentare il gemello digitale dei dispositivi termostato e controller di temperatura:

using Microsoft.Azure.Devices.Serialization;
using Newtonsoft.Json;
using System;

namespace Microsoft.Azure.Devices.Samples
{
  internal class ThermostatTwin : BasicDigitalTwin
  {
    [JsonProperty("$metadata")]
    public new ThermostatMetadata Metadata { get; set; }

    [JsonProperty("maxTempSinceLastReboot")]
    public double? MaxTempSinceLastReboot { get; set; }

    [JsonProperty("targetTemperature")]
    public double? TargetTemperature { get; set; }
  }

  internal class ThermostatMetadata : DigitalTwinMetadata
  {
    [JsonProperty("maxTempSinceLastReboot")]
    public ReportedPropertyMetadata MaxTempSinceLastReboot { get; set; }

    [JsonProperty("targetTemperature")]
    public WritableProperty TargetTemperature { get; set; }
  }

  internal class ReportedPropertyMetadata
  {
    [JsonProperty("lastUpdateTime")]
    public DateTimeOffset LastUpdateTime { get; set; }
  }

  internal class TemperatureControllerTwin : BasicDigitalTwin
  {
    [JsonProperty("$metadata")]
    public new TemperatureControllerMetadata Metadata { get; set; }

    [JsonProperty("serialNumber")]
    public string SerialNumber { get; set; }

    [JsonProperty("thermostat1")]
    public ThermostatTwin Thermostat1 { get; set; }

    [JsonProperty("thermostat2")]
    public ThermostatTwin Thermostat2 { get; set; }
  }

  internal class TemperatureControllerMetadata : DigitalTwinMetadata
  {
    [JsonProperty("serialNumber")]
    public ReportedPropertyMetadata SerialNumber { get; set; }

    [JsonProperty("thermostat1")]
    public WritableProperty Thermostat1 { get; set; }

    [JsonProperty("thermostat2")]
    public WritableProperty Thermostat2 { get; set; }
  }
}

La digitalTwinId variabile contiene l'ID dispositivo del dispositivo Plug and Play IoT registrato con l'hub IoT.

Ottenere il gemello digitale e l'ID modello

Per ottenere il gemello digitale e l'ID modello del dispositivo Plug and Play IoT connesso all'hub IoT:

DigitalTwinClient digitalTwinClient = DigitalTwinClient.CreateFromConnectionString(parameters.HubConnectionString);
HttpOperationResponse<ThermostatTwin, DigitalTwinGetHeaders> getDigitalTwinResponse = await digitalTwinClient
    .GetDigitalTwinAsync<ThermostatTwin>(digitalTwinId);
ThermostatTwin thermostatTwin = getDigitalTwinResponse.Body;
Console.WriteLine($"Model ID: {thermostatTwin.Metadata.ModelId}.");
Console.WriteLine($"Digital Twin: \n{JsonConvert.SerializeObject(thermostatTwin, Formatting.Indented)}");

Aggiornare il gemello digitale

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un dispositivo. La proprietà è definita nel componente predefinito del dispositivo:

var updateOperation = new UpdateOperationsUtility();

int desiredTargetTemperature = 60;

// Get the current value of the targetTemperature property
HttpOperationResponse<ThermostatTwin, DigitalTwinGetHeaders> getDigitalTwinResponse = await digitalTwinClient
    .GetDigitalTwinAsync<ThermostatTwin>(digitalTwinId);
double? currentTargetTemperature = getDigitalTwinResponse.Body.TargetTemperature;

// Has the targetTemperature property previously been set?
if (currentTargetTemperature != null)
{
  // Update the existing property
  // Prepend the property path with a '/'
  updateOperation.AppendReplacePropertyOp($"/targetTemperature",   desiredTargetTemperature);
}
else
{
  // Add a new property
  // Prepend the property path with a '/'
  updateOperation.AppendAddPropertyOp($"/targetTemperature", desiredTargetTemperature);
}

// Update the targetTemperature property on the digital twin
HttpOperationHeaderResponse<DigitalTwinUpdateHeaders> updateDigitalTwinResponse = await digitalTwinClient
    .UpdateDigitalTwinAsync(digitalTwinId, updateOperation.Serialize());

Console.WriteLine($"Update {digitalTwinId} digital twin response: {updateDigitalTwinResponse.Response.StatusCode}.");

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un componente. La proprietà è definita nel componente Thermostat1 :

int desiredTargetTemperature = 60;

var updateOperation = new UpdateOperationsUtility();

// Look at when the property was updated and what was it set to.
HttpOperationResponse<TemperatureControllerTwin, DigitalTwinGetHeaders> getDigitalTwinResponse = await digitalTwinClient
  .GetDigitalTwinAsync<TemperatureControllerTwin>(digitalTwinId);

ThermostatTwin thermostat1 = getDigitalTwinResponse.Body.Thermostat1;

if (thermostat1 != null)
{
  // Thermostat1 is present in the TemperatureController twin. You can add/replace the component-level property "targetTemperature"
  double? currentComponentTargetTemperature = getDigitalTwinResponse.Body.Thermostat1.TargetTemperature;
  if (currentComponentTargetTemperature != null)
  {
      DateTimeOffset targetTemperatureDesiredLastUpdateTime = getDigitalTwinResponse.Body.Thermostat1.Metadata.TargetTemperature.LastUpdateTime;

      // The property path to be replaced should be prepended with a '/'
      updateOperation.AppendReplacePropertyOp("/thermostat1/targetTemperature", desiredTargetTemperature);
  }
  else
  {
      // The property path to be added should be prepended with a '/'
      updateOperation.AppendAddPropertyOp("/thermostat1/targetTemperature", desiredTargetTemperature);
  }
}
else
{
    // Thermostat1 is not present in the TemperatureController twin. Add the component.
    var componentProperty = new Dictionary<string, object> { { "targetTemperature", desiredTargetTemperature }, { "$metadata", new object() } };

    // The property path to be replaced should be prepended with a '/'
    updateOperation.AppendAddComponentOp("/thermostat1", componentProperty);
}

HttpOperationHeaderResponse<DigitalTwinUpdateHeaders> updateDigitalTwinResponse = await digitalTwinClient
    .UpdateDigitalTwinAsync(digitalTwinId, updateOperation.Serialize());

Console.WriteLine($"Update {digitalTwinId} digital twin response: {updateDigitalTwinResponse.Response.StatusCode}.");

Comando Chiama

Il frammento di codice seguente illustra come richiamare il getMaxMinReport comando definito in un componente predefinito:

DateTimeOffset since = DateTimeOffset.Now.Subtract(TimeSpan.FromMinutes(2));

try
{
  HttpOperationResponse<DigitalTwinCommandResponse, DigitalTwinInvokeCommandHeaders> invokeCommandResponse = await digitalTwinClient
    .InvokeCommandAsync(digitalTwinId, "getMaxMinReport", JsonConvert.SerializeObject(since));

  Console.WriteLine($"Command getMaxMinReport was invoked. \nDevice returned status: {invokeCommandResponse.Body.Status}." +
    $"\nReport: {invokeCommandResponse.Body.Payload}");
}
catch (HttpOperationException e)
{
  if (e.Response.StatusCode == HttpStatusCode.NotFound)
  {
    Console.WriteLine($"Unable to execute command getMaxMinReport on {digitalTwinId}.");
  }
}

Il frammento di codice seguente illustra come chiamare il getMaxMinReport comando in un componente. Il comando è definito nel componente Thermostat1 :

DateTimeOffset since = DateTimeOffset.Now.Subtract(TimeSpan.FromMinutes(2));

try
{
    HttpOperationResponse<DigitalTwinCommandResponse, DigitalTwinInvokeCommandHeaders> invokeCommandResponse = await digitalTwinClient
        .InvokeComponentCommandAsync(digitalTwinId, "thermostat1", "getMaxMinReport", JsonConvert.SerializeObject(since));

    Console.WriteLine("Command getMaxMinReport was invoked on component thermostat1." +
        $"\nDevice returned status: {invokeCommandResponse.Body.Status}. \nReport: {invokeCommandResponse.Body.Payload}");
}
catch (HttpOperationException e)
{
    if (e.Response.StatusCode == HttpStatusCode.NotFound)
    {
        Console.WriteLine("Unable to execute command getMaxMinReport on component thermostat1.");
    }
}

Leggere i dati di telemetria del dispositivo

Plug and Play IoT dispositivi inviano i dati di telemetria definiti nel modello DTDL a hub IoT. Per impostazione predefinita, hub IoT instrada i dati di telemetria a un endpoint di Hub eventi in cui è possibile usarli. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint diversi.

Il frammento di codice seguente illustra come leggere i dati di telemetria dall'endpoint predefinito di Hub eventi. Il codice in questo frammento viene tratto dalla guida introduttiva hub IoT Inviare dati di telemetria da un dispositivo a un hub IoT e leggerlo con un'applicazione back-end:

await using EventHubConsumerClient consumer = new EventHubConsumerClient(EventHubConsumerClient.DefaultConsumerGroupName, connectionString, EventHubName);

Console.WriteLine("Listening for messages on all partitions");

try
{
    await foreach (PartitionEvent partitionEvent in consumer.ReadEventsAsync(cancellationToken))
    {
        Console.WriteLine("Message received on partition {0}:", partitionEvent.Partition.PartitionId);

        string data = Encoding.UTF8.GetString(partitionEvent.Data.Body.ToArray());
        Console.WriteLine("\t{0}:", data);

        Console.WriteLine("Application properties (set by device):");
        foreach (var prop in partitionEvent.Data.Properties)
        {
            Console.WriteLine("\t{0}: {1}", prop.Key, prop.Value);
        }

        Console.WriteLine("System properties (set by IoT Hub):");
        foreach (var prop in partitionEvent.Data.SystemProperties)
        {
            Console.WriteLine("\t{0}: {1}", prop.Key, prop.Value);
        }
    }
}
catch (TaskCanceledException)
{
    // This is expected when the token is signaled; it should not be considered an
    // error in this scenario.
}

L'output seguente del codice precedente mostra i dati di telemetria relativi alla temperatura inviati dal termostato senza componenti Plug and Play IoT dispositivo che ha solo il componente predefinito. La dt-dataschema proprietà di sistema mostra l'ID modello:

Message received on partition 1:
        { "temperature": 25.5 }:
Application properties (set by device):
System properties (set by IoT Hub):
        iothub-connection-device-id: my-pnp-device
        iothub-connection-auth-method: {"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}
        iothub-connection-auth-generation-id: 637375045610235418
        iothub-enqueuedtime: 05/10/2020 14:30:58
        iothub-message-source: Telemetry
        dt-dataschema: dtmi:com:example:Thermostat;1
        content-type: application/json
        content-encoding: utf-8

L'output seguente del codice precedente mostra i dati di telemetria relativi alla temperatura inviati dal dispositivo TemperatureController a più componenti Plug and Play IoT. La dt-subject proprietà di sistema mostra il nome del componente che ha inviato i dati di telemetria. In questo esempio i due componenti sono thermostat1 e thermostat2 sono definiti nel modello DTDL. La dt-dataschema proprietà di sistema mostra l'ID modello:

Message received on partition 1:
        {"temperature":11.1}:
Application properties (set by device):
System properties (set by IoT Hub):
        dt-subject: thermostat1
        iothub-connection-device-id: my-pnp-device
        iothub-connection-auth-method: {"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}
        iothub-connection-auth-generation-id: 637375045610235418
        iothub-enqueuedtime: 05/10/2020 14:23:36
        iothub-message-source: Telemetry
        dt-dataschema: dtmi:com:example:TemperatureController;1
        content-type: application/json
        content-encoding: utf-8
Message received on partition 1:
        {"temperature":41.2}:
Application properties (set by device):
System properties (set by IoT Hub):
        dt-subject: thermostat2
        iothub-connection-device-id: my-pnp-device
        iothub-connection-auth-method: {"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}
        iothub-connection-auth-generation-id: 637375045610235418
        iothub-enqueuedtime: 05/10/2020 14:23:36
        iothub-message-source: Telemetry
        dt-dataschema: dtmi:com:example:TemperatureController;1
        content-type: application/json
        content-encoding: utf-8

Leggere le notifiche di modifica del dispositivo gemello

È possibile configurare hub IoT per generare notifiche di modifica del dispositivo gemello per indirizzare a un endpoint supportato. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint > diversi Eventi non di telemetria.

Il codice illustrato nel frammento di codice C# precedente genera l'output seguente quando hub IoT genera notifiche di modifica del dispositivo gemello per un dispositivo termostato senza componenti. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Message received on partition 1:
        {"version":3,"properties":{"reported":{"maxTempSinceLastReboot":9.6,"$metadata":{"$lastUpdated":"2020-10-06T10:17:41.7408552Z","maxTempSinceLastReboot":{"$lastUpdated":"2020-10-06T10:17:41.7408552Z"}},"$version":2}}}:
Application properties (set by device):
        hubName: my-pnp-hub
        deviceId: my-pnp-device
        operationTimestamp: 2020-10-06T10:17:41.7408552+00:00
        iothub-message-schema: twinChangeNotification
        opType: updateTwin
System properties (set by IoT Hub):
        iothub-connection-device-id: my-pnp-device
        iothub-enqueuedtime: 06/10/2020 10:17:41
        iothub-message-source: twinChangeEvents
        user-id: System.ArraySegment`1[System.Byte]
        correlation-id: 61394e8ba7d
        content-type: application/json
        content-encoding: utf-8

Il codice illustrato nel frammento di codice C# precedente genera l'output seguente quando hub IoT genera notifiche di modifica del dispositivo gemello per un dispositivo con componenti. Questo esempio mostra l'output quando un dispositivo sensore di temperatura con un componente termostato genera notifiche. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Message received on partition 1:
        {"version":5,"properties":{"reported":{"thermostat1":{"__t":"c","maxTempSinceLastReboot":9.6},"$metadata":{"$lastUpdated":"2020-10-06T10:27:59.515972Z","thermostat1":{"$lastUpdated":"2020-10-06T10:27:59.515972Z","__t":{"$lastUpdated":"2020-10-06T10:27:59.515972Z"},"maxTempSinceLastReboot":{"$lastUpdated":"2020-10-06T10:27:59.515972Z"}}},"$version":4}}}:
Application properties (set by device):
        hubName: my-pnp-hub
        deviceId: my-pnp-device
        operationTimestamp: 2020-10-06T10:27:59.5159720+00:00
        iothub-message-schema: twinChangeNotification
        opType: updateTwin
System properties (set by IoT Hub):
        iothub-connection-device-id: my-pnp-device
        iothub-enqueuedtime: 06/10/2020 10:27:59
        iothub-message-source: twinChangeEvents
        user-id: System.ArraySegment`1[System.Byte]
        correlation-id: 615051f364e
        content-type: application/json
        content-encoding: utf-8

Leggere le notifiche di modifica del gemello digitale

È possibile configurare hub IoT per generare notifiche di modifica del gemello digitale per indirizzare a un endpoint supportato. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint > diversi Eventi non di telemetria.

Il codice illustrato nel frammento di codice C# precedente genera l'output seguente quando hub IoT genera notifiche di modifica del gemello digitale per un dispositivo termostato senza componenti. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Message received on partition 1:
        [{"op":"add","path":"/$metadata/maxTempSinceLastReboot","value":{"lastUpdateTime":"2020-10-06T10:39:16.0209836Z"}},{"op":"add","path":"/maxTempSinceLastReboot","value":34.9}]:
Application properties (set by device):
        hubName: my-pnp-hub
        deviceId: my-pnp-device
        operationTimestamp: 2020-10-06T10:39:16.0209836+00:00
        iothub-message-schema: digitalTwinChangeNotification
        opType: updateTwin
System properties (set by IoT Hub):
        iothub-connection-device-id: my-pnp-device
        iothub-enqueuedtime: 06/10/2020 10:39:16
        iothub-message-source: digitalTwinChangeEvents
        user-id: System.ArraySegment`1[System.Byte]
        correlation-id: 6169857bf8c
        content-type: application/json-patch+json
        content-encoding: utf-8

Il codice illustrato nel frammento di codice C# precedente genera l'output seguente quando hub IoT genera notifiche di modifica del gemello digitale per un dispositivo con componenti. Questo esempio mostra l'output quando un dispositivo sensore di temperatura con un componente termostato genera notifiche. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Message received on partition 1:
        [{"op":"add","path":"/thermostat1","value":{"$metadata":{"maxTempSinceLastReboot":{"lastUpdateTime":"2020-10-06T10:41:44.8312666Z"}},"maxTempSinceLastReboot":29.1}}]:
Application properties (set by device):
        hubName: my-pnp-hub
        deviceId: my-pnp-device
        operationTimestamp: 2020-10-06T10:41:44.8312666+00:00
        iothub-message-schema: digitalTwinChangeNotification
        opType: updateTwin
System properties (set by IoT Hub):
        iothub-connection-device-id: my-pnp-device
        iothub-enqueuedtime: 06/10/2020 10:41:44
        iothub-message-source: digitalTwinChangeEvents
        user-id: System.ArraySegment`1[System.Byte]
        correlation-id: 616f108f0e3
        content-type: application/json-patch+json
        content-encoding: utf-8

Sono disponibili anche le risorse seguenti:

• Documentazione di riferimento di Java SDK
• Esempi di Gemelli digitali

esempi di client del servizio hub IoT

Questa sezione illustra esempi Java che usano il client del servizio hub IoT e le classi DeviceTwin e DeviceMethod dello spazio dei nomi com.microsoft.azure.sdk.iot.service.devicetwin. Usare la classe DeviceTwin per interagire con lo stato del dispositivo usando i dispositivi gemelli. È anche possibile usare la classe DeviceTwin per eseguire query sulle registrazioni dei dispositivi nel hub IoT. Usare la classe DeviceMethod per chiamare i comandi nel dispositivo. Il modello DTDL per il dispositivo definisce le proprietà e i comandi implementati dal dispositivo. Nei frammenti di codice la deviceId variabile contiene l'ID dispositivo del dispositivo Plug and Play IoT registrato con l'hub IoT.

Ottenere il dispositivo gemello e l'ID modello

Per ottenere il dispositivo gemello e l'ID modello del dispositivo Plug and Play IoT connesso all'hub IoT:

DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);

// ...

DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
twinClient.getTwin(twin);
System.out.println("Model Id of this Twin is: " + twin.getModelId());

Aggiornamento dispositivo gemello

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un dispositivo. È necessario ottenere il gemello prima di aggiornarlo. La proprietà è definita nel componente predefinito del dispositivo:

DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
twinClient.getTwin(twin);

double propertyValue = 60.2;
twin.setDesiredProperties(Collections.singleton(new Pair("targetTemperature", propertyValue)));
twinClient.updateTwin(twin);

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un componente. È necessario ottenere il gemello prima di aggiornarlo. La proprietà è definita nel componente thermostat1 :

public static Set<Pair> CreateComponentPropertyPatch(@NonNull String propertyName, @NonNull double propertyValue, @NonNull String componentName)
{
    JsonObject patchJson = new JsonObject();
    patchJson.addProperty("__t", "c");
    patchJson.addProperty(propertyName, propertyValue);
    return singleton(new Pair(componentName, patchJson));
}

// ...

DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
twinClient.getTwin(twin);

double propertyValue = 60.2;
twin.setDesiredProperties(CreateComponentPropertyPatch("targetTemperature", propertyValue, "thermostat1"));
twinClient.updateTwin(twin);

Per una proprietà in un componente, la patch della proprietà è simile all'esempio seguente:

{
  "thermostat1":
  {
    "__t": "c",
    "targetTemperature": 60.2
  }
}

Comando Chiama

Il frammento di codice seguente illustra come richiamare il getMaxMinReport comando definito in un componente predefinito:

DeviceMethod methodClient = DeviceMethod.createFromConnectionString(iotHubConnectionString);

Long responseTimeout = TimeUnit.SECONDS.toSeconds(200);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

String commandInput = ZonedDateTime.now(ZoneOffset.UTC).minusMinutes(5).format(DateTimeFormatter.ISO_DATE_TIME);
MethodResult result = methodClient.invoke(deviceId, "getMaxMinReport", responseTimeout, connectTimeout, commandInput);

System.out.println("Method result status is: " + result.getStatus());

Il frammento di codice seguente illustra come chiamare il getMaxMinReport comando in un componente. Il comando è definito nel componente thermostat1 :

DeviceMethod methodClient = DeviceMethod.createFromConnectionString(iotHubConnectionString);

Long responseTimeout = TimeUnit.SECONDS.toSeconds(200);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

String commandInput = ZonedDateTime.now(ZoneOffset.UTC).minusMinutes(5).format(DateTimeFormatter.ISO_DATE_TIME);
MethodResult result = methodClient.invoke(deviceId, "thermostat1*getMaxMinReport", responseTimeout, connectTimeout, commandInput);

System.out.println("Method result status is: " + result.getStatus());

hub IoT esempi di gemelli digitali

Usare la classe DigitalTwinAsyncClient nello spazio dei nomi com.microsoft.azure.sdk.iot.service.digitaltwin per interagire con lo stato del dispositivo usando gemelli digitali. Gli esempi seguenti usano anche le classi UpdateOperationUtility e BasicDigitalTwin dello stesso spazio dei nomi. Il modello DTDL per il dispositivo definisce le proprietà e i comandi implementati dal dispositivo.

La digitalTwinid variabile contiene l'ID dispositivo del dispositivo Plug and Play IoT registrato con l'hub IoT.

Ottenere il gemello digitale e l'ID modello

Per ottenere il gemello digitale e l'ID modello del dispositivo Plug and Play IoT connesso all'hub IoT:

DigitalTwinAsyncClient asyncClient = DigitalTwinAsyncClient.createFromConnectionString(iotHubConnectionString);

CountDownLatch latch = new CountDownLatch(1);
asyncClient.getDigitalTwin(digitalTwinid, BasicDigitalTwin.class)
    .subscribe(
        getResponse ->
        {
            System.out.println("Digital Twin Model Id: " + getResponse.getMetadata().getModelId());
            System.out.println("Digital Twin: " + prettyBasicDigitalTwin(getResponse));
            latch.countDown();
        },
        error ->
        {
            System.out.println("Get Digital Twin failed: " + error);
            latch.countDown();
        });

latch.await(10, TimeUnit.SECONDS);

// ...

private static String prettyBasicDigitalTwin(BasicDigitalTwin basicDigitalTwin)
{
    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    return gson.toJson(basicDigitalTwin);
}

Aggiornare il gemello digitale

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un dispositivo. La proprietà è definita nel componente predefinito del dispositivo:

DigitalTwinAsyncClient asyncClient = DigitalTwinAsyncClient.createFromConnectionString(iotHubConnectionString);

CountDownLatch latch1 = new CountDownLatch(1);

UpdateOperationUtility updateOperationUtility = new UpdateOperationUtility();

// Add a new property.
updateOperationUtility.appendAddPropertyOperation("/" + "targetTemperature", 35);
asyncClient.updateDigitalTwin(digitalTwinid, updateOperationUtility.getUpdateOperations())
    .subscribe(
        getResponse ->
        {
            System.out.println("Updated Digital Twin");
            latch1.countDown();
        },
        error ->
        {
            System.out.println("Update Digital Twin failed: " + error);
            latch1.countDown();
        });
latch1.await(10, TimeUnit.SECONDS);
GetDigitalTwin();

// Replace an existing property.
CountDownLatch latch2 = new CountDownLatch(1);
updateOperationUtility.appendReplacePropertyOperation("/targetTemperature", 50);
asyncClient.updateDigitalTwin(digitalTwinid, updateOperationUtility.getUpdateOperations())
    .subscribe(
        getResponse ->
        {
            System.out.println("Updated Digital Twin");
            latch2.countDown();
        },
        error ->
        {
            System.out.println("Update Digital Twin failed: " + error);
            latch2.countDown();
        });

latch2.await(10, TimeUnit.SECONDS);
GetDigitalTwin();

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un componente. La proprietà è definita nel componente thermostat1 :

DigitalTwinClient client = DigitalTwinClient.createFromConnectionString(iotHubConnectionString);

// Get digital twin.
ServiceResponseWithHeaders<String, DigitalTwinGetHeaders> getResponse = client.getDigitalTwinWithResponse(digitalTwinid, String.class);

// Construct the options for conditional update.
DigitalTwinUpdateRequestOptions options = new DigitalTwinUpdateRequestOptions();
options.setIfMatch(getResponse.headers().eTag());

UpdateOperationUtility updateOperationUtility = new UpdateOperationUtility();

Map<String, Object> t1properties = new HashMap<>();
t1properties.put("targetTemperature", 50);
updateOperationUtility.appendReplaceComponentOperation("/thermostat1", t1properties);

digitalTwinUpdateOperations = updateOperationUtility.getUpdateOperations();
updateResponse = client.updateDigitalTwinWithResponse(digitalTwinid, digitalTwinUpdateOperations, options);
System.out.println("Update Digital Twin response status: " + updateResponse.response().message());

getResponse = client.getDigitalTwinWithResponse(digitalTwinid, String.class);

Comando Chiama

Il frammento di codice seguente illustra come richiamare il getMaxMinReport comando definito in un componente predefinito:

CountDownLatch latch = new CountDownLatch(1);

String commandInput = ZonedDateTime.now(ZoneOffset.UTC).minusMinutes(5).format(DateTimeFormatter.ISO_DATE_TIME);

// Invoke a method on root level.
asyncClient.invokeCommand(digitalTwinid, "getMaxMinReport", commandInput)
    .subscribe(
        response ->
        {
            System.out.println("Invoked Command getMaxMinReport response: " + prettyString(response.getPayload()));
            latch.countDown();
        },
        error ->
        {
            RestException ex = (RestException)error;
            if(ex.response().code() == 404) {
                System.out.println("Invoked Command getMaxMinReport failed: " + error);
            }
            else {
                System.out.println("Ensure the device sample is running for this sample to succeed");
            }
            latch.countDown();
        });

latch.await(10, TimeUnit.SECONDS);

// ...

private static String prettyString(String str)
{
    Gson gson = new Gson();
    Gson gsonBuilder = new GsonBuilder().setPrettyPrinting().create();
    return gsonBuilder.toJson(gson.fromJson(str, Object.class));
}

Il frammento di codice seguente illustra come chiamare il getMaxMinReport comando in un componente. Il comando è definito nel componente thermostat1 :

DigitalTwinClient client = DigitalTwinClient.createFromConnectionString(iotHubConnectionString);

String commandInput = ZonedDateTime.now(ZoneOffset.UTC).minusMinutes(5).format(DateTimeFormatter.ISO_DATE_TIME);

DigitalTwinInvokeCommandRequestOptions options = new DigitalTwinInvokeCommandRequestOptions();
try {
    ServiceResponseWithHeaders<DigitalTwinCommandResponse, DigitalTwinInvokeCommandHeaders> commandResponse = client.invokeComponentCommandWithResponse(digitalTwinid, "thermostat1", "getMaxMinReport", commandInput, options);
    System.out.println("Command getMaxMinReport, payload: " + prettyString(commandResponse.body().getPayload()));
    System.out.println("Command getMaxMinReport, status: " + commandResponse.body().getStatus());
} catch (RestException ex)
{
    if(ex.response().code() == 404)
    {
        System.out.println("Ensure the device sample is running for this sample to succeed.");
    }
    else
    {
        throw ex;
    }
}

// ...

private static String prettyString(String str)
{
    Gson gson = new Gson();
    Gson gsonBuilder = new GsonBuilder().setPrettyPrinting().create();
    return gsonBuilder.toJson(gson.fromJson(str, Object.class));
}

Leggere i dati di telemetria del dispositivo

Plug and Play IoT dispositivi inviano i dati di telemetria definiti nel modello DTDL a hub IoT. Per impostazione predefinita, hub IoT instrada i dati di telemetria a un endpoint di Hub eventi in cui è possibile usarli. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint diversi.

Il frammento di codice seguente illustra come leggere i dati di telemetria dall'endpoint predefinito di Hub eventi. Il codice in questo frammento viene tratto dalla guida introduttiva hub IoT Inviare dati di telemetria da un dispositivo a un hub IoT e leggerlo con un'applicazione back-end:

import com.azure.messaging.eventhubs.EventHubClientBuilder;
import com.azure.messaging.eventhubs.EventHubConsumerAsyncClient;

// ...

EventHubClientBuilder eventHubClientBuilder = new EventHubClientBuilder()
    .consumerGroup(EventHubClientBuilder.DEFAULT_CONSUMER_GROUP_NAME)
    .connectionString(eventHubCompatibleConnectionString);

try (EventHubConsumerAsyncClient eventHubConsumerAsyncClient = eventHubClientBuilder.buildAsyncConsumerClient()) {

    receiveFromAllPartitions(eventHubConsumerAsyncClient);

}

// ...

private static void receiveFromAllPartitions(EventHubConsumerAsyncClient eventHubConsumerAsyncClient) {

eventHubConsumerAsyncClient
    .receive(false) // set this to false to read only the newly available events
    .subscribe(partitionEvent -> {
        System.out.println();
        System.out.printf("%nTelemetry received from partition %s:%n%s",
            partitionEvent.getPartitionContext().getPartitionId(), partitionEvent.getData().getBodyAsString());
        System.out.printf("%nApplication properties (set by device):%n%s", partitionEvent.getData().getProperties());
        System.out.printf("%nSystem properties (set by IoT Hub):%n%s",
            partitionEvent.getData().getSystemProperties());
    }, ex -> {
        System.out.println("Error receiving events " + ex);
    }, () -> {
        System.out.println("Completed receiving events");
    });
}

L'output seguente del codice precedente mostra i dati di telemetria relativi alla temperatura inviati dal termostato senza componenti Plug and Play IoT dispositivo che ha solo il componente predefinito. La dt-dataschema proprietà di sistema mostra l'ID modello:

Telemetry received from partition 1:
{"temperature": 10.700000}
Application properties (set by device):
{$.cdid=my-pnp-device}
System properties (set by IoT Hub):
{correlation-id=dd960185-6ddb-4b5f-89bb-e26b0b3c201e, content-encoding=UTF-8, iothub-connection-auth-method={"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}, iothub-enqueuedtime=Tue Oct 20 12:28:10 BST 2020, dt-dataschema=dtmi:com:example:Thermostat;1, absolute-expiry-time=0, iothub-connection-device-id=my-pnp-device, iothub-connection-auth-generation-id=637375776990653481, group-sequence=0, iothub-message-source=Telemetry, creation-time=0, message-id=1c05cece-070b-4e2e-b2e8-e263858594a3, content-type=application/json}

Telemetry received from partition 1:
{"temperature": 10.700000}
Application properties (set by device):
{$.cdid=my-pnp-device}
System properties (set by IoT Hub):
{correlation-id=d10a7350-43ef-4cf6-9db5-a4b08684cd9d, content-encoding=UTF-8, iothub-connection-auth-method={"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}, iothub-enqueuedtime=Tue Oct 20 12:28:15 BST 2020, dt-dataschema=dtmi:com:example:Thermostat;1, absolute-expiry-time=0, iothub-connection-device-id=my-pnp-device, iothub-connection-auth-generation-id=637375776990653481, group-sequence=0, iothub-message-source=Telemetry, creation-time=0, message-id=d3a80af4-1246-41a0-a09a-582a12c17a00, content-type=application/json}

L'output seguente del codice precedente mostra i dati di telemetria relativi alla temperatura inviati dal dispositivo TemperatureController a più componenti Plug and Play IoT. La dt-subject proprietà di sistema mostra il nome del componente che ha inviato i dati di telemetria. In questo esempio i due componenti sono thermostat1 e thermostat2 sono definiti nel modello DTDL. La dt-dataschema proprietà di sistema mostra l'ID modello:

Telemetry received from partition 1:
null
Application properties (set by device):
{$.cdid=my-pnp-device}
System properties (set by IoT Hub):
{correlation-id=413002d0-2107-4c08-8f4a-995ae1f4047b, content-encoding=UTF-8, iothub-connection-auth-method={"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}, iothub-enqueuedtime=Tue Oct 20 12:31:14 BST 2020, dt-dataschema=dtmi:com:example:TemperatureController;1, absolute-expiry-time=0, iothub-connection-device-id=my-pnp-device, iothub-connection-auth-generation-id=637387902591517456, group-sequence=0, iothub-message-source=Telemetry, creation-time=0, message-id=da8bd068-850e-43fb-862f-66080d5969e4, content-type=application/json, dt-subject=thermostat1}

Telemetry received from partition 1:
null
Application properties (set by device):
{$.cdid=my-pnp-device}
System properties (set by IoT Hub):
{correlation-id=2d9407e5-413f-4f8d-bd30-cd153e03c72f, content-encoding=UTF-8, iothub-connection-auth-method={"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}, iothub-enqueuedtime=Tue Oct 20 12:31:14 BST 2020, dt-dataschema=dtmi:com:example:TemperatureController;1, absolute-expiry-time=0, iothub-connection-device-id=my-pnp-device, iothub-connection-auth-generation-id=637387902591517456, group-sequence=0, iothub-message-source=Telemetry, creation-time=0, message-id=ed419c4e-ef2c-4acf-8991-6245059c5fdc, content-type=application/json, dt-subject=thermostat2}

Leggere le notifiche di modifica del dispositivo gemello

È possibile configurare hub IoT per generare notifiche di modifica del dispositivo gemello per indirizzare a un endpoint supportato. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint > diversi Eventi non di telemetria.

Il codice illustrato nel frammento di codice Java precedente genera l'output seguente quando hub IoT genera notifiche di modifica del dispositivo gemello per un dispositivo termostato senza componenti. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Telemetry received from partition 1:
{"version":11,"properties":{"reported":{"maxTempSinceLastReboot":43.4,"$metadata":{"$lastUpdated":"2020-10-20T11:50:41.123127Z","maxTempSinceLastReboot":{"$lastUpdated":"2020-10-20T11:50:41.123127Z"}},"$version":10}}}
Application properties (set by device):
{operationTimestamp=2020-10-20T11:50:41.1231270+00:00, opType=updateTwin, hubName=my-pnp-hub, deviceId=my-pnp-device, iothub-message-schema=twinChangeNotification}
System properties (set by IoT Hub):
{user-id=[B@12fd5bb4, correlation-id=11339418426a, content-encoding=utf-8, iothub-enqueuedtime=Tue Oct 20 12:50:41 BST 2020, absolute-expiry-time=0, iothub-connection-device-id=my-pnp-device, group-sequence=0, iothub-message-source=twinChangeEvents, creation-time=0, content-type=application/json}

Il codice illustrato nel frammento di codice Java precedente genera l'output seguente quando hub IoT genera notifiche di modifica del dispositivo gemello per un dispositivo con componenti. Questo esempio mostra l'output quando un dispositivo sensore di temperatura con un componente termostato genera notifiche. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Telemetry received from partition 1:
{"version":9,"properties":{"reported":{"thermostat1":{"__t":"c","maxTempSinceLastReboot":32.5},"$metadata":{"$lastUpdated":"2020-10-20T11:48:01.2960851Z","thermostat1":{"$lastUpdated":"2020-10-20T11:48:01.2960851Z","__t":{"$lastUpdated":"2020-10-20T11:48:01.2960851Z"},"maxTempSinceLastReboot":{"$lastUpdated":"2020-10-20T11:48:01.2960851Z"}}},"$version":8}}}
Application properties (set by device):
{operationTimestamp=2020-10-20T11:48:01.2960851+00:00, opType=updateTwin, hubName=my-pnp-hub, deviceId=my-pnp-device, iothub-message-schema=twinChangeNotification}
System properties (set by IoT Hub):
{user-id=[B@23949bae, correlation-id=113334d542e1, content-encoding=utf-8, iothub-enqueuedtime=Tue Oct 20 12:48:01 BST 2020, absolute-expiry-time=0, iothub-connection-device-id=my-pnp-device, group-sequence=0, iothub-message-source=twinChangeEvents, creation-time=0, content-type=application/json}

Leggere le notifiche di modifica del gemello digitale

È possibile configurare hub IoT per generare notifiche di modifica del gemello digitale per indirizzare a un endpoint supportato. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint > diversi Eventi non di telemetria.

Il codice illustrato nel frammento di codice Java precedente genera l'output seguente quando hub IoT genera notifiche di modifica del gemello digitale per un dispositivo termostato senza componenti. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Telemetry received from partition 1:
[{"op":"replace","path":"/$metadata/maxTempSinceLastReboot/lastUpdateTime","value":"2020-10-20T11:52:40.627628Z"},{"op":"replace","path":"/maxTempSinceLastReboot","value":16.9}]
Application properties (set by device):
{operationTimestamp=2020-10-20T11:52:40.6276280+00:00, opType=updateTwin, hubName=my-pnp-hub, deviceId=my-pnp-device, iothub-message-schema=digitalTwinChangeNotification}
System properties (set by IoT Hub):
{user-id=[B@4475ce2a, correlation-id=1133db52c0e0, content-encoding=utf-8, iothub-enqueuedtime=Tue Oct 20 12:52:40 BST 2020, absolute-expiry-time=0, iothub-connection-device-id=my-pnp-device, group-sequence=0, iothub-message-source=digitalTwinChangeEvents, creation-time=0, content-type=application/json-patch+json}

Il codice illustrato nel frammento di codice Java precedente genera l'output seguente quando hub IoT genera notifiche di modifica del gemello digitale per un dispositivo con componenti. Questo esempio mostra l'output quando un dispositivo sensore di temperatura con un componente termostato genera notifiche. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Telemetry received from partition 1:
[{"op":"add","path":"/thermostat1","value":{"$metadata":{"maxTempSinceLastReboot":{"lastUpdateTime":"2020-10-20T11:31:04.7811405Z"}},"maxTempSinceLastReboot":27.2}}]
Application properties (set by device):
{operationTimestamp=2020-10-20T11:31:04.7811405+00:00, opType=updateTwin, hubName=my-pnp-hub, deviceId=my-pnp-device, iothub-message-schema=digitalTwinChangeNotification}
System properties (set by IoT Hub):
{user-id=[B@75981aa, correlation-id=1130d6f4d212, content-encoding=utf-8, iothub-enqueuedtime=Tue Oct 20 12:31:04 BST 2020, absolute-expiry-time=0, iothub-connection-device-id=my-pnp-device, group-sequence=0, iothub-message-source=digitalTwinChangeEvents, creation-time=0, content-type=application/json-patch+json}

Sono disponibili anche le risorse seguenti:

• documentazione di riferimento di Node.js SDK
• Esempi di client di servizio
• Esempi di Gemelli digitali

esempi di client del servizio hub IoT

Questa sezione illustra esempi JavaScript che usano il client del servizio hub IoT e le classi Registry e Client. Usare la classe Registry per interagire con lo stato del dispositivo usando i dispositivi gemelli. È anche possibile usare la classe Registry per eseguire query sulle registrazioni dei dispositivi nel hub IoT. Usare la classe Client per chiamare i comandi nel dispositivo. Il modello DTDL per il dispositivo definisce le proprietà e i comandi implementati dal dispositivo. Nei frammenti di codice la deviceId variabile contiene l'ID dispositivo del dispositivo Plug and Play IoT registrato con l'hub IoT.

Ottenere il dispositivo gemello e l'ID modello

Per ottenere il dispositivo gemello e l'ID modello del dispositivo Plug and Play IoT connesso all'hub IoT:

var Registry = require('azure-iothub').Registry;

// ...

var registry = Registry.fromConnectionString(connectionString);
registry.getTwin(deviceId, function(err, twin) {
  if (err) {
    console.error(err.message);
  } else {
    console.log('Model Id: ' + twin.modelId);
    console.log(JSON.stringify(twin, null, 2));
  }
}

Aggiornamento dispositivo gemello

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un dispositivo. L'esempio mostra come ottenere il gemello prima di aggiornarlo. La proprietà è definita nel componente predefinito del dispositivo:

var Registry = require('azure-iothub').Registry;
var registry = Registry.fromConnectionString(connectionString);

registry.getTwin(deviceId, function(err, twin) {
  if (err) {
    console.error(err.message);
  } else {
    var twinPatch = {
      properties: {
        desired: {
          targetTemperature: 42
        }
      }
    };
    twin.update(twinPatch, function(err, twin) {
      if (err) {
        console.error(err.message);
      } else {
        console.log(JSON.stringify(twin, null, 2));
      }
    }
  }
}

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un componente. L'esempio mostra come ottenere il gemello prima di aggiornarlo. La proprietà è definita nel componente thermostat1 :

var Registry = require('azure-iothub').Registry;
var registry = Registry.fromConnectionString(connectionString);

registry.getTwin(deviceId, function(err, twin) {
  if (err) {
    console.error(err.message);
  } else {
    var twinPatch = {
      properties: {
        desired: {
          thermostat1:
          {
            __t: "c",
            targetTemperature: 45
          }
        }
      }
    };
    twin.update(twinPatch, function(err, twin) {
      if (err) {
        console.error(err.message);
      } else {
        console.log(JSON.stringify(twin, null, 2));
      }
    }
  }
}

Per una proprietà in un componente, la patch della proprietà è simile all'esempio seguente:

{
  "thermostat1":
  {
    "__t": "c",
    "targetTemperature": 20
  }
}

Comando Chiama

Il frammento di codice seguente illustra come richiamare il getMaxMinReport comando definito in un componente predefinito:

var Client = require('azure-iothub').Client;

// ...

var client = Client.fromConnectionString(connectionString);

var methodParams = {
  methodName: "getMaxMinReport",
  payload: new Date().getMinutes -2,
  responseTimeoutInSeconds: 15
};

client.invokeDeviceMethod(deviceId, methodParams, function (err, result) {
  if (err) {
    console.error('Failed to invoke method \'' + methodParams.methodName + '\': ' + err.message);
  } else {
    console.log(methodParams.methodName + ' on ' + deviceId + ':');
    console.log(JSON.stringify(result, null, 2));
  }
});

Il frammento di codice seguente illustra come chiamare il getMaxMinReport comando in un componente. Il comando è definito nel componente thermostat1 :

var Client = require('azure-iothub').Client;

// ...

var client = Client.fromConnectionString(connectionString);

var methodParams = {
  methodName: "thermostat1*getMaxMinReport",
  payload: new Date().getMinutes -2,
  responseTimeoutInSeconds: 15
};

client.invokeDeviceMethod(deviceId, methodParams, function (err, result) {
  if (err) {
    console.error('Failed to invoke method \'' + methodParams.methodName + '\': ' + err.message);
  } else {
    console.log(methodParams.methodName + ' on ' + deviceId + ':');
    console.log(JSON.stringify(result, null, 2));
  }
});

hub IoT esempi di gemelli digitali

Usare la classe DigitalTwinClient per interagire con lo stato del dispositivo usando gemelli digitali. Il modello DTDL per il dispositivo definisce le proprietà e i comandi implementati dal dispositivo.

Questa sezione illustra esempi JavaScript che usano l'API Gemelli digitali.

La digitalTwinId variabile contiene l'ID dispositivo del dispositivo Plug and Play IoT registrato con l'hub IoT.

Ottenere il gemello digitale e l'ID modello

Per ottenere il gemello digitale e l'ID modello del dispositivo Plug and Play IoT connesso all'hub IoT:

const IoTHubTokenCredentials = require('azure-iothub').IoTHubTokenCredentials;
const DigitalTwinClient = require('azure-iothub').DigitalTwinClient;
const { inspect } = require('util');

// ...

const credentials = new IoTHubTokenCredentials(connectionString);
const digitalTwinClient = new DigitalTwinClient(credentials);

const digitalTwin = await digitalTwinClient.getDigitalTwin(digitalTwinId);

console.log(inspect(digitalTwin));
console.log('Model Id: ' + inspect(digitalTwin.$metadata.$model));

Aggiornare il gemello digitale

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un dispositivo. La proprietà è definita nel componente predefinito del dispositivo:

const IoTHubTokenCredentials = require('azure-iothub').IoTHubTokenCredentials;
const DigitalTwinClient = require('azure-iothub').DigitalTwinClient;

// ...

const credentials = new IoTHubTokenCredentials(connString);
const digitalTwinClient = new DigitalTwinClient(credentials);

const patch = [{
  op: 'add',
  path: '/targetTemperature',
  value: 42
}];
await digitalTwinClient.updateDigitalTwin(digitalTwinId, patch);

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un componente. La proprietà è definita nel componente thermostat1 :

const IoTHubTokenCredentials = require('azure-iothub').IoTHubTokenCredentials;
const DigitalTwinClient = require('azure-iothub').DigitalTwinClient;

// ...

const credentials = new IoTHubTokenCredentials(connString);
const digitalTwinClient = new DigitalTwinClient(credentials);

const patch = [{
  op: 'add',
  path: '/thermostat1/targetTemperature',
  value: 42
}];
await digitalTwinClient.updateDigitalTwin(digitalTwinId, patch);

Comando Chiama

Il frammento di codice seguente illustra come richiamare il getMaxMinReport comando definito in un componente predefinito:

const IoTHubTokenCredentials = require('azure-iothub').IoTHubTokenCredentials;
const DigitalTwinClient = require('azure-iothub').DigitalTwinClient;
const { inspect } = require('util');

// ...

const commandPayload = new Date().getMinutes -2;

const credentials = new IoTHubTokenCredentials(connectionString);
const digitalTwinClient = new DigitalTwinClient(credentials);

const options = {
  connectTimeoutInSeconds: 30,
  responseTimeoutInSeconds: 40
};
const commandResponse = await digitalTwinClient.invokeCommand(digitalTwinId, "getMaxMinReport", commandPayload, options);

console.log(inspect(commandResponse));

Il frammento di codice seguente illustra come chiamare il getMaxMinReport comando in un componente. Il comando è definito nel componente thermostat1 :

const IoTHubTokenCredentials = require('azure-iothub').IoTHubTokenCredentials;
const DigitalTwinClient = require('azure-iothub').DigitalTwinClient;
const { inspect } = require('util');

// ...

const commandPayload = new Date().getMinutes -2;

const credentials = new IoTHubTokenCredentials(connectionString);
const digitalTwinClient = new DigitalTwinClient(credentials);

const options = {
  connectTimeoutInSeconds: 30,
  responseTimeoutInSeconds: 40
};
const commandResponse = await digitalTwinClient.invokeComponentCommand(digitalTwinId, "thermostat1", "getMaxMinReport", commandPayload, options);

console.log(inspect(commandResponse));

Leggere i dati di telemetria del dispositivo

Plug and Play IoT dispositivi inviano i dati di telemetria definiti nel modello DTDL a hub IoT. Per impostazione predefinita, hub IoT instrada i dati di telemetria a un endpoint di Hub eventi in cui è possibile usarli. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint diversi.

Il frammento di codice seguente illustra come leggere i dati di telemetria dall'endpoint predefinito di Hub eventi. Il codice in questo frammento viene tratto dalla guida introduttiva hub IoT Inviare dati di telemetria da un dispositivo a un hub IoT e leggerlo con un'applicazione back-end:

const { EventHubConsumerClient } = require("@azure/event-hubs");

var printError = function (err) {
  console.log(err.message);
};

var printMessages = function (messages) {
  for (const message of messages) {
    console.log("Telemetry received: ");
    console.log(JSON.stringify(message.body));
    console.log("Properties (set by device): ");
    console.log(JSON.stringify(message.properties));
    console.log("System properties (set by IoT Hub): ");
    console.log(JSON.stringify(message.systemProperties));
    console.log("");
  }
};

// ...

const clientOptions = {};

const consumerClient = new EventHubConsumerClient("$Default", connectionString, clientOptions);

consumerClient.subscribe({
  processEvents: printMessages,
  processError: printError,
});

L'output seguente del codice precedente mostra i dati di telemetria relativi alla temperatura inviati dal dispositivo TemperatureController a più componenti Plug and Play IoT. La dt-subject proprietà di sistema mostra il nome del componente che ha inviato i dati di telemetria. In questo esempio i due componenti sono thermostat1 e thermostat2 sono definiti nel modello DTDL. La dt-dataschema proprietà di sistema mostra l'ID modello:

Telemetry received:
{"temperature":68.77370855171125}
Properties (set by device):
undefined
System properties (set by IoT Hub):
{"iothub-connection-device-id":"my-pnp-device","iothub-connection-auth-method":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}","iothub-connection-auth-generation-id":"637388034455888246","iothub-enqueuedtime":1603206669320,"iothub-message-source":"Telemetry","dt-subject":"thermostat1","dt-dataschema":"dtmi:com:example:TemperatureController;1","contentType":"application/json","contentEncoding":"utf-8"}

Telemetry received:
{"temperature":30.833394506549226}
Properties (set by device):
undefined
System properties (set by IoT Hub):
{"iothub-connection-device-id":"my-pnp-device","iothub-connection-auth-method":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}","iothub-connection-auth-generation-id":"637388034455888246","iothub-enqueuedtime":1603206665835,"iothub-message-source":"Telemetry","dt-subject":"thermostat2","dt-dataschema":"dtmi:com:example:TemperatureController;1","contentType":"application/json","contentEncoding":"utf-8"}

Leggere le notifiche di modifica del dispositivo gemello

È possibile configurare hub IoT per generare notifiche di modifica del dispositivo gemello per indirizzare a un endpoint supportato. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint > diversi Eventi non di telemetria.

Il codice illustrato nel frammento di codice JavaScript precedente genera l'output seguente quando hub IoT genera notifiche di modifica del dispositivo gemello per un dispositivo termostato senza componenti. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Telemetry received:
{"version":4,"properties":{"reported":{"maxTempSinceLastReboot":42.1415152639582,"$metadata":{"$lastUpdated":"2020-10-21T10:01:40.1281138Z","maxTempSinceLastReboot":{"$lastUpdated":"2020-10-21T10:01:40.1281138Z"}},"$version":3}}}
Properties (set by device):
{"hubName":"my-pnp-hub","deviceId":"my-pnp-device","operationTimestamp":"2020-10-21T10:01:40.1281138+00:00","iothub-message-schema":"twinChangeNotification","opType":"updateTwin"}
System properties (set by IoT Hub):
{"iothub-connection-device-id":"my-pnp-device","iothub-enqueuedtime":1603274500282,"iothub-message-source":"twinChangeEvents","userId":{"type":"Buffer","data":[109,121,45,112,110,112,45,104,117,98]},"correlationId":"11ed82d13f50","contentType":"application/json","contentEncoding":"utf-8"}

Il codice illustrato nel frammento di codice JavaScript precedente genera l'output seguente quando hub IoT genera notifiche di modifica del dispositivo gemello per un dispositivo con componenti. Questo esempio mostra l'output quando un dispositivo sensore di temperatura con un componente termostato genera notifiche. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Telemetry received:
{"version":4,"properties":{"reported":{"thermostat1":{"maxTempSinceLastReboot":3.5592971602417913,"__t":"c"},"$metadata":{"$lastUpdated":"2020-10-21T10:07:51.8284866Z","thermostat1":{"$lastUpdated":"2020-10-21T10:07:51.8284866Z","maxTempSinceLastReboot":{"$lastUpdated":"2020-10-21T10:07:51.8284866Z"},"__t":{"$lastUpdated":"2020-10-21T10:07:51.8284866Z"}}},"$version":3}}}
Properties (set by device):
{"hubName":"my-pnp-hub","deviceId":"my-pnp-device","operationTimestamp":"2020-10-21T10:07:51.8284866+00:00","iothub-message-schema":"twinChangeNotification","opType":"updateTwin"}
System properties (set by IoT Hub):
{"iothub-connection-device-id":"my-pnp-device","iothub-enqueuedtime":1603274871951,"iothub-message-source":"twinChangeEvents","userId":{"type":"Buffer","data":[109,121,45,112,110,112,45,104,117,98]},"correlationId":"11ee605b195f","contentType":"application/json","contentEncoding":"utf-8"}

Leggere le notifiche di modifica del gemello digitale

È possibile configurare hub IoT per generare notifiche di modifica del gemello digitale per indirizzare a un endpoint supportato. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint > diversi Eventi non di telemetria.

Il codice illustrato nel frammento di codice JavaScript precedente genera l'output seguente quando hub IoT genera notifiche di modifica del gemello digitale per un dispositivo termostato senza componenti. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Telemetry received:
[{"op":"add","path":"/$metadata/maxTempSinceLastReboot","value":{"lastUpdateTime":"2020-10-21T10:01:40.1281138Z"}},{"op":"add","path":"/maxTempSinceLastReboot","value":42.1415152639582}]
Properties (set by device):
{"hubName":"my-pnp-hub","deviceId":"my-pnp-device","operationTimestamp":"2020-10-21T10:01:40.1281138+00:00","iothub-message-schema":"digitalTwinChangeNotification","opType":"updateTwin"}
System properties (set by IoT Hub):
{"iothub-connection-device-id":"my-pnp-device","iothub-enqueuedtime":1603274500282,"iothub-message-source":"digitalTwinChangeEvents","userId":{"type":"Buffer","data":[109,121,45,112,110,112,45,104,117,98]},"correlationId":"11ed82d13f50","contentType":"application/json-patch+json","contentEncoding":"utf-8"}

Il codice illustrato nel frammento di codice JavaScript precedente genera l'output seguente quando hub IoT genera notifiche di modifica del gemello digitale per un dispositivo con componenti. Questo esempio mostra l'output quando un dispositivo sensore di temperatura con un componente termostato genera notifiche. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Telemetry received:
[{"op":"add","path":"/thermostat1","value":{"$metadata":{"maxTempSinceLastReboot":{"lastUpdateTime":"2020-10-21T10:07:51.8284866Z"}},"maxTempSinceLastReboot":3.5592971602417913}}]
Properties (set by device):
{"hubName":"my-pnp-hub","deviceId":"my-pnp-device","operationTimestamp":"2020-10-21T10:07:51.8284866+00:00","iothub-message-schema":"digitalTwinChangeNotification","opType":"updateTwin"}
System properties (set by IoT Hub):
{"iothub-connection-device-id":"my-pnp-device","iothub-enqueuedtime":1603274871951,"iothub-message-source":"digitalTwinChangeEvents","userId":{"type":"Buffer","data":[109,121,45,112,110,112,45,104,117,98]},"correlationId":"11ee605b195f","contentType":"application/json-patch+json","contentEncoding":"utf-8"}

Sono disponibili anche le risorse seguenti:

• Documentazione di riferimento di Python SDK
• Esempi di client di servizio
• Esempi di Gemelli digitali

esempi di client del servizio hub IoT

Questa sezione illustra esempi python che usano il client del servizio hub IoT e le classi IoTHubRegistryManager e CloudToDeviceMethod. Usare la classe IoTHubRegistryManager per interagire con lo stato del dispositivo usando i dispositivi gemelli. È anche possibile usare la classe IoTHubRegistryManager per eseguire query sulle registrazioni dei dispositivi nel hub IoT. Usare la classe CloudToDeviceMethod per chiamare i comandi nel dispositivo. Il modello DTDL per il dispositivo definisce le proprietà e i comandi implementati dal dispositivo. Nei frammenti di codice la device_id variabile contiene l'ID dispositivo del dispositivo Plug and Play IoT registrato con l'hub IoT.

Ottenere il dispositivo gemello e l'ID modello

Per ottenere il dispositivo gemello e l'ID modello del dispositivo Plug and Play IoT connesso all'hub IoT:

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties

iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)

# ...

twin = iothub_registry_manager.get_twin(device_id)
print("The device twin is: ")
print("")
print(twin)
print("")

additional_props = twin.additional_properties
if "modelId" in additional_props:
    print("The Model ID for this device is:")
    print(additional_props["modelId"])
    print("")

Aggiornamento dispositivo gemello

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un dispositivo. L'esempio mostra come è necessario ottenere il gemello prima di etag aggiornarlo. La proprietà è definita nel componente predefinito del dispositivo:

iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)

twin = iothub_registry_manager.get_twin(device_id)

twin_patch = Twin()

twin_patch.properties = TwinProperties(
    desired={"targetTemperature": 42}
)
updated_twin = iothub_registry_manager.update_twin(device_id, twin_patch, twin.etag)

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un componente. L'esempio mostra come è necessario ottenere il gemello prima di ETag aggiornarlo. La proprietà è definita nel componente thermostat1 :

iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)

twin = iothub_registry_manager.get_twin(device_id)

twin_patch = Twin()

twin_patch.properties = TwinProperties(
    desired={ "thermostat1": {
        "__t": "c",
        "targetTemperature": 42}
    }
)
updated_twin = iothub_registry_manager.update_twin(device_id, twin_patch, twin.etag)

Per una proprietà in un componente, la patch della proprietà è simile all'esempio seguente:

{
"thermostat1":
  {
    "__t": "c",
    "targetTemperature": 20
  }
}

Comando Chiama

Il frammento di codice seguente illustra come richiamare il getMaxMinReport comando definito in un componente predefinito:

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod

# ...

iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)

method_payload = datetime.datetime.now() - datetime.timedelta(minutes=2)
device_method = CloudToDeviceMethod(method_name="getMaxMinReport", payload=method_payload)
result = iothub_registry_manager.invoke_device_method(device_id, device_method)
print(result.payload)

Il frammento di codice seguente illustra come chiamare il getMaxMinReport comando in un componente. Il comando è definito nel componente thermostat1 :

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod

# ...

iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)

method_payload = datetime.datetime.now() - datetime.timedelta(minutes=2)
device_method = CloudToDeviceMethod(method_name="thermostat1*getMaxMinReport", payload=method_payload)
result = iothub_registry_manager.invoke_device_method(device_id, device_method)
print(result.payload)

hub IoT esempi di gemelli digitali

Usare la classe DigitalTwinClient per interagire con lo stato del dispositivo usando gemelli digitali. Il modello DTDL per il dispositivo definisce le proprietà e i comandi implementati dal dispositivo.

La device_id variabile contiene l'ID dispositivo del dispositivo Plug and Play IoT registrato con l'hub IoT.

Ottenere il gemello digitale e l'ID modello

Per ottenere il gemello digitale e l'ID modello del dispositivo Plug and Play IoT connesso all'hub IoT:

from azure.iot.hub import DigitalTwinClient

digital_twin_client = DigitalTwinClient(iothub_connection_str)

digital_twin = digital_twin_client.get_digital_twin(device_id)
if digital_twin:
    print(digital_twin)
    print("Model Id: " + digital_twin["$metadata"]["$model"])
else:
    print("No digital_twin found")

Aggiornare il gemello digitale

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un dispositivo. La proprietà è definita nel componente predefinito del dispositivo:

from azure.iot.hub import DigitalTwinClient

digital_twin_client = DigitalTwinClient(iothub_connection_str)

patch = [{"op": "add", "path": "/targetTemperature", "value": 42}]
digital_twin_client.update_digital_twin(device_id, patch)

Il frammento di codice seguente illustra come aggiornare la targetTemperature proprietà in un componente. La proprietà è definita nel componente thermostat1 :

from azure.iot.hub import DigitalTwinClient

digital_twin_client = DigitalTwinClient(iothub_connection_str)

patch = [{"op": "add", "path": "/targetTemperature", "value": 42}]
digital_twin_client.update_digital_twin(device_id, patch)

Comando Chiama

Il frammento di codice seguente illustra come richiamare il getMaxMinReport comando definito in un componente predefinito:

from azure.iot.hub import DigitalTwinClient

payload = datetime.datetime.now() - datetime.timedelta(minutes=2)

connect_timeout_in_seconds = 3
response_timeout_in_seconds = 7


digital_twin_client = DigitalTwinClient(iothub_connection_str)

invoke_command_result = digital_twin_client.invoke_command(
    device_id, "getMaxMinReport", payload, connect_timeout_in_seconds, response_timeout_in_seconds
)
if invoke_command_result:
    print(invoke_command_result)
else:
    print("No invoke_command_result found")

Il frammento di codice seguente illustra come chiamare il getMaxMinReport comando in un componente. Il comando è definito nel componente thermostat1 :

from azure.iot.hub import DigitalTwinClient

payload = datetime.datetime.now() - datetime.timedelta(minutes=2)

connect_timeout_in_seconds = 3
response_timeout_in_seconds = 7


digital_twin_client = DigitalTwinClient(iothub_connection_str)

invoke_command_result = digital_twin_client.invoke_component_command(
    device_id, "thermostat1", "getMaxMinReport", payload, connect_timeout_in_seconds, response_timeout_in_seconds
)
if invoke_command_result:
    print(invoke_command_result)
else:
    print("No invoke_command_result found")

Leggere i dati di telemetria del dispositivo

Plug and Play IoT dispositivi inviano i dati di telemetria definiti nel modello DTDL a hub IoT. Per impostazione predefinita, hub IoT instrada i dati di telemetria a un endpoint di Hub eventi in cui è possibile usarli. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint diversi.

Il frammento di codice seguente illustra come leggere i dati di telemetria dall'endpoint predefinito di Hub eventi. Il codice in questo frammento viene tratto dalla guida introduttiva hub IoT Inviare dati di telemetria da un dispositivo a un hub IoT e leggerlo con un'applicazione back-end:

import asyncio
from azure.eventhub import TransportType
from azure.eventhub.aio import EventHubConsumerClient

# Define callbacks to process events
async def on_event_batch(partition_context, events):
    for event in events:
        print("Received event from partition: {}.".format(partition_context.partition_id))
        print("Telemetry received: ", event.body_as_str())
        print("Properties (set by device): ", event.properties)
        print("System properties (set by IoT Hub): ", event.system_properties)
        print()
    await partition_context.update_checkpoint()

async def on_error(partition_context, error):
    # ...

loop = asyncio.get_event_loop()
client = EventHubConsumerClient.from_connection_string(
    conn_str=CONNECTION_STR,
    consumer_group="$default",
)

try:
    loop.run_until_complete(client.receive_batch(on_event_batch=on_event_batch, on_error=on_error))
except KeyboardInterrupt:
    print("Receiving has stopped.")
finally:
    loop.run_until_complete(client.close())
    loop.stop()

L'output seguente del codice precedente mostra i dati di telemetria relativi alla temperatura inviati dal termostato senza componenti Plug and Play IoT dispositivo che ha solo il componente predefinito. La dt-dataschema proprietà di sistema mostra l'ID modello:

Received event from partition: 1.
Telemetry received:  {"temperature": 12}
Properties (set by device):  None
System properties (set by IoT Hub):  {b'content-type': b'application/json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-connection-auth-method': b'{"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}', b'iothub-connection-auth-generation-id': b'637388855582764406', b'iothub-enqueuedtime': 1603288810715, b'iothub-message-source': b'Telemetry', b'dt-dataschema': b'dtmi:com:example:Thermostat;1', b'x-opt-sequence-number': 13280, b'x-opt-offset': b'12890070640', b'x-opt-enqueued-time': 1603288810824}

L'output seguente del codice precedente mostra i dati di telemetria relativi alla temperatura inviati dal dispositivo TemperatureController a più componenti Plug and Play IoT. La dt-subject proprietà di sistema mostra il nome del componente che ha inviato i dati di telemetria. In questo esempio i due componenti sono thermostat1 e thermostat2 sono definiti nel modello DTDL. La dt-dataschema proprietà di sistema mostra l'ID modello:

Received event from partition: 1.
Telemetry received:  {"temperature": 45}
Properties (set by device):  None
System properties (set by IoT Hub):  {b'content-type': b'application/json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-connection-auth-method': b'{"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}', b'iothub-connection-auth-generation-id': b'637388858939631652', b'iothub-enqueuedtime': 1603289127844, b'iothub-message-source': b'Telemetry', b'dt-subject': b'thermostat1', b'dt-dataschema': b'dtmi:com:example:TemperatureController;1', b'x-opt-sequence-number': 13328, b'x-opt-offset': b'12890095440', b'x-opt-enqueued-time': 1603289128001}

Received event from partition: 1.
Telemetry received:  {"temperature": 49}
Properties (set by device):  None
System properties (set by IoT Hub):  {b'content-type': b'application/json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-connection-auth-method': b'{"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}', b'iothub-connection-auth-generation-id': b'637388858939631652', b'iothub-enqueuedtime': 1603289133017, b'iothub-message-source': b'Telemetry', b'dt-subject': b'thermostat2', b'dt-dataschema': b'dtmi:com:example:TemperatureController;1', b'x-opt-sequence-number': 13329, b'x-opt-offset': b'12890095928', b'x-opt-enqueued-time': 1603289133173}

Leggere le notifiche di modifica del dispositivo gemello

È possibile configurare hub IoT per generare notifiche di modifica del dispositivo gemello per indirizzare a un endpoint supportato. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint > diversi Eventi non di telemetria.

Il codice illustrato nel frammento di codice Python precedente genera l'output seguente quando hub IoT genera notifiche di modifica del dispositivo gemello per un dispositivo termostato senza componenti. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Received event from partition: 1.
Telemetry received:  {"version":3,"properties":{"reported":{"maxTempSinceLastReboot":10.96,"$metadata":{"$lastUpdated":"2020-10-21T14:10:42.4171263Z","maxTempSinceLastReboot":{"$lastUpdated":"2020-10-21T14:10:42.4171263Z"}},"$version":2}}}
Properties (set by device):  {b'hubName': b'my-pnp-hub', b'deviceId': b'my-pnp-device', b'operationTimestamp': b'2020-10-21T14:10:42.4171263+00:00', b'iothub-message-schema': b'twinChangeNotification', b'opType': b'updateTwin'}
System properties (set by IoT Hub):  {b'user-id': b'my-pnp-hub\x81\x0e\xa4\x7f', b'correlation-id': b'12104ced5402', b'content-type': b'application/json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-enqueuedtime': 1603289442519, b'iothub-message-source': b'twinChangeEvents', b'x-opt-sequence-number': 13332, b'x-opt-offset': b'12890097392', b'x-opt-enqueued-time': 1603289442738}

Il codice illustrato nel frammento di codice Python precedente genera l'output seguente quando hub IoT genera notifiche di modifica del dispositivo gemello per un dispositivo con componenti. Questo esempio mostra l'output quando un dispositivo sensore di temperatura con un componente termostato genera notifiche. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Received event from partition: 1.
Telemetry received:  {"version":4,"properties":{"reported":{"thermostat1":{"maxTempSinceLastReboot":98.34,"__t":"c"},"$metadata":{"$lastUpdated":"2020-10-21T14:13:39.36491Z","thermostat1":{"$lastUpdated":"2020-10-21T14:13:39.36491Z","maxTempSinceLastReboot":{"$lastUpdated":"2020-10-21T14:13:39.36491Z"},"__t":{"$lastUpdated":"2020-10-21T14:13:39.36491Z"}}},"$version":3}}}
Properties (set by device):  {b'hubName': b'my-pnp-hub', b'deviceId': b'my-pnp-device', b'operationTimestamp': b'2020-10-21T14:13:39.3649100+00:00', b'iothub-message-schema': b'twinChangeNotification', b'opType': b'updateTwin'}
System properties (set by IoT Hub):  {b'user-id': b'my-pnp-hub', b'correlation-id': b'1210b664ab83', b'content-type': b'application/json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-enqueuedtime': 1603289619481, b'iothub-message-source': b'twinChangeEvents', b'x-opt-sequence-number': 13341, b'x-opt-offset': b'12890102216', b'x-opt-enqueued-time': 1603289619668}

Leggere le notifiche di modifica del gemello digitale

È possibile configurare hub IoT per generare notifiche di modifica del gemello digitale per indirizzare a un endpoint supportato. Per altre informazioni, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint > diversi Eventi non di telemetria.

Il codice illustrato nel frammento di codice Python precedente genera l'output seguente quando hub IoT genera notifiche di modifica del gemello digitale per un dispositivo termostato senza componenti. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Received event from partition: 1.
Telemetry received:  [{"op":"add","path":"/$metadata/maxTempSinceLastReboot","value":{"lastUpdateTime":"2020-10-21T14:10:42.4171263Z"}},{"op":"add","path":"/maxTempSinceLastReboot","value":10.96}]
Properties (set by device):  {b'hubName': b'my-pnp-hub', b'deviceId': b'my-pnp-device', b'operationTimestamp': b'2020-10-21T14:10:42.4171263+00:00', b'iothub-message-schema': b'digitalTwinChangeNotification', b'opType': b'updateTwin'}
System properties (set by IoT Hub):  {b'user-id': b'my-pnp-hub\x81\x0e\xa4\x7f', b'correlation-id': b'12104ced5402', b'content-type': b'application/json-patch+json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-enqueuedtime': 1603289442519, b'iothub-message-source': b'digitalTwinChangeEvents', b'x-opt-sequence-number': 13333, b'x-opt-offset': b'12890098024', b'x-opt-enqueued-time': 1603289442738}

Il codice illustrato nel frammento di codice Python precedente genera l'output seguente quando hub IoT genera notifiche di modifica del gemello digitale per un dispositivo con componenti. Questo esempio mostra l'output quando un dispositivo sensore di temperatura con un componente termostato genera notifiche. Le proprietà iothub-message-schema dell'applicazione e opType forniscono informazioni sul tipo di notifica delle modifiche:

Received event from partition: 1.
Telemetry received:  [{"op":"add","path":"/thermostat1","value":{"$metadata":{"maxTempSinceLastReboot":{"lastUpdateTime":"2020-10-21T14:13:39.36491Z"}},"maxTempSinceLastReboot":98.34}}]
Properties (set by device):  {b'hubName': b'my-pnp-hub', b'deviceId': b'my-pnp-device', b'operationTimestamp': b'2020-10-21T14:13:39.3649100+00:00', b'iothub-message-schema': b'digitalTwinChangeNotification', b'opType': b'updateTwin'}
System properties (set by IoT Hub):  {b'user-id': b'my-pnp-hub', b'correlation-id': b'1210b664ab83', b'content-type': b'application/json-patch+json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-enqueuedtime': 1603289619481, b'iothub-message-source': b'digitalTwinChangeEvents', b'x-opt-sequence-number': 13342, b'x-opt-offset': b'12890102984', b'x-opt-enqueued-time': 1603289619668}

Passaggi successivi

Dopo aver appreso la modellazione dei dispositivi, ecco alcune altre risorse:

• DTDL (Digital Twins Definition Language)
• SDK per dispositivi C
• IoT REST API
• guida alla modellazione di Plug and Play IoT