Mulai menggunakan perangkat ganda (Java)

Artikel
03/17/2023

Kembaran perangkat adalah dokumen JSON yang menyimpan informasi status perangkat termasuk metadata, konfigurasi, dan kondisi. IoT Hub mempertahankan kembaran perangkat untuk setiap perangkat yang tersambung dengannya.

Catatan

Fitur yang dijelaskan dalam artikel ini hanya tersedia di tingkat standar IoT Hub. Untuk informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat IoT Hub yang tepat untuk solusi Anda.

Gunakan perangkat ganda untuk:

Menyimpan metadata perangkat dari back-end solusi Anda.
Melaporkan informasi status saat ini seperti kemampuan dan kondisi yang tersedia, misalnya, metode konektivitas yang digunakan, dari aplikasi perangkat Anda.
Menyinkronkan status alur kerja yang berjalan lama, seperti pembaruan firmware dan konfigurasi, antara aplikasi perangkat dan aplikasi back-end.
Mengkueri metadata, konfigurasi, atau status perangkat Anda.

Device twins dirancang untuk sinkronisasi serta untuk mengueri konfigurasi dan kondisi perangkat. Untuk informasi selengkapnya tentang perangkat kembar, termasuk kapan harus menggunakan perangkat kembar, lihat Memahami perangkat kembar.

Hub IoT menyimpan kembar perangkat, yang berisi elemen-elemen berikut:

Tag. Metadata perangkat hanya dapat diakses oleh back-end solusi.
Properti yang diinginkan. Objek JSON dapat dimodifikasi oleh back-end solusi dan dapat diamati oleh aplikasi perangkat.
Properti yang dilaporkan. Objek JSON dapat dimodifikasi oleh aplikasi perangkat dan dapat dibaca oleh back-end solusi.

Tag dan properti tidak boleh berisi array, tetapi dapat berisi objek berlapis.

Ilustrasi berikut ini memperlihatkan organisasi perangkat kembar:

Cuplikan layar diagram konsep ganda perangkat.

Selain itu, back-end solusi dapat mengueri device twins berdasarkan semua data di atas. Untuk informasi device twins selengkapnya, lihat Mulai dengan perangkat kembar. Untuk informasi selengkapnya tentang sintaksis kueri, lihat Bahasa kueri IoT Hub.

Artikel ini menunjukkan cara:

Gunakan aplikasi perangkat yang disimulasikan untuk melaporkan saluran konektivitasnya sebagai properti yang dilaporkan pada perangkat kembar.
Perangkat kueri dari aplikasi back-end Anda menggunakan filter pada tag dan properti yang telah sebelumnya dibuat.

Di artikel ini, Anda membuat dua aplikasi konsol Java:

add-tags-query: aplikasi back-end Java yang menambahkan tag serta kueri perangkat ganda.
simulated-device: aplikasi perangkat Java yang tersambung ke IoT Hub Anda serta melaporkan kondisi konektivitasnya.

Catatan

Lihat Azure IoT SDK untuk informasi selengkapnya tentang alat SDK yang tersedia untuk membangun aplikasi perangkat dan back-end.

Prasyarat

Hub IoT. Membuat satu dengan CLI atau portal Azure.
Perangkat yang terdaftar. Daftarkan perangkat di portal Azure.
Java SE Development Kit 8. Pastikan Anda memilih Java 8 pada Dukungan jangka panjang untuk mengunduh JDK 8.
Maven 3
Pastikan port 8883 terbuka di firewall Anda. Sampel perangkat dalam artikel ini menggunakan protokol MQTT, yang berkomunikasi melalui port 8883. Port ini dapat diblokir di beberapa lingkungan jaringan perusahaan dan pendidikan. Untuk informasi selengkapnya dan cara mengatasi masalah ini, lihat Menyambungkan ke Azure IoT Hub (MQTT).

Mendapatkan string koneksi IoT hub

Dalam artikel ini, Anda membuat layanan backend yang menambahkan properti yang diinginkan ke kembar perangkat, lalu meminta registri identitas untuk menemukan semua perangkat dengan properti yang dilaporkan yang telah diperbarui dengan sesuai. Layanan Anda memerlukan izin sambungkan layanan untuk memodifikasi properti yang diinginkan dari kembar perangkat, dan memerlukan izin baca registri untuk mengkueri registri identitas. Tidak ada kebijakan akses bersama default yang hanya berisi dua izin ini, jadi Anda perlu membuatnya.

Untuk membuat kebijakan akses bersama yang memberikan izin sambungkan layanan dan baca registri dan untuk mendapatkan string koneksi untuk kebijakan ini, ikuti langkah-langkah berikut:

Di portal Azure, pilih Grup sumber daya. Pilih grup sumber daya tempat hub Anda berada, lalu pilih hub Anda dari daftar sumber daya.
Di panel sisi kiri hub Anda, pilih Kebijakan akses bersama.
Dari menu atas di atas daftar kebijakan, pilih Tambahkan kebijakan akses kebijakan bersama.
Di panel Tambahkan kebijakan akses bersama di sebelah kanan, masukkan nama deskriptif untuk kebijakan Anda, seperti serviceAndRegistryRead. Di bawah Izin, pilih Baca Registri dan Sambungkan layanan, lalu pilih Tambahkan.
Pilih kebijakan baru Anda dari daftar kebijakan.
Pilih ikon salin untuk String sambungan primer dan simpan nilainya.

Untuk mengetahui informasi selengkapnya tentang kebijakan dan izin akses bersama IoT Hub, lihat Kontrol akses dan izin.

Membuat aplikasi perangkat yang memperbarui properti yang dilaporkan

Di bagian ini, Anda membuat aplikasi konsol Java yang tersambung ke hub Anda sebagai myDeviceId Anda, kemudian memperbarui properti yang dilaporkan perangkat gandanya agar berisi informasi bahwa terhubung menggunakan jaringan seluler.

Di folder iot-java-twin-getstarted, buat proyek Maven bernama simulated-device menggunakan perintah berikut pada perintah Anda:

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

Pada perintah Anda, navigasikan ke folder simulated-device.
Menggunakan editor teks, buka file pom.xml di folder perangkat yang disimulasi dan tambahkan dependensi berikut ke simpul dependensi. Dependensi ini memungkinkan Anda menggunakan paket iot-device-client di aplikasi Anda untuk berkomunikasi dengan IoT Hub Anda.
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Catatan

Anda dapat memeriksa versi terbaru iot-device-client menggunakan penelusuran Maven.
Tambahkan dependensi berikut ke simpul dependencies. Dependensi ini mengonfigurasi NOP untuk fasad pengelogan Apache SLF4J, yang digunakan oleh SDK klien perangkat untuk menerapkan pengelogan. Konfigurasi ini bersifat opsional, tetapi, jika Anda menghilangkannya, Anda mungkin melihat peringatan di konsol saat menjalankan aplikasi. Untuk informasi selengkapnya tentang masuk di SDK klien perangkat, lihat Pengelogan di file readme Sampel untuk SDK perangkat Azure IoT untuk Java.
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

Tambahkan simpul build berikut setelah simpul dependensi. Konfigurasi ini menginstruksikan Maven untuk menggunakan Java 1.8 untuk membangun aplikasi:

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

Simpan dan tutup file pom.xml.
Menggunakan editor teks, buka file simulated-device\src\main\java\com\mycompany\app\App.java.

Tambahkan pernyataan impor berikut ke file:

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;

Tambahkan variabel tingkat kelas berikut ke kelas Aplikasi. Ganti {yourdeviceconnectionstring} dengan string koneksi perangkat yang Anda lihat saat mendaftarkan perangkat di IoT Hub:
```
private static String connString = "{yourdeviceconnectionstring}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myDeviceId";
```
Aplikasi sampel ini menggunakan variabel protokol saat membuat instans objek DeviceClient.

Tambahkan metode berikut ke kelas Aplikasi untuk mencetak informasi tentang pembaruan ganda:

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

Ganti kode pada metode utama dengan kode berikut ke:

Buat klien perangkat untuk berkomunikasi dengan IoT Hub.
Buat objek Perangkat untuk menyimpan properti perangkat ganda.

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

Tambahkan kode berikut ke metode utama untuk membuat properti yang dilaporkan connectivityType dan mengirimkannya ke 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...");
}

Tambahkan kode berikut ke akhir metode utama. Menunggu tombol Enter memberikan waktu bagi IoT Hub untuk melaporkan status operasi perangkat ganda.

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

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

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

Ubah tanda tangan metode utama untuk menyertakan pengecualian sebagai berikut:

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

Simpan dan tutup file simulated-device\src\main\java\com\mycompany\app\App.java.
Bangun aplikasi simulated-device dan perbaiki kesalahan apa pun. Pada perintah Anda, navigasikan ke folder simulated-device dan jalankan perintah berikut:
```
mvn clean package -DskipTests
```

Membuat aplikasi layanan yang memperbarui properti dan kueri yang diinginkan kembar

