Introduzione ai dispositivi gemelli (Java)

I dispositivi gemelli sono documenti JSON nei quali vengono archiviate informazioni sullo stato dei dispositivi (metadati, configurazioni e condizioni). L'hub IoT rende permanente un dispositivo gemello per ogni dispositivo che si connette.

Usare i dispositivi gemelli per:

  • Archiviare i metadati dei dispositivi dal back-end della soluzione.
  • Segnalare informazioni sullo stato corrente, come funzionalità disponibili e condizioni (ad esempio, il metodo di connettività usato) dall'app per dispositivi.
  • Sincronizzare lo stato dei flussi di lavoro a esecuzione prolungata (come gli aggiornamenti del firmware e della configurazione) tra un'app per dispositivi e un'app di back-end.
  • Eseguire query sui metadati, la configurazione o lo stato dei dispositivi.
Nota

I dispositivi gemelli sono progettati per la sincronizzazione e per l'esecuzione di query sulle configurazioni e le condizioni dei dispositivi. Altre informazioni su quando usare i dispositivi gemelli sono reperibili in Informazioni sui dispositivi gemelli.

I dispositivi gemelli vengono archiviati in un hub IoT e contengono gli elementi seguenti.

  • Tag: metadati dei dispositivi accessibili solo dal back-end della soluzione
  • Proprietà desiderate: oggetti JSON modificabili dal back-end della soluzione e osservabili dall'app per dispositivi
  • Proprietà segnalate: oggetti JSON modificabili dall'app per dispositivi e leggibili dal back-end della soluzione I tag e le proprietà non possono contenere matrici, ma gli oggetti possono essere annidati.

Il back-end della soluzione può anche eseguire query sui dispositivi gemelli in base a tutti i dati sopra indicati. Vedere Informazioni sui dispositivi gemelli per altre informazioni sui dispositivi gemelli e Linguaggio di query per hub IoT per informazioni sull'esecuzione di query.

Nota

Al momento i dispositivi gemelli sono accessibili solo dai dispositivi che si connettono all'hub IoT tramite il protocollo MQTT. Per istruzioni su come convertire l'app per dispositivo esistente in modo che usi MQTT, vedere l'articolo Supporto di MQTT.

Questa esercitazione illustra come:

  • Creare un'app back-end che aggiunge tag a un dispositivo gemello e un'app per dispositivo simulato che segnala il proprio canale di connettività come proprietà segnalata nel dispositivo gemello.
  • Eseguire query sui dispositivi dall'app back-end con filtri sui tag e sulle proprietà creati in precedenza.

In questa esercitazione vengono create due app console Java:

  • add-tags-query, un'app back-end .Java che aggiunge tag ed effettua query sui dispositivi gemelli.
  • simulated-device, un'app per dispositivi Java che si connette all'hub IoT e segnala la condizione di connettività usando una proprietà segnalata.
Nota

L'articolo Azure IoT SDK contiene informazioni sui componenti Azure IoT SDK che consentono di compilare le app back-end e per dispositivi.

Per completare questa esercitazione, sono necessari:

Creare un hub IoT

Creare un hub IoT per connettere l'app per dispositivo simulato. La procedura seguente illustra come completare questa attività usando il portale di Azure.

  1. Accedere al portale di Azure.
  2. Nell'indice fare clic su Nuovo > Internet delle cose > Hub IoT.

    Indice del portale di Azure

  3. Nel pannello Hub IoT scegliere la configurazione per l'hub IoT.

    Pannello Hub IoT

    1. Nella casella Nome immettere un nome per l'hub IoT. Se il Nome è valido e disponibile, appare un segno di spunta verde nella casella Nome.

      Importante

      L'hub IoT sarà individuabile pubblicamente come endpoint DNS, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.

    2. Selezionare un piano tariffario e un livello di scalabilità. Per questa esercitazione non è necessario un livello specifico. Per questa esercitazione, usare il livello F1 gratuito.

    3. In Gruppo di risorse creare un gruppo di risorse o selezionarne uno esistente. Per altre informazioni, vedere Using resource groups to manage your Azure resources (Uso di Gruppi di risorse per gestire le risorse di Azure).
    4. In Percorsoselezionare il percorso per ospitare l'hub IoT. Per questa esercitazione, scegliere la località più vicina.
  4. Dopo aver scelto le opzioni di configurazione dell'hub IoT, fare clic su Crea. La creazione dell'hub IoT da parte di Azure può richiedere alcuni minuti. Per verificare lo stato, è possibile monitorare l'avanzamento nella Schermata iniziale o nel pannello Notifiche.

    Stato del nuovo hub IoT

  5. Dopo avere creato l'hub IoT, fare clic sul nuovo riquadro per l'hub IoT nel portale di Azure per aprire il pannello del nuovo hub IoT. Annotare il Nome host, quindi fare clic su Criteri di accesso condiviso.

    Pannello del nuovo hub IoT

  6. Nel pannello Criteri di accesso condivisi fare clic sul criterio iothubowner, quindi copiare e annotare la stringa di connessione dell'hub IoT nel pannello iothubowner. Per altre informazioni, vedere Controllo di accesso nella "Guida per gli sviluppatori dell'hub IoT".

    Pannello Criteri di accesso condivisi

