Introduzione ai dispositivi gemelli (Java)

Articolo
03/18/2023

i dispositivi gemelli sono documenti JSON che archiviano informazioni sullo stato dei dispositivi, tra cui metadati, configurazioni e condizioni. L'hub IoT rende permanente un dispositivo gemello per ogni dispositivo che si connette.

Nota

Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli Basic e Standard/Gratuito dell'hub IoT, vedere Scegliere il livello appropriato dell'hub IoT per la soluzione.

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.

I dispositivi gemelli sono progettati per la sincronizzazione e per l'esecuzione di query sulle configurazioni e le condizioni dei dispositivi. Per altre informazioni sui dispositivi gemelli, tra cui quando usarli, vedere Informazioni sui dispositivi gemelli.

Gli hub IoT archiviano i dispositivi gemelli, che 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 possono contenere oggetti annidati.

Nella figura seguente viene illustrata l'organizzazione di un dispositivo gemello:

Screenshot di un diagramma concettuale del dispositivo gemello.

Il back-end della soluzione può anche eseguire query sui dispositivi gemelli in base a tutti i dati sopra indicati. Per altre informazioni sui dispositivi gemelli, vedere Informazioni sui dispositivi gemelli. Per altre informazioni sulle query, vedere Linguaggio di query di hub IoT.

Questo articolo illustra come:

Usare un'app per dispositivo simulato per segnalare il 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 questo articolo vengono creati due app console Java:

add-tags-query, un'app back-end che aggiunge tag ed effettua query sui dispositivi gemelli.
simulated-device: un'app per dispositivi simulata che si connette all'hub IoT e ne segnala la condizione di connettività.

Nota

Vedere Azure IoT SDK per altre informazioni sugli strumenti SDK disponibili per creare app sia per dispositivi che back-end.

Prerequisiti

Un hub IoT. Crearne una con l'interfaccia della riga di comando o con il portale di Azure.
Un dispositivo registrato nell'hub IoT. Se non si ha un dispositivo nell'hub IoT, seguire la procedura descritta in Registrare un dispositivo.
Java SE Development Kit 8. Assicurarsi di selezionare Java 8 in Supporto a lungo termine per passare ai download per JDK 8.
Maven 3
Assicurarsi che la porta 8883 sia aperta nel firewall. L'esempio di dispositivo di questo articolo usa il protocollo MQTT, che comunica tramite la porta 8883. Questa porta potrebbe essere bloccata in alcuni ambienti di rete aziendali e didattici. Per altre informazioni e soluzioni alternative per questo problema, vedere Connettersi all'hub IoT (MQTT).

Ottenere la stringa di connessione dell'hub IoT

In questo articolo viene creato un servizio back-end che aggiunge le proprietà desiderate a un dispositivo gemello e quindi esegue una query nel registro delle identità per trovare tutti i dispositivi con le proprietà segnalate che sono stati aggiornati di conseguenza. Il servizio richiede l’autorizzazione di connessione al servizio per modificare le proprietà desiderate di un dispositivo gemello ed è necessaria l’autorizzazione di lettura del registro di sistema per eseguire query sul registro delle identità. Non esistono criteri di accesso condiviso predefiniti che contengono solo queste due autorizzazioni, quindi è necessario crearne uno.

Per creare criteri di accesso condiviso che concedono le autorizzazioni di connessione al servizio e lettura del registro di sistema e ottenere una stringa di connessione per questo criterio, attenersi alla seguente procedura:

Nel portale di Azure fare clic su Gruppi di risorse. Selezionare il gruppo di risorse in cui si trova l'hub e quindi selezionare l'hub dall'elenco di risorse.
Nel riquadro sinistro dell'hub selezionare Criteri di accesso condiviso.
Dal menu superiore sopra l'elenco di criteri selezionare Aggiungi criteri di accesso condiviso.
Nel riquadro Aggiungi criteri di accesso condiviso a destra immettere un nome descrittivo per i criteri, ad esempio serviceAndRegistryRead. In Autorizzazioni selezionare Lettura del registro di sistema e Connessione al servizio, quindi selezionare Aggiungi.
Selezionare il nuovo criterio dall'elenco dei criteri.
Selezionare l'icona di copia per Stringa di connessione primaria e salvare il valore.

Per altre informazioni sui criteri di accesso condiviso e sulle autorizzazioni dell'hub IoT, vedere Controllo dell'accesso e autorizzazioni.

Creare un'app per dispositivi che aggiorna le proprietà segnalate

In questa sezione si crea un'app console Java che si connette all'hub come myDeviceId e quindi aggiorna le proprietà segnalate del dispositivo gemello per confermare che è connesso tramite una rete cellulare.

