Začínáme s dvojčaty zařízení (Java)

Článek
01/29/2024

Dvojčata zařízení jsou dokumenty JSON s uloženými informacemi o stavu zařízení, včetně metadat, konfigurací a podmínek. IoT Hub zachová dvojče zařízení pro každé zařízení, které se k němu připojí.

Poznámka:

Funkce popsané v tomto článku jsou k dispozici pouze na úrovni Standard služby IoT Hub. Další informace o úrovních Služby IoT Hub úrovně Basic a Standard/Free najdete v tématu Volba správné úrovně IoT Hubu pro vaše řešení.

Dvojčata zařízení použijte k:

Uložte metadata zařízení z back-endu řešení.
Nahlašujte aktuální informace o stavu, jako jsou dostupné možnosti a podmínky, například použitá metoda připojení, z vaší aplikace zařízení.
Synchronizujte stav dlouhotrvajících pracovních postupů, jako jsou aktualizace firmwaru a konfigurace, mezi aplikací zařízení a back-endovou aplikací.
Zadejte dotaz na metadata, konfiguraci nebo stav zařízení.

Dvojčata zařízení jsou navržená pro synchronizaci a dotazování konfigurací a podmínek zařízení. Další informace o dvojčatech zařízení, včetně případů použití dvojčat zařízení, najdete v tématu Principy dvojčat zařízení.

IoT Hubs ukládají dvojčata zařízení, která obsahují následující prvky:

Značky. Metadata zařízení jsou přístupná jenom back-endem řešení.
Požadované vlastnosti. Objekty JSON upravitelné back-endem řešení a pozorovatelné aplikací zařízení.
Ohlášené vlastnosti Objekty JSON upravitelné aplikací zařízení a čitelné back-endem řešení.

Značky a vlastnosti nemohou obsahovat pole, ale mohou obsahovat vnořené objekty.

Následující obrázek znázorňuje organizaci dvojčete zařízení:

Snímek obrazovky s diagramem konceptu dvojčete zařízení

Back-end řešení navíc může dotazovat dvojčata zařízení na základě všech výše uvedených dat. Další informace o dvojčatech zařízení najdete v tématu Principy dvojčat zařízení. Další informace o dotazování najdete v dotazovacím jazyce služby IoT Hub.

V tomto článku se dozvíte, jak:

Pomocí aplikace simulovaného zařízení můžete hlásit svůj kanál připojení jako ohlášenou vlastnost dvojčete zařízení.
Dotazování zařízení z back-endové aplikace pomocí filtrů na značky a vlastnosti, které jste vytvořili dříve.

V tomto článku vytvoříte dvě konzolové aplikace v Javě:

add-tags-query: back-endová aplikace, která přidává značky a dotazy dvojčat zařízení.
simulated-device: aplikace simulovaného zařízení, která se připojuje k centru IoT a hlásí stav připojení.

Poznámka:

Další informace o dostupných nástrojích SDK pro sestavení zařízení i back-endových aplikací najdete v sadách SDK .

Požadavky

IoT Hub. Vytvořte ho pomocí rozhraní příkazového řádku nebo webu Azure Portal.
Zařízení zaregistrované ve službě IoT Hub. Pokud ve službě IoT Hub nemáte zařízení, postupujte podle pokynů v části Registrace zařízení.
Java SE Development Kit 8. Ujistěte se, že v části Dlouhodobá podpora vyberete Javu 8, abyste se dostali ke stažení sady JDK 8.
Maven 3
Ujistěte se, že je v bráně firewall otevřený port 8883. Ukázka zařízení v tomto článku používá protokol MQTT, který komunikuje přes port 8883. Tento port může být blokovaný v některých podnikových a vzdělávacích síťových prostředích. Další informace a způsoby řešení tohoto problému najdete v tématu Připojení ke službě IoT Hub (MQTT).

Získání připojovací řetězec centra IoT

V tomto článku vytvoříte back-endovou službu, která přidá požadované vlastnosti do dvojčete zařízení, a pak se do registru identit dotazuje, aby zjistila všechna zařízení s ohlášenými vlastnostmi, které byly odpovídajícím způsobem aktualizovány. Vaše služba potřebuje oprávnění k připojení služby k úpravě požadovaných vlastností dvojčete zařízení a potřebuje oprávnění ke čtení registru pro dotazování registru identit. Neexistují žádné výchozí zásady sdíleného přístupu, které obsahují pouze tato dvě oprávnění, takže potřebujete vytvořit jednu.

Chcete-li vytvořit zásadu sdíleného přístupu, která uděluje oprávnění ke čtení služby a registru a získat připojovací řetězec pro tuto zásadu, postupujte takto:

Na webu Azure Portal vyberte skupiny prostředků. Vyberte skupinu prostředků, ve které se nachází vaše centrum, a pak vyberte centrum ze seznamu prostředků.
V levém podokně centra vyberte zásady sdíleného přístupu.
V horní nabídce nad seznamem zásad vyberte Přidat zásady přístupu ke sdíleným zásadám.
V podokně Přidat zásady sdíleného přístupu vpravo zadejte popisný název zásady, například serviceAndRegistryRead. V části Oprávnění vyberte Možnost Čtení registru a Připojení ke službě a pak vyberte Přidat.
Ze seznamu zásad vyberte novou zásadu.
Vyberte ikonu kopírování pro primární připojovací řetězec a uložte hodnotu.

Další informace ozásadách

Vytvoření aplikace zařízení, která aktualizuje ohlášené vlastnosti

V této části vytvoříte konzolovou aplikaci Java, která se připojí k vašemu centru jako myDeviceId, a pak aktualizuje ohlášené vlastnosti dvojčete zařízení, abyste potvrdili, že je připojená pomocí mobilní sítě.

Ve složce iot-java-twin-getstarted vytvořte projekt Maven s názvem simulated-device pomocí následujícího příkazu na příkazovém řádku:

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

Na příkazovém řádku přejděte do složky simulated-device .
Pomocí textového editoru otevřete soubor pom.xml ve složce simulovaného zařízení a přidejte do uzlu závislostí následující závislosti. Tato závislost umožňuje používat balíček iot-device-client ve vaší aplikaci ke komunikaci s centrem IoT.
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Poznámka:

Můžete vyhledat nejnovější verzi iot-device-client pomocí vyhledávání Maven.
Do uzlu závislostí přidejte následující závislost. Tato závislost nakonfiguruje NOP pro fasádu protokolování Apache SLF4J , která se používá klientskou sadou SDK zařízení k implementaci protokolování. Tato konfigurace je volitelná, ale pokud ji vynecháte, může se při spuštění aplikace v konzole zobrazit upozornění. Další informace o protokolování v klientské sadě SDK pro zařízení najdete v části Protokolování v ukázkách sady SDK pro zařízení Azure IoT pro soubor Readme v Javě .
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

Za uzel závislostí přidejte následující uzel sestavení. Tato konfigurace dává Mavenu pokyn, aby k sestavení aplikace použil Javu 1.8:

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

Uložte a zavřete soubor pom.xml.
V textovém editoru otevřete soubor simulated-device\src\main\java\com\mycompany\app\App.java .

Do souboru přidejte následující příkazy pro import:

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;

Do třídy App přidejte následující proměnné na úrovni třídy. Nahraďte {yourdeviceconnectionstring} připojovací řetězec zařízení, které jste viděli při registraci zařízení ve službě IoT Hub:
```
private static String connString = "{yourdeviceconnectionstring}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myDeviceId";
```
Tato ukázková aplikace používá při vytváření instance objektu DeviceClient proměnnou protocol.

Do třídy App přidejte následující metodu pro tisk informací o aktualizacích dvojčat:

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

Nahraďte kód v hlavní metodě následujícím kódem:

Vytvořte klienta zařízení pro komunikaci se službou IoT Hub.
Vytvořte objekt zařízení pro uložení vlastností dvojčete zařízení.

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

Do hlavní metody přidejte následující kód, který vytvoří hlášenou vlastnost connectivityType a odešle ji do IoT Hubu:

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

Na konec hlavní metody přidejte následující kód. Čekání na klíč Enter umožňuje, aby služba IoT Hub hlásila stav operací dvojčete zařízení.
```
System.out.println("Press any key to exit...");

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

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

Upravte podpis metody Main tak, aby zahrnoval následující výjimky:

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

Uložte a zavřete soubor simulated-device\src\main\java\com\mycompany\app\App.java .
Sestavte aplikaci simulovaného zařízení a opravte případné chyby. Na příkazovém řádku přejděte do složky simulated-device a spusťte následující příkaz:
```
mvn clean package -DskipTests
```

Vytvoření aplikace služby, která aktualizuje požadované vlastnosti a dotazuje dvojčata

V této části vytvoříte aplikaci v Javě, která přidá metadata umístění jako značku do dvojčete zařízení ve službě IoT Hub přidružené k myDeviceId. Aplikace se dotazuje ioT Hubu na zařízení umístěná v USA a pak se dotazuje zařízení, která hlásí připojení mobilní sítě.

Na vývojovém počítači vytvořte prázdnou složku s názvem iot-java-twin-getstarted.

Ve složce iot-java-twin-getstarted vytvořte projekt Maven s názvem add-tags-query pomocí následujícího příkazu na příkazovém řádku:

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

Na příkazovém řádku přejděte do složky add-tags-query .
Pomocí textového editoru otevřete soubor pom.xml ve složce dotazu add-tags-query a přidejte do uzlu závislostí následující závislost. Tato závislost umožňuje používat balíček iot-service-client ve vaší aplikaci ke komunikaci s centrem IoT:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
Poznámka:

Můžete vyhledat nejnovější verzi iot-service-client pomocí vyhledávání Maven.

Za uzel závislostí přidejte následující uzel sestavení. Tato konfigurace dává Mavenu pokyn, aby k sestavení aplikace použil Javu 1.8.

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

Uložte a zavřete soubor pom.xml.
V textovém editoru otevřete soubor add-tags-query\src\main\java\com\mycompany\app\App.java .

Do souboru přidejte následující příkazy pro import:

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;

Do třídy App přidejte následující proměnné na úrovni třídy. Nahraďte {youriothubconnectionstring} připojovací řetězec IoT Hub, který jste zkopírovali v připojovací řetězec Get the IoT Hub.

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

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

Aktualizujte podpis hlavní metody tak, aby zahrnoval následující throws klauzuli:
```
public static void main( String[] args ) throws IOException
```
Nahraďte kód v hlavní metodě následujícím kódem, který vytvoří Objekty DeviceTwin a DeviceTwinDevice . Objekt DeviceTwin zpracovává komunikaci s centrem IoT. DeviceTwinDevice objekt představuje dvojče zařízení s jeho vlastnostmi a značkami:
```
// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
```

Do hlavní metody přidejte následující try/catch blok:

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

Pokud chcete aktualizovat značky dvojčete zařízení a oblastizařízení ve dvojčeti zařízení, přidejte do try bloku následující kód:

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

Pokud chcete zadávat dotazy na dvojčata zařízení ve službě IoT Hub, přidejte následující kód do try bloku za kód, který jste přidali v předchozím kroku. Kód spouští dva dotazy. Každý dotaz vrátí maximálně 100 zařízení.

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

Uložte a zavřete soubor add-tags-query\src\main\java\com\mycompany\app\App.java
Sestavte aplikaci pro dotazy na doplňky a opravte případné chyby. Na příkazovém řádku přejděte do složky add-tags-query a spusťte následující příkaz:
```
mvn clean package -DskipTests
```

Spouštění aplikací

Teď jste připraveni spustit konzolové aplikace.

Na příkazovém řádku ve složce add-tags-query spusťte následující příkaz a spusťte aplikaci služby add-tags-query :
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Zobrazí se značky zařízení a oblasti přidané do dvojčete zařízení. První dotaz vrátí vaše zařízení, ale druhý ne.
Na příkazovém řádku ve složce simulated-device spusťte následující příkaz a přidejte do dvojčete zařízení hlášenou vlastnost connectivityType :
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Na příkazovém řádku ve složce add-tags-query spusťte následující příkaz a spusťte aplikaci služby add-tags-query podruhé:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Teď, když vaše zařízení odeslalo vlastnost connectivityType do IoT Hubu, vrátí druhý dotaz vaše zařízení.

V tomto článku:

Přidání metadat zařízení jako značek z back-endové aplikace
Nahlášené informace o připojení zařízení ve dvojčeti zařízení
Dotazovali se na informace dvojčete zařízení pomocí dotazovacího jazyka ioT Hubu podobného SQL.

Další kroky

Informace o:

Odeslání telemetrie ze zařízení, viz Rychlý start: Odesílání telemetrie ze zařízení IoT technologie Plug and Play do Azure IoT Hubu
Konfigurace zařízení pomocí požadovaných vlastností dvojčete zařízení, viz Kurz: Konfigurace zařízení z back-endové služby
Interaktivní řízení zařízení, například zapnutí ventilátoru z aplikace řízené uživatelem, najdete v rychlém startu: Řízení zařízení připojeného k centru IoT

Sdílet prostřednictvím