Creare un'identità del dispositivo

In questa sezione si usa il portale di Azure per creare un'identità del dispositivo nel registro delle identità dell'hub IoT. Un dispositivo non può connettersi all'hub IoT a meno che non abbia una voce nel registro di identità. Per altre informazioni, vedere la sezione "Registro di identità" della Guida per gli sviluppatori dell'hub IoT. Nel portale, Device Explorer consente di generare una chiave e un ID dispositivo univoci con cui il dispositivo può identificarsi quando si connette all'hub IoT. Gli ID dispositivo fanno distinzione tra maiuscole e minuscole.

  1. Assicurarsi di aver eseguito l'accesso al portale di Azure.

  2. Nell'indice fare clic su Tutte le risorse e trovare la risorsa hub IoT.

    Passare all'hub IoT

  3. Dopo aver aperto la risorsa hub IoT, fare clic sullo strumento Device Explorer e quindi su Aggiungi nella parte superiore. Specificare un nome per il nuovo dispositivo, ad esempio myDeviceId e fare clic su Salva.

    Creare l'identità del dispositivo nel portale

    In questo modo viene creata una nuova identità del dispositivo per l'hub IoT.

    Importante

    L'ID dispositivo può essere visibile nei log raccolti per il supporto tecnico e la risoluzione dei problemi, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.

  4. Nell'elenco dei dispositivi in Device Explorer fare clic sul dispositivo appena creato e prendere nota della Stringa di connessione - chiave primaria.

    Stringa di connessione del dispositivo

Nota

Il registro di identità dell'hub IoT archivia solo le identità del dispositivo per abilitare l'accesso sicuro all'hub. Archivia gli ID dispositivo e le chiavi da usare come credenziali di sicurezza e un flag di attivazione/disattivazione che consente di disabilitare l'accesso per un singolo dispositivo. Se l'applicazione deve archiviare altri metadati specifici del dispositivo, dovrà usare un archivio specifico dell'applicazione. Per altre informazioni, vedere la Guida per gli sviluppatori dell'hub IoT.

Se si preferisce creare l'identità del dispositivo a livello di programmazione, leggere la sezione corrispondente nell'articolo Connettere il dispositivo all'hub IoT usando Java.

Creare l'app di servizio

