Kom igång med enhetstvillingar (Java)

Artikel
01/29/2024

Enhetstvillingar är JSON-dokument som lagrar information om enhetstillstånd, som metadata, konfigurationer och villkor. IoT Hub bevarar en enhetstvilling för varje enhet som ansluter till den.

Kommentar

De funktioner som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

Använd enhetstvillingar för att:

Lagra enhetsmetadata från lösningens serverdel.
Rapportera aktuell tillståndsinformation, till exempel tillgängliga funktioner och villkor, till exempel den anslutningsmetod som används, från enhetsappen.
Synkronisera tillståndet för långvariga arbetsflöden, till exempel inbyggd programvara och konfigurationsuppdateringar, mellan en enhetsapp och en serverdelsapp.
Fråga efter enhetens metadata, konfiguration eller tillstånd.

Enhetstvillingar är utformade för synkronisering och för att köra frågor mot enhetskonfigurationer och villkor. Mer information om enhetstvillingar, inklusive när du ska använda enhetstvillingar, finns i Förstå enhetstvillingar.

IoT Hubs lagrar enhetstvillingar som innehåller följande element:

Taggar. Enhetsmetadata är endast tillgängliga för lösningens serverdel.
Önskade egenskaper. JSON-objekt som kan ändras av lösningens serverdel och kan observeras av enhetsappen.
Rapporterade egenskaper. JSON-objekt kan ändras av enhetsappen och kan läsas av lösningens serverdel.

Taggar och egenskaper får inte innehålla matriser, men kan innehålla kapslade objekt.

Följande bild visar enhetstvillingorganisationen:

Skärmbild av ett konceptdiagram för enhetstvillingar.

Dessutom kan lösningens serverdel köra frågor mot enhetstvillingar baserat på alla ovanstående data. Mer information om enhetstvillingar finns i Förstå enhetstvillingar. Mer information om frågor finns i IoT Hub-frågespråk.

Den här artikeln visar hur du gör följande:

Använd en simulerad enhetsapp för att rapportera dess anslutningskanal som en rapporterad egenskap på enhetstvillingen.
Fråga enheter från serverdelsappen med filter på taggarna och egenskaperna som skapades tidigare.

I den här artikeln skapar du två Java-konsolappar:

add-tags-query: en serverdelsapp som lägger till taggar och frågar enhetstvillingar.
simulated-device: en simulerad enhetsapp som ansluter till din IoT-hubb och rapporterar dess anslutningsvillkor.

Kommentar

Mer information om de SDK-verktyg som är tillgängliga för att skapa både enhets- och serverdelsappar finns i Azure IoT SDK:er .

Förutsättningar

En IoT-hubb. Skapa en med CLI eller Azure-portalen.
En registrerad enhet. Registrera en i Azure-portalen.
Java SE Development Kit 8. Se till att du väljer Java 8 under Långsiktigt stöd för att komma till nedladdningar för JDK 8.
Maven 3
Kontrollera att port 8883 är öppen i brandväggen. Enhetsexemplet i den här artikeln använder MQTT-protokollet, som kommunicerar via port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att kringgå det här problemet finns i Anslut ing to IoT Hub (MQTT).

Hämta IoT Hub-anslutningssträng

I den här artikeln skapar du en serverdelstjänst som lägger till önskade egenskaper till en enhetstvilling och sedan frågar identitetsregistret för att hitta alla enheter med rapporterade egenskaper som har uppdaterats i enlighet med detta. Tjänsten behöver behörigheten för tjänstanslutning för att ändra önskade egenskaper för en enhetstvilling, och den behöver registerläsningsbehörighet för att köra frågor mot identitetsregistret. Det finns ingen standardprincip för delad åtkomst som bara innehåller dessa två behörigheter, så du måste skapa en.

Följ dessa steg för att skapa en princip för delad åtkomst som beviljar behörigheter för tjänstanslutning och registerläsning och få en anslutningssträng för den här principen:

I Azure-portalen väljer du Resursgrupper. Välj den resursgrupp där hubben finns och välj sedan din hubb i listan över resurser.
I den vänstra rutan i hubben väljer du Principer för delad åtkomst.
Välj Lägg till princip för delad principåtkomst på den översta menyn ovanför listan med principer.
I fönstret Lägg till princip för delad åtkomst till höger anger du ett beskrivande namn för din princip, till exempel serviceAndRegistryRead. Under Behörigheter väljer du Registerläsning och tjänst Anslut och väljer sedan Lägg till.
Välj din nya princip i listan över principer.
Välj kopieringsikonen för den primära anslutningssträng och spara värdet.

Mer information om principer och behörigheter för delad åtkomst i IoT Hub finns i Åtkomstkontroll och behörigheter.

Skapa en enhetsapp som uppdaterar rapporterade egenskaper

I det här avsnittet skapar du en Java-konsolapp som ansluter till din hubb som myDeviceId och uppdaterar sedan enhetstvillingens rapporterade egenskaper för att bekräfta att den är ansluten med ett mobilnät.

I mappen iot-java-twin-getstarted skapar du ett Maven-projekt med namnet simulated-device med följande kommando i kommandotolken:

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

Gå till mappen simulated-device i kommandotolken.
Med hjälp av en textredigerare öppnar du filen pom.xml i mappen simulated-device och lägger till följande beroenden i noden dependencies . Med det här beroendet kan du använda iot-device-client-paketet i din app för att kommunicera med din IoT-hubb.
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Kommentar

Du kan söka efter den senaste versionen av iot-device-client med Maven-sökning.
Lägg till följande beroende till noden beroenden. Det här beroendet konfigurerar en NOP för Apache SLF4J-loggningsfasaden , som används av enhetens klient-SDK för att implementera loggning. Den här konfigurationen är valfri, men om du utelämnar den kan du se en varning i konsolen när du kör appen. Mer information om loggning i enhetsklient-SDK finns i Loggning i exempel för Azure IoT-enhets-SDK för Java-readme-filen .
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

Lägg till följande byggnod efter noden beroenden. Den här konfigurationen instruerar Maven att använda Java 1.8 för att skapa appen:

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

Spara och stäng filen pom.xml.
Öppna filen simulated-device\src\main\java\com\mycompany\app\App.java med hjälp av en textredigerare.

Lägg till följande Import-instruktioner i filen:

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;

Lägg till följande variabler på klassnivå till klassen App. Ersätt {yourdeviceconnectionstring} med enheten anslutningssträng du såg när du registrerade en enhet i IoT Hub:
```
private static String connString = "{yourdeviceconnectionstring}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myDeviceId";
```
Den här exempelappen använder variabeln protocol när den instantierar ett DeviceClient-objekt.

Lägg till följande metod i klassen App för att skriva ut information om tvillinguppdateringar:

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

Ersätt koden i huvudmetoden med följande kod för att:

Skapa en enhetsklient för att kommunicera med IoT Hub.
Skapa ett enhetsobjekt för att lagra egenskaperna för enhetstvillingen.

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

Lägg till följande kod i huvudmetoden för att skapa en connectivityType-rapporterad egenskap och skicka den till 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...");
}

Lägg till följande kod i slutet av huvudmetoden . Om du väntar på returnyckeln kan IoT Hub rapportera status för enhetstvillingåtgärderna.

System.out.println("Press any key to exit...");

Scanner scanner = new Scanner(System.in);
scanner.nextLine();

dataCollector.clean();
client.close();

Ändra signaturen för main-metoden och ta med undantagen som visas nedan:

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

Spara och stäng filen simulated-device\src\main\java\com\mycompany\app\App.java .
Skapa appen simulated-device och korrigera eventuella fel. I kommandotolken navigerar du till mappen simulated-device och kör följande kommando:
```
mvn clean package -DskipTests
```

Skapa en tjänstapp som uppdaterar önskade egenskaper och frågar tvillingar

I det här avsnittet skapar du en Java-app som lägger till platsmetadata som en tagg till enhetstvillingen i IoT Hub som är associerad med myDeviceId. Appen frågar IoT Hub efter enheter som finns i USA och frågar sedan enheter som rapporterar en mobilnätverksanslutning.

På utvecklingsdatorn skapar du en tom mapp med namnet iot-java-twin-getstarted.