Nella cartella iot-java-twin-getstarted creare un progetto Maven denominato simulated-device eseguendo questo comando al prompt dei comandi:

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

Al prompt dei comandi passare alla cartella simulated-device.
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.17.5</version>
</dependency>
```
Nota

È possibile cercare la versione più recente di iot-device-client usando la ricerca di Maven.
Aggiungere la dipendenza seguente al nodo dependencies. Questa dipendenza configura un NOP per l’interfaccia di registrazione Apache SLF4J, che viene usata dall'SDK del client per dispositivi per implementare la registrazione. Questa configurazione è facoltativa, ma se la si omette, è possibile che venga visualizzato un avviso nella console quando si esegue l'app. Per altre informazioni sulla registrazione nell’SDK del client per dispositivi, vedere Registrazione nel file Leggimi Samples for the Azure IoT device SDK for Java (Esempi per l’Azure IoT SDK per dispositivi per Java).
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

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>

Salvare e chiudere il file pom.xml.
Usando un editor di testo, aprire il file simulated-device\src\main\java\com\mycompany\app\App.java.

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;

Aggiungere le variabili a livello di classe seguenti alla classe App . Sostituire {yourdeviceconnectionstring} con la stringa di connessione del dispositivo visualizzata durante la registrazione di un dispositivo nell'hub IoT:
```
private static String connString = "{yourdeviceconnectionstring}";
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.

Aggiungere il metodo seguente alla classe App per stampare le informazioni sugli aggiornamenti del dispositivo gemello:

protected static class DeviceTwinStatusCallBack implements IotHubEventCallback {
    @Override
    public void execute(IotHubStatusCode status, Object context) {
      System.out.println("IoT Hub responded to device twin operation with status " + status.name());
    }
  }

Sostituire il codice nel metodo main con il codice seguente:

Creare un client del dispositivo per comunicare con l'IoT Hub.
Creare un oggetto Device per archiviare le proprietà dei 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);
  }
};

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.closeNow();
  System.out.println("Shutting down...");
}

Alla fine del metodo main aggiungere il codice seguente. Attendere che il tasto Invio consenta all'hub IoT 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();
```

Modificare la firma del metodo main includendo le eccezioni come segue:

public static void main(String[] args) throws URISyntaxException, IOException

Salvare e chiudere il file simulated-device\src\main\java\com\mycompany\app\App.java.
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
```

Creare un'app di servizio che aggiorni le proprietà desiderate e le query dei dispositivi gemelli

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 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.

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

Nella cartella iot-java-twin-getstarted creare un progetto Maven denominato add-tags-query eseguendo questo comando al prompt dei comandi:

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

Al prompt dei comandi passare alla cartella add-tags-query.
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.17.1</version>
  <type>jar</type>
</dependency>
```
Nota

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

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>

Salvare e chiudere il file pom.xml.
Usando un editor di testo, aprire il file add-tags-query\src\main\java\com\mycompany\app\App.java.

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;

Aggiungere le variabili a livello di classe seguenti alla classe App . Sostituire {youriothubconnectionstring} con la stringa di connessione dell'hub IoT copiata in Ottenere la stringa di connessione dell'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";

Aggiornare la firma del metodo main affinché includa la clausola throws:
```
public static void main( String[] args ) throws IOException
```
Sostituire il codice nel metodo main con il codice seguente 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);
```

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());
}

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);

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());
}

Salvare e chiudere il file add-tags-query\src\main\java\com\mycompany\app\App.java
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
```

Eseguire le app

A questo punto è possibile eseguire le app console.

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"
```
È possibile visualizzare i tag plant e region aggiunti al dispositivo gemello. Solo la prima query restituisce il dispositivo, non la seconda.
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"
```
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"
```
Ora che il dispositivo ha inviato la proprietà connectivityType all'hub IoT, la seconda query restituisce il dispositivo.

In questo articolo si apprenderà come:

Metadati del dispositivo aggiunti come tag da un'app back-end
Informazioni sulla connettività del dispositivo segnalate nel dispositivo gemello
Query sulle informazioni sul dispositivo gemello usando il linguaggio di query di hub IoT simile a SQL

Passaggi successivi

Per scoprire come:

Inviare dati di telemetria dai dispositivi, vedere Guida introduttiva: Inviare dati di telemetria da un dispositivo Plug and Play IoT all'hub IoT di Azure
Configurare i dispositivi usando le proprietà desiderate del dispositivo gemello, vedere Esercitazione: Configurare i dispositivi da un servizio back-end
Controllare i dispositivi in modo interattivo, ad esempio accendere una ventola da un'app controllata dall'utente, vedere Guida introduttiva: Controllare un dispositivo connesso a un hub IoT

Condividi tramite