In questa sezione si crea a un'app Java che aggiunge i metadati della posizione come tag al dispositivo gemello nell'hub IoT associato a myDeviceId. L'app esegue innanzitutto una query dell'hub IoT per i dispositivi che si trovano negli Stati Uniti, quindi per i dispositivi che segnalano una connessione di rete tramite cellulare.

  1. Nel computer di sviluppo creare una cartella vuota denominata iot-java-twin-getstarted.

  2. Nella cartella iot-java-twin-getstarted creare un progetto Maven denominato add-tags-query eseguendo questo comando al prompt dei comandi. Si noti che si tratta di un lungo comando singolo:

    mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=add-tags-query -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

  3. Al prompt dei comandi passare alla cartella add-tags-query.

  4. In un editor di testo aprire il file pom.xml nella cartella add-tags-query e aggiungere la dipendenza seguente al nodo dependencies. Questa dipendenza consente di usare il pacchetto iot-service-client nell'app per comunicare con l'hub IoT:

    <dependency>
      <groupId>com.microsoft.azure.sdk.iot</groupId>
      <artifactId>iot-service-client</artifactId>
      <version>1.7.23</version>
      <type>jar</type>
    </dependency>
    
    Nota

    È possibile cercare la versione più recente di iot-service-client usando la ricerca di Maven.

  5. Aggiungere il nodo build seguente dopo il nodo dependencies. Questa configurazione indica a Maven di usare Java 1.8 per compilare l'app:

    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.3</version>
          <configuration>
            <source>1.8</source>
            <target>1.8</target>
          </configuration>
        </plugin>
      </plugins>
    </build>
    
  6. Salvare e chiudere il file pom.xml.

  7. Aprire il file add-tags-query\src\main\java\com\mycompany\app\App.java in un editor di testo.

  8. Aggiungere al file le istruzioni import seguenti:

    import com.microsoft.azure.sdk.iot.service.devicetwin.*;
    import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;
    
    import java.io.IOException;
    import java.util.HashSet;
    import java.util.Set;
    
  9. Aggiungere le variabili a livello di classe seguenti alla classe App . Sostituire {youriothubconnectionstring} con la stringa di connessione dell'hub IoT indicata nella sezione Creare un hub IoT:

    public static final String iotHubConnectionString = "{youriothubconnectionstring}";
    public static final String deviceId = "myDeviceId";
    
    public static final String region = "US";
    public static final String plant = "Redmond43";
    
  10. Aggiornare la firma del metodo main affinché includa la clausola throws:

    public static void main( String[] args ) throws IOException
    
  11. Aggiungere il codice seguente al metodo main per creare gli oggetti DeviceTwin e DeviceTwinDevice. L'oggetto DeviceTwin gestisce la comunicazione con l'hub IoT. L'oggetto DeviceTwinDevice rappresenta un dispositivo gemello con le relative proprietà e tag:

    // Get the DeviceTwin and DeviceTwinDevice objects
    DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
    DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
    
  12. Aggiungere il blocco try/catch seguente al metodo main:

    try {
      // Code goes here
    } catch (IotHubException e) {
      System.out.println(e.getMessage());
    } catch (IOException e) {
      System.out.println(e.getMessage());
    }
    
  13. Per aggiornare i tag del dispositivo gemello region e plant nel dispositivo gemello, aggiungere il codice seguente nel blocco try:

    // Get the device twin from IoT Hub
    System.out.println("Device twin before update:");
    twinClient.getTwin(device);
    System.out.println(device);
    
    // Update device twin tags if they are different
    // from the existing values
    String currentTags = device.tagsToString();
    if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {
      // Create the tags and attach them to the DeviceTwinDevice object
      Set<Pair> tags = new HashSet<Pair>();
      tags.add(new Pair("region", region));
      tags.add(new Pair("plant", plant));
      device.setTags(tags);
    
      // Update the device twin in IoT Hub
      System.out.println("Updating device twin");
      twinClient.updateTwin(device);
    }
    
    // Retrieve the device twin with the tag values from IoT Hub
    System.out.println("Device twin after update:");
    twinClient.getTwin(device);
    System.out.println(device);
    
  14. Per eseguire una query sui dispositivi gemelli nell'hub IoT, aggiungere il codice seguente al blocco try dopo il codice aggiunto nel passaggio precedente. Il codice esegue due query. Ogni query restituisce un massimo di 100 dispositivi:

    // Query the device twins in IoT Hub
    System.out.println("Devices in Redmond:");
    
    // Construct the query
    SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);
    
    // Run the query, returning a maximum of 100 devices
    Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
    while (twinClient.hasNextDeviceTwin(twinQuery)) {
      DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
      System.out.println(d.getDeviceId());
    }
    
    System.out.println("Devices in Redmond using a cellular network:");
    
    // Construct the query
    sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);
    
    // Run the query, returning a maximum of 100 devices
    twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
    while (twinClient.hasNextDeviceTwin(twinQuery)) {
      DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
      System.out.println(d.getDeviceId());
    }
    
  15. Salvare e chiudere il file add-tags-query\src\main\java\com\mycompany\app\App.java

  16. Compilare l'app add-tags-query e correggere eventuali errori. Al prompt dei comandi passare alla cartella add-tags-query ed eseguire il comando seguente:

    mvn clean package -DskipTests

Creare un'app per dispositivi

