Mulai menggunakan perangkat ganda (Python)

Device twins 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 mengetahui informasi selengkapnya tentang IoT Hub tingkat standar dan dasar, lihat Cara memilih tingkat IoT Hub yang tepat.

Gunakan device twins 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.

  • Mengueri metadata, konfigurasi, atau status perangkat Anda.

Device twins dirancang untuk sinkronisasi serta untuk mengueri konfigurasi dan kondisi perangkat. Informasi lebih lanjut tentang waktu penggunaan device twins dapat ditemukan di Memahami perangkat kembar.

Device twins disimpan di IoT hub dan memuat 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 objek dapat ditumpuk.

Ilustrasi berikut ini memperlihatkan organisasi perangkat kembar:

Gambar perangkat kembar menampilkan fungsi

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.

Tutorial ini akan menunjukkan cara untuk:

  • Membuat aplikasi back-end yang menambahkan tag ke device twins, dan aplikasi perangkat yang disimulasikan yang melaporkan saluran konektivitasnya sebagai properti yang dilaporkan padadevice twins.

  • Perangkat kueri dari aplikasi back-end Anda menggunakan filter pada tag dan properti yang telah sebelumnya dibuat.

Di akhir tutorial ini, Anda akan memiliki dua aplikasi konsol Python:

  • AddTagsAndQuery.py, aplikasi back-end Python, yang menambahkan tag dan kueri perangkat ganda.

  • ReportConnectivity.py, aplikasi Python, yang menyimulasikan perangkat yang terhubung ke IoT Hub Anda dengan identitas perangkat yang dibuat sebelumnya, dan melaporkan kondisi konektivitasnya.

Catatan

IoT Hub memiliki dukungan SDK untuk banyak platform perangkat dan bahasa (termasuk C, Java, dan Python)melalui SDK perangkat Azure IoT. Untuk petunjuk tentang cara menggunakan Python untuk menghubungkan perangkat Anda ke kode tutorial ini, dan umumnya ke Azure IoT Hub, lihat SDK Phyton Azure IoT.

Prasyarat

  • Pastikan port 8883 terbuka di firewall Anda. Sampel perangkat dalam artikel ini menggunakan protokol MQTT, yang berkomunikasi melalui port 8883. Port ini mungkin diblokir di beberapa lingkungan jaringan perusahaan dan pendidikan. Untuk mengetahui informasi selengkapnya dan cara mengatasi masalah ini, lihat Menghubungkan ke IoT Hub (MQTT).

Membuat hub IoT

