Aan de slag met apparaatdubbels (Java)

Artikel
01/29/2024

Apparaatdubbels zijn JSON-documenten waarin statusinformatie van een apparaat zijn opgeslagen, zoals metagegevens, configuraties en voorwaarden. IoT Hub houdt een apparaatdubbel vast voor elk apparaat dat er verbinding mee maakt.

Notitie

De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.

Apparaatdubbels gebruiken om:

Sla metagegevens van apparaten op vanuit de back-end van uw oplossing.
Rapporteer actuele statusinformatie, zoals beschikbare mogelijkheden en voorwaarden, bijvoorbeeld de gebruikte connectiviteitsmethode vanuit uw apparaat-app.
Synchroniseer de status van langlopende werkstromen, zoals firmware- en configuratie-updates, tussen een apparaat-app en een back-end-app.
Voer een query uit op de metagegevens, configuratie of status van uw apparaat.

Apparaatdubbels zijn ontworpen voor synchronisatie en voor het opvragen van apparaatconfiguraties en -voorwaarden. Zie Apparaatdubbels begrijpen voor meer informatie over apparaatdubbels, inclusief wanneer u apparaatdubbels gebruikt.

IoT Hubs slaan apparaatdubbels op, die de volgende elementen bevatten:

Tags. Metagegevens van apparaten die alleen toegankelijk zijn voor de back-end van de oplossing.
Gewenste eigenschappen. JSON-objecten kunnen worden gewijzigd door de back-end van de oplossing en waarneembaar door de apparaat-app.
Gerapporteerde eigenschappen. JSON-objecten kunnen worden gewijzigd door de apparaat-app en kunnen worden gelezen door de back-end van de oplossing.

Tags en eigenschappen kunnen geen matrices bevatten, maar kunnen geneste objecten bevatten.

In de volgende afbeelding ziet u de organisatie van apparaatdubbels:

Schermopname van een conceptdiagram van een apparaatdubbel.

Daarnaast kan de back-end van de oplossing een query uitvoeren op apparaatdubbels op basis van alle bovenstaande gegevens. Zie Apparaatdubbels begrijpen voor meer informatie over apparaatdubbels. Zie de Querytaal van IoT Hub voor meer informatie over het uitvoeren van query's.

Dit artikel laat het volgende zien:

Gebruik een gesimuleerde apparaat-app om het connectiviteitskanaal te rapporteren als een gerapporteerde eigenschap op de apparaatdubbel.
Query's uitvoeren op apparaten vanuit uw back-end-app met behulp van filters op de tags en eigenschappen die u eerder hebt gemaakt.

In dit artikel maakt u twee Java-console-apps:

add-tags-query: een back-end-app waarmee tags en query's op apparaatdubbels worden toegevoegd.
simulated-device: een gesimuleerde apparaat-app die verbinding maakt met uw IoT-hub en de connectiviteitsvoorwaarde rapporteert.

Notitie

Zie Azure IoT SDK's voor meer informatie over de SDK-hulpprogramma's die beschikbaar zijn voor het bouwen van zowel apparaat- als back-end-apps.

Vereisten

Een IoT-hub. Maak er een met de CLI of Azure Portal.
Een geregistreerd apparaat. Registreer er een in Azure Portal.
Java SE Development Kit 8. Zorg ervoor dat u Java 8 selecteert onder Langetermijnondersteuning om naar downloads voor JDK 8 te gaan.
Maven 3
Zorg ervoor dat de poort 8883 is geopend in uw firewall. Het apparaatvoorbeeld in dit artikel maakt gebruik van het MQTT-protocol, dat via poort 8883 communiceert. Deze poort is in sommige netwerkomgevingen van bedrijven en onderwijsinstellingen mogelijk geblokkeerd. Zie Verbinding maken met IoT Hub (MQTT) voor meer informatie en manieren om dit probleem te omzeilen.

De IoT Hub-verbindingsreeks ophalen

In dit artikel maakt u een back-endservice die gewenste eigenschappen toevoegt aan een apparaatdubbel en vervolgens het identiteitsregister opvraagt om alle apparaten met gerapporteerde eigenschappen te vinden dienovereenkomstig zijn bijgewerkt. Uw service heeft de serviceverbindingsmachtiging nodig om de gewenste eigenschappen van een apparaatdubbel te wijzigen en heeft de leesmachtiging voor het register nodig om een query uit te voeren op het identiteitsregister. Er is geen standaardbeleid voor gedeelde toegang dat alleen deze twee machtigingen bevat, dus u moet er een maken.

Voer de volgende stappen uit om een gedeeld toegangsbeleid te maken dat serviceverbindings- en registertoegangsmachtigingen verleent en een verbindingsreeks voor dit beleid op te halen:

