Memulai perangkat ganda (Node.js)

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 Node.js:

AddTagsAndQuery.js: aplikasi back-end yang menambahkan tag dan kueri perangkat ganda.
TwinSimulatedDevice.js: 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

Untuk menyelesaikan artikel ini, Anda perlu:

IoT Hub di langganan Azure Anda. Jika belum memiliki hub, Anda dapat mengikuti langkah-langkah di Membuat IoT hub.
Perangkat yang terdaftar di hub IoT Anda. Jika Anda tidak memiliki perangkat di hub IoT Anda, ikuti langkah-langkah di Mendaftarkan perangkat.
Node.js versi 10.0.x atau yang lebih baru.
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 Node.js yang tersambung ke hub Anda sebagai myDeviceId Anda, kemudian memperbarui properti yang dilaporkan perangkat gandanya untuk berisi informasi bahwa terhubung melalui jaringan seluler.

Buat folder kosong baru yang bernama reportconnectivity. Di folder reportconnectivity, buat file package.json menggunakan perintah berikut pada perintah Anda. Parameter --yes menerima semua pengaturan default.
```
npm init --yes
```
Pada perintah Anda di folder reportconnectivity, jalankan perintah berikut untuk memasang paket azure-iot-device dan azure-iot-device-mqtt:
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
Menggunakan editor teks, buat file ReportConnectivity.js di folder reportconnectivity.

Tambahkan kode berikut ke file ReportConnectivity.js berikut. Ganti {device connection string} dengan string koneksi perangkat yang Anda lihat saat mendaftarkan perangkat di IoT Hub:

    'use strict';
    var Client = require('azure-iot-device').Client;
    var Protocol = require('azure-iot-device-mqtt').Mqtt;

    var connectionString = '{device connection string}';
    var client = Client.fromConnectionString(connectionString, Protocol);

    client.open(function(err) {
    if (err) {
        console.error('could not open IotHub client');
    }  else {
        console.log('client opened');

        client.getTwin(function(err, twin) {
        if (err) {
            console.error('could not get twin');
        } else {
            var patch = {
                connectivity: {
                    type: 'cellular'
                }
            };

            twin.properties.reported.update(patch, function(err) {
                if (err) {
                    console.error('could not update twin');
                } else {
                    console.log('twin state reported');
                    process.exit();
                }
            });
        }
        });
    }
    });

Objek Client mengekspos semua metode yang Anda butuhkan untuk berinteraksi dengan perangkat ganda dari perangkat. Kode sebelumnya, setelah menginisialisasi objek Client, mengambil perangkat ganda untuk myDeviceId dan memperbarui properti yang dilaporkan dengan informasi konektivitas.

Menjalankan aplikasi perangkat
```
    node ReportConnectivity.js
```
Anda akan melihat pesan twin state reported.
Setelah perangkat melaporkan informasi konektivitasnya, hal ini akan muncul di kedua kueri. Kembali ke folder addtagsandqueryapp dan jalankan kueri lagi:
```
    node AddTagsAndQuery.js
```
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 yang menambahkan metadata lokasi ke perangkat ganda yang terkait dengan myDeviceId Anda. Aplikasi ini pertama kali meminta IoT Hub untuk perangkat yang terletak di AS, kemudian untuk perangkat yang melaporkan koneksi jaringan seluler.

Buat folder kosong baru yang disebut addtagsandqueryapp. Di folder addtagsandqueryapp, buat file package.json menggunakan perintah berikut pada perintah Anda. Parameter --yes menerima semua pengaturan default.
```
npm init --yes
```
Pada perintah Anda di folder addtagsandqueryapp, jalankan perintah berikut untuk memasang paket azure-iothub:
```
npm install azure-iothub --save
```
Menggunakan editor teks, buat file AddTagsAndQuery.js baru di folder addtagsandqueryapp.

Tambahkan kode berikut ke file AddTagsAndQuery.js. Ganti {iot hub connection string} dengan string koneksi IoT Hub yang Anda salin di Mendapatkan string koneksi IoT Hub.

     'use strict';
     var iothub = require('azure-iothub');
     var connectionString = '{iot hub connection string}';
     var registry = iothub.Registry.fromConnectionString(connectionString);

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Objek Registry memaparkan semua metode yang diperlukan untuk berinteraksi dengan perangkat ganda dari layanan. Kode sebelumnya pertama-tama menginisialisasi objek Registry, kemudian mengambil perangkat ganda untuk myDeviceId, dan akhirnya memperbarui tag dengan informasi lokasi yang diinginkan.

Setelah memperbarui tag, ia memanggil fungsi queryTwins.

Tambahkan kode berikut di akhir AddTagsAndQuery.js untuk menerapkan fungsi queryTwins:

     var queryTwins = function() {
         var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
         query.nextAsTwin(function(err, results) {
             if (err) {
                 console.error('Failed to fetch the results: ' + err.message);
             } else {
                 console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
             }
         });

         query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
         query.nextAsTwin(function(err, results) {
             if (err) {
                 console.error('Failed to fetch the results: ' + err.message);
             } else {
                 console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
             }
         });
     };

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

Saat kode membuat objek kueri, kode menentukan jumlah maksimum dokumen yang dikembalikan dalam parameter kedua. Objek kueri berisi properti boolean hasMoreResults yang dapat Anda gunakan untuk memanggil nextAsTwin berikutnya beberapa kali untuk mengambil semua hasil. Metode yang disebut next tersedia untuk hasil yang bukan merupakan perangkat ganda, misalnya, hasil kueri agregasi.

Jalankan aplikasi dengan:
```
    node AddTagsAndQuery.js
```
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, 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

Bagikan melalui