I mappen iot-java-twin-getstarted skapar du ett Maven-projekt med namnet add-tags-query med följande kommando i kommandotolken:

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

Gå till mappen add-tags-query i kommandotolken.
Med hjälp av en textredigerare öppnar du filen pom.xml i mappen add-tags-query och lägger till följande beroende till noden beroenden. Med det här beroendet kan du använda iot-service-client-paketet i din app för att kommunicera med din IoT-hubb:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
Kommentar

Du kan söka efter den senaste versionen av iot-service-client med Maven-sökning.

Lägg till följande byggnod efter noden beroenden. Den här konfigurationen instruerar Maven att använda Java 1.8 för att skapa appen.

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

Spara och stäng filen pom.xml.
Öppna filen add-tags-query\src\main\java\com\mycompany\app\App.java med hjälp av en textredigerare.

Lägg till följande Import-instruktioner i filen:

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;

Lägg till följande variabler på klassnivå till klassen App. Ersätt {youriothubconnectionstring} med IoT-hubben anslutningssträng du kopierade i Hämta IoT Hub-anslutningssträng.

public static final String iotHubConnectionString = "{youriothubconnectionstring}";
public static final String deviceId = "myDeviceId";

public static final String region = "US";
public static final String plant = "Redmond43";

Uppdatera huvudmetodsignaturen så att den innehåller följande throws sats:
```
public static void main( String[] args ) throws IOException
```
Ersätt koden i huvudmetoden med följande kod för att skapa objekten DeviceTwin och DeviceTwinDevice . DeviceTwin-objektet hanterar kommunikationen med din IoT-hubb. DeviceTwinDevice-objektet representerar enhetstvillingen med dess egenskaper och taggar:
```
// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
```

Lägg till följande try/catch block i huvudmetoden :

try {
  // Code goes here
} catch (IotHubException e) {
  System.out.println(e.getMessage());
} catch (IOException e) {
  System.out.println(e.getMessage());
}

Om du vill uppdatera taggarna för region - och enhetstvillingar i enhetstvillingen lägger du till följande kod i try blocket:

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

Om du vill fråga enhetstvillingarna i IoT Hub lägger du till följande kod try i blocket efter koden du lade till i föregående steg. Koden kör två frågor. Varje fråga returnerar högst 100 enheter.

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

Spara och stäng filen add-tags-query\src\main\java\com\mycompany\app\App.java
Skapa appen add-tags-query och korrigera eventuella fel. Gå till mappen add-tags-query i kommandotolken och kör följande kommando:
```
mvn clean package -DskipTests
```

Köra apparna

Nu är du redo att köra konsolapparna.

Kör följande kommando i en kommandotolk i mappen add-tags-query för att köra tjänstappen add-tags-query :
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Du kan se de växt- och regiontaggar som har lagts till i enhetstvillingen. Den första frågan returnerar enheten, men den andra gör det inte.
I en kommandotolk i mappen simulated-device kör du följande kommando för att lägga till egenskapen connectivityType-rapporterad till enhetstvillingen:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Kör följande kommando i en kommandotolk i mappen add-tags-query för att köra tjänstappen add-tags-query en andra gång:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Nu när enheten har skickat egenskapen connectivityType till IoT Hub returnerar den andra frågan enheten.

Den här artikeln innehåller följande avsnitt:

Enhetsmetadata har lagts till som taggar från en serverdelsapp
Rapporterad anslutningsinformation för enheter i enhetstvillingen
Efterfrågade information om enhetstvillingen med hjälp av SQL-liknande IoT Hub-frågespråk

Nästa steg

Om du vill ta reda på hur du:

Skicka telemetri från enheter finns i Snabbstart: Skicka telemetri från en IoT Plug and Play-enhet till Azure IoT Hub
Konfigurera enheter med hjälp av enhetstvillingens önskade egenskaper finns i Självstudie: Konfigurera dina enheter från en serverdelstjänst
Kontrollera enheter interaktivt, till exempel aktivera en fläkt från en användarkontrollerad app, se Snabbstart: Kontrollera en enhet som är ansluten till en IoT-hubb

Share via