In questa sezione si crea un'app console Java che imposta un valore di proprietà restituito che viene inviato all'IoT Hub.

  1. Nella cartella iot-java-twin-getstarted creare un progetto Maven denominato simulated-device usando il comando seguente nel prompt dei comandi. Si noti che si tratta di un lungo comando singolo:

    mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=simulated-device -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

  2. Al prompt dei comandi passare alla cartella simulated-device.

  3. In un editor di testo aprire il file pom.xml nella cartella simulated-device e aggiungere le dipendenze seguenti al nodo dependencies. Questa dipendenza consente di usare il pacchetto iot-device-client nell'app per comunicare con l'hub IoT:

    <dependency>
      <groupId>com.microsoft.azure.sdk.iot</groupId>
      <artifactId>iot-device-client</artifactId>
      <version>1.3.32</version>
    </dependency>
    
    Nota

    È possibile cercare la versione più recente di iot-device-client usando la ricerca di Maven.

  4. Aggiungere il nodo build seguente dopo il nodo dependencies. Questa configurazione indica a Maven di usare Java 1.8 per compilare l'app:

    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.3</version>
          <configuration>
            <source>1.8</source>
            <target>1.8</target>
          </configuration>
        </plugin>
      </plugins>
    </build>
    
  5. Salvare e chiudere il file pom.xml.

  6. Aprire il file simulated-device\src\main\java\com\mycompany\app\App.java in un editor di testo.

  7. Aggiungere al file le istruzioni import seguenti:

    import com.microsoft.azure.sdk.iot.device.*;
    import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;
    
    import java.io.IOException;
    import java.net.URISyntaxException;
    import java.util.Scanner;
    
  8. Aggiungere le variabili a livello di classe seguenti alla classe App . Sostituzione di {youriothubname} con il nome dell'hub IoT e {yourdevicekey} con il valore della chiave del dispositivo generato nella sezione Creare un'identità del dispositivo:

    private static String connString = "HostName={youriothubname}.azure-devices.net;DeviceId=myDeviceID;SharedAccessKey={yourdevicekey}";
    private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
    private static String deviceId = "myDeviceId";
    

    Questa app di esempio usa la variabile protocol quando crea un'istanza di un oggetto DeviceClient. Attualmente per usare le funzionalità del dispositivo gemello è necessario usare il protocollo MQTT.

  9. Al metodo main aggiungere il codice seguente:

    • Creare un client del dispositivo per comunicare con l'IoT Hub.
    • Creare un Device oggetto per archiviare le proprietà dispositivi gemelli.

      DeviceClient client = new DeviceClient(connString, protocol);
      
      // Create a Device object to store the device twin properties
      Device dataCollector = new Device() {
      // Print details when a property value changes
      @Override
      public void PropertyCall(String propertyKey, Object propertyValue, Object context) {
        System.out.println(propertyKey + " changed to " + propertyValue);
      }
      };
      
  10. Aggiungere il codice seguente al metodo main per creare una proprietà segnalata connectivityType e inviarla all'IoT Hub:

    try {
      // Open the DeviceClient and start the device twin services.
      client.open();
      client.startDeviceTwin(new DeviceTwinStatusCallBack(), null, dataCollector, null);
    
      // Create a reported property and send it to your IoT hub.
      dataCollector.setReportedProp(new Property("connectivityType", "cellular"));
      client.sendReportedProperties(dataCollector.getReportedProp());
    }
    catch (Exception e) {
      System.out.println("On exception, shutting down \n" + " Cause: " + e.getCause() + " \n" + e.getMessage());
      dataCollector.clean();
      client.close();
      System.out.println("Shutting down...");
    }
    
  11. Alla fine del metodo main aggiungere il codice seguente. Attendere che il tasto Invio consenta all'IoT Hub di segnalare lo stato delle operazioni del dispositivo gemello:

    System.out.println("Press any key to exit...");
    
    Scanner scanner = new Scanner(System.in);
    scanner.nextLine();
    
    dataCollector.clean();
    client.close();
    
  12. Salvare e chiudere il file simulated-device\src\main\java\com\mycompany\app\App.java.

  13. Compilare l'app simulated-device e correggere eventuali errori. Al prompt dei comandi passare alla cartella simulated-device ed eseguire il comando seguente:

    mvn clean package -DskipTests

Eseguire le app

A questo punto è possibile eseguire le app console.

  1. Al prompt dei comandi nella cartella add-tags-query eseguire il comando seguente per eseguire l'app del servizio add-tags-query:

    mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

    App del servizio hub IoT Java per aggiornare i valori dei tag ed eseguire query di dispositivo

    È possibile visualizzare i tag plant e region aggiunti al dispositivo gemello. Solo la prima query restituisce il dispositivo, non la seconda.

  2. Al prompt dei comandi nella cartella simulated-device eseguire il comando seguente per aggiungere la proprietà segnalata connectivityType al dispositivo gemello:

    mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

    Il client del dispositivo aggiunge la proprietà segnalata **connectivityType**

  3. Al prompt dei comandi nella cartella add-tags-query eseguire il comando seguente per eseguire l'app del servizio add-tags-query una seconda volta:

    mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

    App del servizio hub IoT Java per aggiornare i valori dei tag ed eseguire query di dispositivo

    Ora che il dispositivo ha inviato la proprietà connectivityType all'hub IoT, la seconda query restituisce il dispositivo.

Passaggi successivi

In questa esercitazione è stato configurato un nuovo hub IoT nel Portale di Azure ed è stata quindi creata un'identità del dispositivo nel registro di identità dell'hub IoT. Sono stati aggiunti i metadati del dispositivo come tag da un'app back-end ed è stata scritta un'app per dispositivo per segnalare le informazioni sulla connettività del dispositivo nel dispositivo gemello. Si è anche appreso come effettuare una query delle informazioni del dispositivo gemello usando il linguaggio di query simile a SQL dell'hub IoT.

Per altre informazioni, vedere le risorse seguenti:

  • Per inviare dati di telemetria dai dispositivi, vedere l'esercitazione Introduzione all'hub IoT.
  • Per controllare i dispositivi in modo interattivo, ad esempio per attivare un ventilatore da un'app controllata dall'utente, vedere l'esercitazione Usare metodi diretti.