Selecteer resourcegroepen in de Azure-portal. Selecteer de resourcegroep waar uw hub zich bevindt en selecteer vervolgens uw hub in de lijst met resources.
Selecteer in het linkerdeelvenster van uw hub beleid voor gedeelde toegang.
Selecteer in het bovenste menu boven de lijst met beleidsregels de optie Beleid voor gedeelde beleidsregels toevoegen.
Voer in het deelvenster Gedeeld toegangsbeleid aan de rechterkant een beschrijvende naam in voor uw beleid, zoals serviceAndRegistryRead. Selecteer onder Machtigingen de optie Lezen en Verbinding maken register en Service en selecteer vervolgens Toevoegen.
Selecteer uw nieuwe beleid in de lijst met beleidsregels.
Selecteer het kopieerpictogram voor de primaire verbindingsreeks en sla de waarde op.

Zie Toegangsbeheer en machtigingen voor meer informatie over beleid en machtigingen voor gedeelde toegang van IoT Hub.

Een apparaat-app maken waarmee gerapporteerde eigenschappen worden bijgewerkt

In deze sectie maakt u een Java-console-app die verbinding maakt met uw hub als myDeviceId en werkt u vervolgens de gerapporteerde eigenschappen van de apparaatdubbel bij om te bevestigen dat deze is verbonden met een mobiel netwerk.

Maak in de map iot-java-twin-getstarted een Maven-project met de naam simulated-device met behulp van de volgende opdracht bij de opdrachtprompt:

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

Navigeer in de opdrachtprompt naar de map simulated-device .
Open met behulp van een teksteditor het pom.xml-bestand in de map simulated-device en voeg de volgende afhankelijkheden toe aan het knooppunt afhankelijkheden. Met deze afhankelijkheid kunt u het iot-device-clientpakket in uw app gebruiken om te communiceren met uw IoT-hub.
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Notitie

U vindt de meest recente versie van iot-device-client met Maven zoeken.
Voeg de volgende afhankelijkheid toe aan het knooppunt afhankelijkheden . Deze afhankelijkheid configureert een NOP voor de Apache SLF4J-logboekregistratiefaçade , die wordt gebruikt door de client-SDK van het apparaat om logboekregistratie te implementeren. Deze configuratie is optioneel, maar als u deze weglaat, ziet u mogelijk een waarschuwing in de console wanneer u de app uitvoert. Zie Logboekregistratie in de voorbeelden voor de Azure IoT-apparaat-SDK voor Java-leesmij-bestand voor meer informatie over logboekregistratie in de SDK voor de apparaatclient.
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

Voeg het volgende build-knooppunt toe na het knooppunt afhankelijkheden . Met deze configuratie verwijst Maven naar het gebruik van Java 1.8 om de app te bouwen:

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

Sla het bestand pom.xml op en sluit het.
Open met behulp van een teksteditor het bestand simulated-device\src\main\java\com\mycompany\app\App.java .

Voeg de volgende importinstructies toe aan het bestand:

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;

Voeg de volgende variabelen op klasseniveau toe aan de App-klasse. Vervang {yourdeviceconnectionstring} door het apparaat verbindingsreeks u hebt gezien toen u een apparaat hebt geregistreerd in de IoT Hub:
```
private static String connString = "{yourdeviceconnectionstring}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myDeviceId";
```
Deze voorbeeld-app gebruikt de protocol-variabele bij het maken van een DeviceClient-object.

Voeg de volgende methode toe aan de App-klasse om informatie over updates van dubbels af te drukken:

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

Vervang de code in de hoofdmethode door de volgende code om:

Maak een apparaatclient om te communiceren met IoT Hub.
Maak een apparaatobject om de eigenschappen van de apparaatdubbel op te slaan.

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

Voeg de volgende code toe aan de hoofdmethode om een door connectivityType gerapporteerde eigenschap te maken en deze naar IoT Hub te verzenden:

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

Voeg de volgende code toe aan het einde van de hoofdmethode . Als u wacht op de Enter-sleutel , kan IoT Hub de status van de apparaatdubbelbewerkingen rapporteren.
```
System.out.println("Press any key to exit...");

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

dataCollector.clean();
client.close();
```
Wijzig de handtekening van de main-methode om de uitzonderingen als volgt op te nemen:
```
public static void main(String[] args) throws URISyntaxException, IOException
```
Sla het bestand simulated-device\src\main\java\com\mycompany\app\App.java op en sluit het.
Bouw de app simulated-device en corrigeer eventuele fouten. Navigeer in de opdrachtprompt naar de map simulated-device en voer de volgende opdracht uit:
```
mvn clean package -DskipTests
```

Een service-app maken waarmee de gewenste eigenschappen worden bijgewerkt en query's worden uitgevoerd op dubbels

