Mulai menggunakan perangkat ganda (Python)

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

AddTagsAndQuery.py: aplikasi back-end yang menambahkan tag dan kueri perangkat kembar.
ReportConnectivity.py: aplikasi perangkat yang disimulasikan yang tersambung ke hub IoT Anda serta melaporkan kondisi konektivitasnya.

Catatan

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

Prasyarat

Akun Azure aktif. (Jika Anda tidak memiliki akun, Anda dapat membuat akun gratis hanya dalam beberapa menit.)
Hub IoT. Membuat satu dengan CLI atau portal Azure.
Perangkat yang terdaftar di hub IoT Anda. Jika Anda tidak memiliki perangkat di hub IoT Anda, ikuti langkah-langkah di Mendaftarkan perangkat.
Python versi 3.7 atau yang lebih baru disarankan. Pastikan untuk menggunakan penginstalan 32-bit atau 64-bit sesuai kebutuhan penyiapan Anda. Saat diminta selama instalasi, pastikan untuk menambahkan Python ke variabel lingkungan khusus platform Anda.
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 layanan yang memperbarui properti dan kueri yang diinginkan kembar

Di bagian ini, Anda membuat aplikasi konsol Python yang menambahkan metadata lokasi ke perangkat ganda yang terkait dengan {Device ID} Anda. Aplikasi ini pertama kali meminta IoT Hub untuk perangkat yang terletak di AS, kemudian untuk perangkat yang melaporkan koneksi jaringan seluler.

Di direktori kerja Anda, buka perintah dan instal Azure IoT Hub Service SDK for Python.
```
pip install azure-iot-hub
```
Menggunakan editor teks, buat file AddTagsAndQuery.py baru.

Tambahkan kode berikut untuk mengimpor modul yang diperlukan dari SDK layanan:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

Tambahkan kode berikut. Ganti [IoTHub Connection String] dengan string koneksi IoT Hub yang Anda salin di Mendapatkan string koneksi IoT Hub. Ganti [Device Id] dengan ID perangkat (nama) dari perangkat terdaftar Anda di hub IoT.
```
IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"
```

Tambahkan kode berikut ke file AddTagsAndQuery.py:

def iothub_service_sample_run():
    try:
        iothub_registry_manager = IoTHubRegistryManager(IOTHUB_CONNECTION_STRING)

        new_tags = {
                'location' : {
                    'region' : 'US',
                    'plant' : 'Redmond43'
                }
            }

        twin = iothub_registry_manager.get_twin(DEVICE_ID)
        twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
        twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

        # Add a delay to account for any latency before executing the query
        sleep(1)

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

        print()

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

    except Exception as ex:
        print("Unexpected error {0}".format(ex))
        return
    except KeyboardInterrupt:
        print("IoT Hub Device Twin service sample stopped")

Objek IoTHubRegistryManager memaparkan semua metode yang diperlukan untuk berinteraksi dengan perangkat ganda dari layanan. Kode pertama menginisialisasi objek IoTHubRegistryManager, kemudian memperbarui perangkat ganda untuk DEVICE_ID, dan akhirnya menjalankan dua kueri. Yang pertama hanya memilih perangkat ganda perangkat yang terletak di pabrik Redmond43, dan yang kedua menyempurnakan kueri untuk memilih hanya perangkat yang juga terhubung melalui jaringan seluler.

Tambahkan kode berikut di akhir AddTagsAndQuery.py untuk menerapkan fungsi iothub_service_sample_run:

if __name__ == '__main__':
    print("Starting the Python IoT Hub Device Twin service sample...")
    print()

    iothub_service_sample_run()

Jalankan aplikasi dengan:
```
python AddTagsAndQuery.py
```
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. Di bagian berikutnya, Anda akan membuat aplikasi perangkat yang akan menggunakan jaringan seluler dan Anda akan menjalankan ulang kueri ini untuk melihat perubahannya.

Membuat aplikasi perangkat yang memperbarui properti yang dilaporkan

Di bagian ini, Anda membuat aplikasi konsol Python yang tersambung ke hub Anda sebagai {Device ID} Anda, kemudian memperbarui properti yang dilaporkan perangkat kembarnya untuk mengonfirmasi bahwa itu tersambung menggunakan jaringan seluler.

Dari perintah di direktori kerja Anda, instal Azure IoT Hub Device SDK for Python:
```
pip install azure-iot-device
```
Menggunakan editor teks, buat file ReportConnectivity.py baru.
Tambahkan kode berikut untuk mengimpor modul yang diperlukan dari SDK perangkat:
```
import time
from azure.iot.device import IoTHubModuleClient
```
Tambahkan kode berikut. Ganti nilai tempat penampung [IoTHub Device Connection String] dengan string koneksi perangkat yang Anda lihat ketika mendaftarkan perangkat di IoT Hub:
```
CONNECTION_STRING = "[IoTHub Device Connection String]"
```

Tambahkan kode berikut ke file ReportConnectivity.py untuk membuat instans klien dan menerapkan fungsionalitas kembar perangkat:

def create_client():
    # Instantiate client
    client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

    try:
        # Set handlers on the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler
    except:
        # Clean up in the event of failure
        client.shutdown()

    return client

Tambahkan kode berikut di akhir ReportConnectivity.py untuk menjalankan aplikasi:

def main():
    print ( "Starting the Python IoT Hub Device Twin device sample..." )
    client = create_client()
    print ( "IoTHubModuleClient waiting for commands, press Ctrl-C to exit" )

    try:
        # Update reported properties with cellular information
        print ( "Sending data as reported property..." )
        reported_patch = {"connectivity": "cellular"}
        client.patch_twin_reported_properties(reported_patch)
        print ( "Reported properties updated" )

        # Wait for program exit
        while True:
            time.sleep(1000000)
    except KeyboardInterrupt:
        print ("IoT Hub Device Twin device sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Jalankan aplikasi perangkat:
```
python ReportConnectivity.py
```
Anda akan melihat konfirmasi properti yang dilaporkan kembar perangkat diperbarui.
Setelah perangkat melaporkan informasi konektivitasnya, hal ini akan muncul di kedua kueri. Kembali dan jalankan kueri lagi:
```
python AddTagsAndQuery.py
```
Kali ini, {DEVICE ID} Anda akan muncul di kedua hasil kueri.

Di aplikasi perangkat, Anda akan melihat konfirmasi bahwa patch ganda properti yang diinginkan yang dikirim oleh aplikasi layanan diterima.

Dalam artikel ini, Anda:

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

Langkah berikutnya

Untuk mempelajari cara:

Mengirim telemetri dari perangkat, lihat artikel Mulai Cepat: Mengirim telemetri dari perangkat IoT Plug and Play pada 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.

Bagikan melalui