Bagian ini menjelaskan cara membuat hub IoT menggunakan portal Microsoft Azure.

  1. Masuk ke portal Microsoft Azure.

  2. Dari beranda Azure, pilih tombol + Buat sumber daya, lalu masukkan IoT Hub di bidang Telusuri Marketplace.

  3. Pilih IoT Hub dari hasil pencarian, lalu pilih Buat.

  4. Pada tab Dasar, lengkapi bidang sebagai berikut:

    • Langganan: Pilih langganan yang akan digunakan untuk hub Anda.

    • Grup Sumber Daya: Pilih grup sumber daya atau buat grup baru. Untuk membuat grup baru, pilih Buat baru dan isi nama yang ingin Anda gunakan. Untuk menggunakan grup sumber daya yang sudah ada, pilih grup sumber daya tersebut. Untuk informasi selengkapnya, lihat Mengelola grup sumber daya Azure Resource Manager.

    • Wilayah: Pilih wilayah lokasi hub yang Anda inginkan. Pilih lokasi yang terdekat dengan Anda. Beberapa fitur, seperti aliran perangkat IoT Hub, hanya tersedia di wilayah tertentu. Untuk fitur terbatas ini, Anda harus memilih salah satu wilayah yang didukung.

    • Nama Hub IoT: Masukkan nama untuk hub Anda. Nama ini tidak boleh sama secara global, dengan panjang antara 3 dan 50 karakter alfanumerik. Nama ini juga dapat menyertakan karakter tanda hubung ('-').

    Penting

    Karena hub IoT akan dapat ditemukan secara umum sebagai titik akhir DNS, pastikan untuk menghindari memasukkan informasi sensitif atau identitas pribadi saat menamainya.

    Buat hub menggunakan portal Microsoft Azure.

  5. Pilih Berikutnya: Jaringan untuk melanjutkan membuat hub Anda.

    Pilih titik akhir yang dapat digunakan perangkat untuk tersambung ke IoT Hub Anda. Anda bisa memilih pengaturan default Titik akhir publik (semua jaringan) , atau pilih Titik akhir publik (rentang IP yang dipilih) , atau Titik akhir privat. Terima pengaturan default untuk contoh ini.

    Pilih titik akhir yang dapat tersambung.

  6. Pilih Berikutnya: Manajemen untuk terus membuat hub Anda.

    Atur ukuran dan skala untuk hub baru menggunakan portal Microsoft Azure.

    Anda dapat menerima pengaturan default di sini. Jika diinginkan, Anda dapat memodifikasi salah satu bidang berikut:

    • Harga dan tingkatan skala: Tingkatan yang Anda pilih. Anda dapat memilih dari beberapa tingkatan, tergantung pada seberapa banyak fitur yang Anda inginkan dan seberapa banyak pesan yang Anda kirim per hari melalui solusi Anda. Tingkatan gratis dimaksudkan untuk pengujian dan evaluasi. Ini memungkinkan 500 perangkat untuk tersambung ke hub dan hingga 8.000 pesan per hari. Setiap langganan Azure dapat membuat satu hub IoT dalam tingkatan gratis.

      Jika Anda bekerja melalui mulai cepat untuk streaming perangkat IoT Hub, pilih tingkatan gratis.

    • Unit IoT Hub: Jumlah pesan yang diizinkan per unit per hari tergantung pada tingkatan harga hub Anda. Misalnya, jika Anda ingin hub mendukung 700.000 pesan masuk, Anda memilih dua unit tingkatan S1. Untuk detail tentang opsi tingkatan lainnya, lihat Memilih tingkat Hub IoT yang tepat.

    • Pertahanan untuk IoT: Nyalakan ini untuk menambahkan lapisan perlindungan ancaman ekstra untuk IoT dan perangkat Anda. Opsi ini tidak tersedia untuk hub di tingkatan gratis. Untuk informasi selengkapnya tentang fitur ini, lihat Azure Defender for IoT.

    • Pengaturan Tingkat Lanjut > Partisi perangkat-ke-cloud: Properti ini menghubungkan pesan perangkat ke cloud dengan jumlah pembaca pesan secara bersamaan. Sebagian besar hub hanya membutuhkan empat partisi.

  7. Pilih Berikutnya: Tag untuk melanjutkan ke layar berikutnya.

    Tag adalah pasangan nama/nilai. Anda dapat menetapkan tag yang sama ke beberapa sumber daya dan grup sumber daya untuk mengkategorikan sumber daya dan mengonsolidasikan penagihan. Dalam dokumen ini, Anda tidak akan menambahkan tag apa pun. Untuk informasi selengkapnya, lihat Menggunakan tag untuk mengatur sumber daya Azure Anda.

    Tetapkan tag untuk hub menggunakan portal Microsoft Azure.

  8. Pilih Berikutnya: Tinjau + buat untuk meninjau pilihan Anda. Anda melihat sesuatu yang mirip dengan layar ini, tetapi dengan nilai yang Anda pilih saat membuat hub.

    Tinjau informasi untuk membuat hub baru.

  9. Pilih Buat untuk memulai penyebaran hub baru Anda. Penyebaran Anda akan berlangsung beberapa menit saat hub sedang dibuat. Setelah penyebaran selesai, klik Buka sumber daya untuk membuka hub baru.

Mendaftarkan perangkat baru di hub IoT

Di bagian ini, Anda membuat identitas perangkat di registri identitas di hub IoT Anda. Perangkat tidak dapat tersambung ke hub kecuali memiliki entri dalam registri identitas. Untuk mengetahui informasi selengkapnya, lihat Panduan pengembang IoT Hub.

  1. Di menu navigasi hub IoT Anda, buka Perangkat IoT, lalu pilih Baru untuk menambahkan perangkat di hub IoT Anda.

    Membuat identitas perangkat di portal

  2. Pada Buat perangkat, berikan nama untuk perangkat baru Anda, seperti myDeviceId, dan pilih Simpan. Tindakan ini membuat identitas perangkat untuk hub IoT Anda. Biarkan Buat kunci otomatis dicentang agar kunci utama dan sekunder akan dibuat secara otomatis.

    Menambahkan perangkat baru

    Penting

    ID perangkat mungkin terlihat dalam log yang dikumpulkan untuk dukungan dan pemecahan masalah pelanggan, jadi pastikan untuk menghindari informasi sensitif saat menamainya.

  3. Setelah perangkat dibuat, buka perangkat dari daftar di panel perangkat IoT. Salin String Koneksi Utama. String koneksi ini digunakan oleh kode perangkat untuk berkomunikasi dengan hub.

    Secara default, kunci dan string koneksi disembunyikan karena merupakan informasi sensitif. Jika Anda mengklik ikon mata, mereka akan terungkap seperti yang ditunjukkan pada gambar di bawah ini. Tidak perlu mengungkapkannya untuk menyalinnya dengan tombol salin.

    String koneksi perangkat