Di bagian ini, Anda membuat aplikasi Java yang menambahkan metadata lokasi sebagai tag ke perangkat ganda di IoT Hub yang terkait dengan myDeviceId. Aplikasi ini pertama kali meminta IoT Hub untuk perangkat yang terletak di AS, kemudian untuk perangkat yang melaporkan koneksi jaringan seluler.

Di mesin pengembangan Anda, buat folder kosong bernama iot-java-twin-getstarted.

Di folder iot-java-twin-getstarted, buat proyek Maven bernama add-tags-query menggunakan perintah berikut pada perintah Anda:

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

Pada perintah Anda, navigasikan ke folder add-tags-query.
Menggunakan editor teks, buka file pom.xml di folder add-tags-query dan tambahkan dependensi berikut ke simpul dependensi. Dependensi ini memungkinkan Anda menggunakan paket iot-service-client di aplikasi Anda untuk berkomunikasi dengan IoT hub Anda:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
Catatan

Anda dapat memeriksa versi terbaru iot-service-client menggunakan pencarian Maven.

Tambahkan simpul build berikut setelah simpul dependensi. Konfigurasi ini menginstruksikan Maven untuk menggunakan Java 1.8 untuk membangun aplikasi.

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

Simpan dan tutup file pom.xml.
Menggunakan editor teks, buka file add-tags-query\src\main\java\com\mycompany\app\App.java.

Tambahkan pernyataan impor berikut ke file:

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;

Tambahkan variabel tingkat kelas berikut ke kelas Aplikasi. Ganti {youriothubconnectionstring} dengan string koneksi IoT Hub yang Anda salin di Mendapatkan string koneksi 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";

Perbarui tanda tangan metode utama untuk menyertakan klausul throws berikut:
```
public static void main( String[] args ) throws IOException
```
Ganti kode dalam metode utama dengan kode berikut untuk membuat objek DeviceTwin dan DeviceTwinDevice. Objek DeviceTwin menangani komunikasi dengan IoT Hub Anda. Objek DeviceTwinDevice mewakili perangkat ganda dengan properti dan tagnya:
```
// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
```

Tambahkan blok try/catch berikut ke metode utama:

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

Untuk memperbarui tag perangkat ganda wilayah dan pabrik di perangkat ganda Anda, tambahkan kode berikut di blok 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);

Untuk menanyakan perangkat ganda di IoT Hub, tambahkan kode berikut ke blok try setelah kode yang Anda tambahkan di langkah sebelumnya. Kode menjalankan dua kueri. Setiap kueri mengembalikan maksimum 100 perangkat.

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

Simpan dan tutup file add-tags-query\src\main\java\com\mycompany\app\App.java
Bangun aplikasi add-tags-query dan perbaiki kesalahan apa pun. Pada perintah Anda, navigasikan ke folder add-tags-query dan jalankan perintah berikut:
```
mvn clean package -DskipTests
```

Menjalankan aplikasi

Anda sekarang siap untuk menjalankan aplikasi konsol.

Pada perintah di folder add-tags-query, jalankan perintah berikut untuk menjalankan aplikasi layanan add-tags-query:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Anda dapat melihat tag pabrik dan wilayah yang ditambahkan ke perangkat ganda. Kueri pertama mengembalikan perangkat Anda, tetapi kueri yang kedua tidak.
Pada perintah di folder simulated-device, jalankan perintah berikut untuk menambahkan properti yang dilaporkan connectivityType ke perangkat ganda:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Pada perintah di folder add-tags-query, jalankan perintah berikut untuk menjalankan aplikasi layanan add-tags-query untuk kedua kalinya:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Sekarang perangkat Anda telah mengirim properti connectivityType ke IoT Hub, kueri kedua mengembalikan perangkat Anda.

Dalam artikel ini, Anda:

Menambahkan metadata perangkat sebagai tag dari aplikasi back-end
Informasi konektivitas perangkat yang dilaporkan pada perangkat kembar
Mengkueri informasi perangkat kembar menggunakan bahasa kueri IoT Hub yang mirip SQL

Langkah berikutnya

Untuk mempelajari cara:

Mengirim telemetri dari perangkat, harap lihat Mulai Cepat: Mengirim telemetri dari perangkat IoT Plug and Play pada Azure IoT Hub
Mengonfigurasi perangkat menggunakan properti yang diinginkan kembar perangkat, harap lihat Tutorial: Mengonfigurasi perangkat Anda dari layanan back-end
Mengontrol perangkat secara interaktif seperti menyalakan kipas dari aplikasi yang dikontrol pengguna, harap lihat Mulai Cepat: Mengontrol perangkat yang tersambung ke hub IoT