In deze sectie maakt u een Java-app die locatiemetagegevens toevoegt als een tag aan de apparaatdubbel in IoT Hub die is gekoppeld aan myDeviceId. De app vraagt IoT Hub op voor apparaten die zich in de VS bevinden en vraagt vervolgens apparaten op die een mobiele netwerkverbinding rapporteren.

Maak op uw ontwikkelcomputer een lege map met de naam iot-java-twin-getstarted.

Maak in de map iot-java-twin-getstarted een Maven-project met de naam add-tags-query met behulp van de volgende opdracht bij de opdrachtprompt:

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

Navigeer in de opdrachtprompt naar de map add-tags-query .
Open met behulp van een teksteditor het pom.xml bestand in de map add-tags-query en voeg de volgende afhankelijkheid toe aan het knooppunt afhankelijkheden . Met deze afhankelijkheid kunt u het iot-service-clientpakket in uw app gebruiken om te communiceren met uw IoT-hub:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
Notitie

U vindt de meest recente versie van iot-service-client met Maven zoeken.

Voeg het volgende build-knooppunt toe na het knooppunt afhankelijkheden . Met deze configuratie verwijst Maven naar het gebruik van Java 1.8 om de app te bouwen.

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

Sla het bestand pom.xml op en sluit het.
Open met behulp van een teksteditor het bestand add-tags-query\src\main\java\com\mycompany\app\App.java .

Voeg de volgende importinstructies toe aan het bestand:

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;

Voeg de volgende variabelen op klasseniveau toe aan de App-klasse. Vervang {youriothubconnectionstring} door de IoT-hub verbindingsreeks die u hebt gekopieerd in De IoT-hub ophalen verbindingsreeks.

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

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

Werk de handtekening van de hoofdmethode bij om de volgende throws component op te nemen:
```
public static void main( String[] args ) throws IOException
```
Vervang de code in de hoofdmethode door de volgende code om de objecten DeviceTwin en DeviceTwinDevice te maken. Het DeviceTwin-object verwerkt de communicatie met uw IoT-hub. Het object DeviceTwinDevice vertegenwoordigt de apparaatdubbel met de eigenschappen en tags:
```
// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
```

Voeg het volgende try/catch blok toe aan de hoofdmethode :

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

Als u de tags voor de regio en plantapparaatdubbel in uw apparaatdubbel wilt bijwerken, voegt u de volgende code toe in het try blok:

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

Als u een query wilt uitvoeren op de apparaatdubbels in IoT Hub, voegt u de volgende code toe aan het try blok na de code die u in de vorige stap hebt toegevoegd. De code voert twee query's uit. Elke query retourneert maximaal 100 apparaten.

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

Het bestand add-tags-query\src\main\java\com\mycompany\app\App.java opslaan en sluiten
Bouw de app add-tags-query en corrigeer eventuele fouten. Navigeer in de opdrachtprompt naar de map add-tags-query en voer de volgende opdracht uit:
```
mvn clean package -DskipTests
```

De apps uitvoeren

U bent nu klaar om de console-apps uit te voeren.

Voer bij een opdrachtprompt in de map add-tags-query de volgende opdracht uit om de service-app add-tags-query uit te voeren:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
U kunt de plant - en regiolabels zien die zijn toegevoegd aan de apparaatdubbel. De eerste query retourneert uw apparaat, maar de tweede niet.
Voer bij een opdrachtprompt in de map simulated-device de volgende opdracht uit om de gerapporteerde eigenschap connectivityType toe te voegen aan de apparaatdubbel:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Voer bij een opdrachtprompt in de map add-tags-query de volgende opdracht uit om de app add-tags-query service een tweede keer uit te voeren:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Nu uw apparaat de eigenschap connectivityType naar IoT Hub heeft verzonden, retourneert de tweede query uw apparaat.

In dit artikel leert u het volgende:

Metagegevens van apparaten toegevoegd als tags uit een back-end-app
Gerapporteerde apparaatverbindingsgegevens in de apparaatdubbel
Query's uitgevoerd op de gegevens van de apparaatdubbel, met sql-achtige IoT Hub-querytaal

Volgende stappen

Zie voor meer informatie over:

Telemetrie verzenden vanaf apparaten, zie quickstart: Telemetrie verzenden van een IoT-Plug en Play-apparaat naar Azure IoT Hub
Configureer apparaten met behulp van de gewenste eigenschappen van een apparaatdubbel. Zie Zelfstudie: Uw apparaten configureren vanuit een back-endservice
Apparaten interactief beheren, zoals het inschakelen van een ventilator vanuit een door de gebruiker beheerde app, zie Quickstart: Een apparaat beheren dat is verbonden met een IoT-hub

Share via