Catatan

Registri identitas IoT Hub hanya menyimpan identitas perangkat dan modul untuk memungkinkan akses aman ke hub IoT. Ini menyimpan ID perangkat dan kunci untuk digunakan sebagai info masuk keamanan, dan bendera yang diaktifkan/dinonaktifkan yang dapat Anda gunakan untuk menonaktifkan akses untuk perangkat individual. Jika aplikasi Anda perlu menyimpan metadata khusus perangkat lainnya, aplikasi tersebut harus menggunakan penyimpanan khusus aplikasi. Untuk mengetahui informasi selengkapnya, lihat Panduan pengembang IoT Hub.

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:

  1. Di portal Microsoft Azure, pilih Grup sumber daya. Pilih grup sumber daya tempat hub Anda berada, lalu pilih hub Anda dari daftar sumber daya.

  2. Di panel sisi kiri hub Anda, pilih Kebijakan akses bersama.

  3. Dari menu atas di atas daftar kebijakan, pilih Tambahkan.

  4. Di panel Tambahkan kebijakan akses bersama, masukkan nama deskriptif untuk kebijakan Anda; misalnya serviceAndRegistryRead. Di bagian Izin, pilih Penulisan registri dan Sambungkan layanan, lalu pilih Buat.

    Tampilkan cara menambahkan kebijakan akses bersama baru

  5. Pilih kebijakan baru Anda dari daftar kebijakan.

  6. Pada Kunci akses bersama, pilih ikon salin untuk String koneksi -- kunci primer dan simpan nilainya.

    Tampilkan cara mengambil string koneksi

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

Membuat aplikasi layanan

Di bagian ini, Anda membuat aplikasi konsol Python yang menambahkan metadata lokasi ke perangkat ganda yang terkait dengan {Device ID} Anda. Kemudian meminta perangkat ganda yang disimpan di IoT Hub yang memilih perangkat yang terletak di Redmond, lalu yang melaporkan koneksi seluler.

  1. Di direktori kerja Anda, buka perintah dan instal Azure IoT Hub Service SDK for Python.

    pip install azure-iot-hub
    
  2. Menggunakan editor teks, buat file AddTagsAndQuery.py baru.

  3. 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
    
  4. 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 yang Anda daftarkan di Daftarkan perangkat baru di hub IoT.

    IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
    DEVICE_ID = "[Device Id]"
    
  5. 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.

  6. 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()
    
  7. 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.

    kueri pertama menampilkan semua perangkat di Redmond

Di bagian berikutnya, Anda membuat aplikasi perangkat yang melaporkan informasi konektivitas dan mengubah hasil kueri di bagian sebelumnya.

Membuat aplikasi perangkat

Di bagian ini, Anda membuat aplikasi konsol Python yang terhubung ke hub Anda sebagai {Device ID} Anda, kemudian memperbarui properti yang dilaporkan perangkat gandanya untuk berisi informasi bahwa terhubung menggunakan jaringan seluler.

  1. Dari perintah di direktori kerja Anda, instal Azure IoT Hub Device SDK for Python:

    pip install azure-iot-device
    
  2. Menggunakan editor teks, buat file ReportConnectivity.py baru.

  3. Tambahkan kode berikut untuk mengimpor modul yang diperlukan dari SDK perangkat:

    import time
    from azure.iot.device import IoTHubModuleClient
    
  4. Tambahkan kode berikut. Ganti nilai tempat penampung [IoTHub Device Connection String] dengan string koneksi perangkat yang Anda salin di Mendaftarkan perangkat baru di IoT Hub.

    CONNECTION_STRING = "[IoTHub Device Connection String]"
    
  5. Tambahkan kode berikut ke file ReportConnectivity.py untuk menginstansiasi klien dan menerapkan fungsionalitas twin 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
    
  6. 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()
    
  7. Jalankan aplikasi perangkat:

    python ReportConnectivity.py
    

    Anda akan melihat konfirmasi properti yang dilaporkan kembar perangkat diperbarui.

    memperbarui properti yang dilaporkan dari aplikasi perangkat

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

    kueri kedua pada aplikasi layanan

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

    menerima properti yang diinginkan di aplikasi perangkat

Langkah berikutnya

Dalam tutorial ini, Anda mengonfigurasi IoT hub baru di portal Microsoft Azure, lalu membuat identitas perangkat di registri identitas IoT hub. Anda menambahkan metadata perangkat sebagai tag dari aplikasi back-end, dan menulis aplikasi perangkat yang disimulasikan untuk melaporkan informasi konektivitas perangkat di perangkat ganda. Anda juga mempelajari cara mengkueri informasi ini menggunakan registri.

Gunakan sumber daya berikut untuk mempelajari cara: