Mulai menggunakan perangkat kembar (.NET)

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.

Dalam artikel ini, Anda membuat dua aplikasi konsol .NET:

AddTagsAndQuery: aplikasi back-end yang menambahkan tag dan kueri perangkat kembar.
ReportConnectivity: aplikasi perangkat yang disimulasikan yang tersambung ke hub IoT 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

Visual Studio.
Hub IoT. Membuat satu dengan CLI atau portal Azure.
Perangkat yang terdaftar. Daftarkan perangkat di portal Azure.
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 .NET yang tersambung ke hub Anda sebagai myDeviceId, kemudian memperbarui properti yang dilaporkan perangkat kembarnya untuk mengonfirmasi bahwa itu tersambung menggunakan jaringan seluler.

Buka Visual Studio, lalu pilih Buat proyek baru.
Pilih Aplikasi Konsol (.NET Framework), lalu pilih Berikutnya.
Di Konfigurasikan proyek baru Anda, beri nama proyek sebagai ReportConnectivity, lalu pilih Berikutnya.
Pada Penjelajah Solusi, klik kanan proyek ReportConnectivity, dan pilih Kelola Paket NuGet.
Pertahankan versi default .NET Framework, lalu pilih Buat untuk membuat proyek.
Pilih Telusuri dan cari serta pilih Microsoft.Azure.Devices.Client. Pilih Instal.

Langkah ini mengunduh, memasang, dan menambahkan referensi ke Paket NuGet SDK perangkat Azure IoT dan dependensinya.

Tambahkan pernyataan berikut using ke bagian atas file Program.cs:

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

Tambahkan bidang berikut ke kelas Program. Ganti {device connection string} dengan string koneksi perangkat yang Anda lihat saat mendaftarkan perangkat di IoT Hub:

static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;

Tambahkan metode berikut ke kelas Program:

public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

Objek Client mengekspos semua metode yang Anda butuhkan untuk berinteraksi dengan perangkat ganda dari perangkat. Kode yang ditunjukkan di atas menginisialisasi objek Klient, lalu mengambil perangkat kembar untuk myDeviceId.

Tambahkan metode berikut ke kelas Program:

public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

Kode di atas memperbarui properti myDeviceId yang dilaporkan dengan informasi konektivitas.

Terakhir, tambahkan baris berikut ke metode Main:

try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Di Penjelajah Solusi, klik kanan pada solusi dan pilih Atur Proyek StartUp....
Pilih Properti Umum>Proyek Startup, lalu pilih Proyek startup multi. Untuk ReportConnectivity, pilih Mulai sebagai Tindakan. Pilih OK untuk menyimpan perubahan Anda.
Jalankan aplikasi ini dengan mengklik kanan proyek ReportConnectivity dan memilih Debug, lalu Mulai instans baru. Anda akan melihat aplikasi mendapatkan informasi kembar, lalu mengirim konektivitas sebagai properti yang dilaporkan.

Setelah perangkat melaporkan informasi konektivitasnya, perangkat akan muncul di kedua kueri.
Klik kanan proyek AddTagsAndQuery dan pilih Debug>Mulai instans baru untuk menjalankan kueri lagi. Kali ini myDeviceId akan muncul di kedua hasil kueri.

Membuat aplikasi layanan yang memperbarui properti dan kueri yang diinginkan kembar

Di bagian ini, Anda membuat aplikasi konsol Node.js, menggunakan C# yang menambahkan metadata lokasi ke perangkat kembar 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 Visual Studio, pilih File >> Proyek Baru. Di Buat proyek baru, pilih Aplikasi Konsol (.NET Framework), lalu pilih Berikutnya.
Di Konfigurasikan proyek baru Anda, beri nama proyek AddTagsAndQuery, lalu pilih Berikutnya.
Terima versi default .NET Framework, lalu pilih Buat untuk membuat proyek.
Pada Penjelajah Solusi, klik kanan proyek AddTagsAndQuerydan pilih Kelola Paket NuGet.
Pilih Telusuri dan cari serta pilih Microsoft.Azure.Devices. Pilih Instal.

Langkah ini mengunduh, memasang, dan menambahkan referensi ke paket NuGet SDK layanan Azure IoT dan dependensinya.
Tambahkan pernyataan berikut using ke bagian atas file Program.cs:
```
using Microsoft.Azure.Devices;
```
Tambahkan bidang berikut ke kelas Program. Ganti {iot hub connection string} dengan string koneksi IoT Hub yang Anda salin di Mendapatkan string koneksi IoT Hub.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```

Tambahkan metode berikut ke kelas Program:

public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

    var query = registryManager.CreateQuery(
      "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
    var twinsInRedmond43 = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43: {0}", 
      string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

    query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
    var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
      string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
}

Kelas RegistryManager memaparkan semua metode yang diperlukan untuk berinteraksi dengan perangkat kembar dari layanan tersebut. Kode sebelumnya pertama-tama menginisialisasi objek registryManager, kemudian mengambil perangkat kembar untuk myDeviceId, dan akhirnya memperbarui tag dengan informasi lokasi yang diinginkan.

Setelah memperbarui, kode sebelumnya menjalankan dua kueri: yang pertama hanya memilih perangkat kembar dari perangkat yang terletak di pabrik Redmond43, dan yang kedua menyempurnakan kueri untuk memilih hanya perangkat yang juga tersambung melalui jaringan seluler.

Kode sebelumnya, saat membuat objek kueri, menentukan jumlah maksimum dokumen yang dikembalikan. Objek kueri berisi properti boolean HasMoreResults yang dapat Anda gunakan untuk memanggil GetNextAsTwinAsync berikutnya beberapa kali untuk mengambil semua hasil. Metode yang disebut GetNextAsJson tersedia untuk hasil yang bukan merupakan perangkat kembar, misalnya, hasil kueri agregasi.

Terakhir, tambahkan baris berikut ke metode Main:

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Jalankan aplikasi ini dengan mengeklik kanan pada proyek AddTagsAndQuery dan memilih Debug, diikuti oleh Mulai instans baru. Anda akan melihat satu perangkat dalam hasil untuk kueri yang meminta semua perangkat yang terletak di Redmond43 dan tidak ada untuk kueri yang membatasi hasil ke perangkat yang menggunakan jaringan seluler.

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, lihat Mulai Cepat: Mengirim telemetri dari perangkat IoT Plug and Play ke Azure IoT Hub.
Mengonfigurasi perangkat menggunakan properti yang diinginkan dari perangkat kembar, lihat Tutorial: Mengonfigurasi perangkat Anda dari layanan back-end.
Mengontrol perangkat secara interaktif, seperti menyalakan kipas dari aplikasi yang dikontrol pengguna, lihat Mulai Cepat: Mengontrol perangkat yang tersambung ke hub IoT.

Mulai menggunakan perangkat kembar (.NET)

Prasyarat

Mendapatkan string koneksi IoT hub

Membuat aplikasi perangkat yang memperbarui properti yang dilaporkan

Membuat aplikasi layanan yang memperbarui properti dan kueri yang diinginkan kembar

Langkah berikutnya

Sumber Daya Tambahan: