Mulai menggunakan identitas modul IoT Hub dan kembar identitas modul

• Memerlukan Visual Studio

Gambaran Umum

Artikel ini menjelaskan cara menggunakan Azure IoT SDK untuk .NET untuk membuat kode aplikasi layanan perangkat dan backend untuk kembar identitas modul.

Membuat aplikasi perangkat

Bagian ini menjelaskan cara menggunakan kode aplikasi perangkat untuk:

• Mengambil kembaran identitas modul dan memeriksa properti yang dilaporkan
• Memperbarui properti kembar identitas modul yang dilaporkan
• Membuat handler panggilan balik pembaruan properti yang diinginkan modul

Paket NuGet perangkat yang diperlukan

Aplikasi klien perangkat yang ditulis dalam C# memerlukan paket NuGet Microsoft.Azure.Devices.Client .

Tambahkan pernyataan ini using untuk menggunakan pustaka perangkat.

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

Menyambungkan ke perangkat

Kelas ModuleClient mengekspos semua metode yang diperlukan untuk berinteraksi dengan kembar identitas modul dari perangkat.

Sambungkan ke perangkat menggunakan metode CreateFromConnectionString dengan identitas modul string koneksi.

Panggilan CreateFromConnectionString tanpa parameter transportasi tersambung menggunakan transportasi AMQP default.

Contoh ini terhubung ke perangkat menggunakan transportasi AMQP default.

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

Mengambil kembaran identitas modul dan memeriksa properti

Panggil GetTwinAsync untuk mengambil properti kembar identitas modul saat ini ke dalam objek Kembar .

Contoh ini mengambil dan menampilkan properti kembar identitas modul dalam format JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

Memperbarui properti yang dilaporkan kembar identitas modul

Untuk memperbarui properti yang dilaporkan kembar:

1. Membuat objek TwinCollection untuk pembaruan properti yang dilaporkan
2. Memperbarui satu atau beberapa properti yang dilaporkan dalam TwinCollection objek
3. Gunakan UpdateReportedPropertiesAsync untuk mendorong perubahan properti yang dilaporkan ke layanan hub IoT

Contohnya:

try
{
  Console.WriteLine("Sending sample start time as reported property");
  TwinCollection reportedProperties = new TwinCollection();
  reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
  await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Membuat handler panggilan balik pembaruan properti yang diinginkan

Teruskan nama metode penangan panggilan balik ke SetDesiredPropertyUpdateCallbackAsync untuk membuat penanganan panggilan balik pembaruan properti yang diinginkan yang dijalankan saat properti yang diinginkan diubah dalam kembar identitas modul.

Misalnya, panggilan ini menyiapkan sistem untuk memberi tahu metode bernama OnDesiredPropertyChangedAsync setiap kali properti modul yang diinginkan diubah.

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Properti kembar identitas modul diteruskan ke metode panggilan balik sebagai TwinCollection dan dapat diperiksa sebagai KeyValuePair struktur.

Contoh ini menerima pembaruan properti yang TwinCollectiondiinginkan sebagai , lalu mengulang dan mencetak KeyValuePair pembaruan koleksi. Setelah mengulangi KeyValuePair koleksi, kode memanggil UpdateReportedPropertiesAsync untuk memperbarui properti yang DateTimeLastDesiredPropertyChangeReceived dilaporkan untuk selalu memperbarui waktu terakhir.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Sampel modul SDK

Azure IoT SDK untuk .NET menyediakan sampel kerja aplikasi perangkat yang menangani tugas kembar identitas modul. Untuk informasi selengkapnya, lihat:

• TwinSample
• Pengujian Klien Perangkat

Membuat aplikasi backend

Bagian ini menjelaskan cara membaca dan memperbarui bidang identitas modul.

Kelas RegistryManager mengekspos semua metode yang diperlukan untuk membuat aplikasi backend untuk berinteraksi dengan kembar identitas modul dari layanan.

Paket NuGet layanan yang diperlukan

Aplikasi layanan backend memerlukan paket NuGet Microsoft.Azure.Devices .

Tambahkan pernyataan ini using untuk menggunakan pustaka layanan.

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

Menyambungkan ke Azure IoT Hub

Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:

• Kebijakan akses bersama
• Microsoft Entra

Menyambungkan menggunakan kebijakan akses bersama

Sambungkan aplikasi backend ke hub IoT menggunakan CreateFromConnectionString.

Metode yang UpdateModuleAsync digunakan di bagian ini memerlukan izin kebijakan akses bersama Service Connect untuk menambahkan properti yang diinginkan ke modul. Sebagai parameter untuk CreateFromConnectionString, berikan kebijakan akses bersama string koneksi yang menyertakan izin Service Connect. Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

Contohnya:

static RegistryManager registryManager;
static string connectionString = "{IoT hub shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Menyambungkan menggunakan Microsoft Entra

Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.

Mengonfigurasi aplikasi Microsoft Entra

Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:

• Rahasia Klien
• Sertifikat
• Kredensial identitas federasi

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, Kontributor Kembar IoT Hub diperlukan untuk mengaktifkan akses baca dan tulis ke perangkat IoT Hub dan modul kembar. Untuk informasi selengkapnya, lihat Mengelola akses ke IoT Hub dengan menggunakan penetapan peran Azure RBAC.

Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Mengautentikasi menggunakan DefaultAzureCredential

Cara term mudah untuk menggunakan Microsoft Entra untuk mengautentikasi aplikasi backend adalah dengan menggunakan DefaultAzureCredential, tetapi disarankan untuk menggunakan metode yang berbeda di lingkungan produksi termasuk yang spesifik TokenCredential atau diurai.ChainedTokenCredential Untuk kesederhanaan, bagian ini menjelaskan autentikasi menggunakan DefaultAzureCredential dan Rahasia klien. Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential, lihat Panduan penggunaan untuk DefaultAzureCredential.

DefaultAzureCredential mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.

Microsoft Entra memerlukan paket NuGet ini dan pernyataan terkait using :

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan ID penyewa ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh DefaultAzureCredential untuk mengautentikasi aplikasi. Hasil autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke metode koneksi IoT Hub.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

TokenCredential yang dihasilkan kemudian dapat diteruskan ke metode sambungkan ke IoT Hub untuk klien SDK apa pun yang menerima kredensial Microsoft Entra:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

Dalam contoh ini, diteruskan TokenCredential ke untuk ServiceClient.Create membuat objek koneksi ServiceClient .

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

Dalam contoh ini, diteruskan TokenCredential ke RegistryManager.Create untuk membuat objek RegistryManager .

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Sampel kode

Untuk sampel autentikasi layanan Microsoft Entra yang berfungsi, lihat Sampel autentikasi berbasis peran.

Membaca dan memperbarui bidang identitas modul

Panggil GetModuleAsync untuk mengambil bidang kembar identitas modul saat ini ke dalam objek Modul .

Kelas ini Module mencakup properties yang sesuai dengan bagian kembar identitas modul. Gunakan properti kelas Modul untuk melihat dan memperbarui bidang kembar identitas modul. Anda dapat menggunakan Module properti objek untuk memperbarui beberapa bidang sebelum menulis pembaruan ke perangkat menggunakan UpdateModuleAsync.

Setelah membuat pembaruan bidang kembar identitas modul, panggil UpdateModuleAsync untuk menulis Module pembaruan bidang objek kembali ke perangkat. Gunakan try dan catch logika yang digabungkan dengan handler kesalahan untuk menangkap kesalahan patch yang salah diformat dari UpdateModuleAsync.

Contoh ini mengambil modul ke dalam Module objek, memperbarui moduleLastActivityTime properti, lalu memperbarui modul di IoT Hub menggunakan UpdateModuleAsync.

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateModuleAsync(module);
}
catch (Exception e)
{
   console.WriteLine("Module update failed.", e.Message);
}

API modul lainnya

• GetModulesOnDeviceAsync - Mengambil identitas modul pada perangkat
• RemoveModuleAsync - Menghapus modul yang terdaftar sebelumnya dari perangkat

Sampel layanan SDK

Azure IoT SDK untuk .NET menyediakan sampel kerja aplikasi layanan yang menangani tugas kembar identitas modul. Untuk informasi selengkapnya, lihat Pengujian E2E Manajer Registri.

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

Gambaran Umum

Artikel ini menjelaskan cara menggunakan Azure IoT SDK untuk Python untuk membuat kode aplikasi layanan perangkat dan backend untuk kembar identitas modul.

Memasang paket

Pustaka azure-iot-device harus diinstal untuk membuat aplikasi perangkat.

pip install azure-iot-device

Pustaka azure-iot-hub harus diinstal untuk membuat aplikasi layanan backend.

pip install azure-iot-hub

Pustaka msrest digunakan untuk menangkap pengecualian HTTPOperationError.

pip install msrest

Membuat aplikasi perangkat

Bagian ini menjelaskan cara menggunakan kode aplikasi perangkat untuk:

• Mengambil kembaran identitas modul dan memeriksa properti yang dilaporkan
• Memperbarui properti yang dilaporkan kembar identitas modul
• Membuat penangan panggilan balik pembaruan properti yang diinginkan kembar identitas modul

Impor pernyataan

Tambahkan pernyataan ini import untuk menggunakan pustaka perangkat.

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

Menyambungkan ke perangkat

Kelas IoTHubModuleClient berisi metode yang dapat digunakan untuk bekerja dengan kembar identitas modul.

Untuk menyambungkan aplikasi ke perangkat:

1. Panggil create_from_connection_string untuk menambahkan string koneksi identitas modul
2. Memanggil sambungkan untuk menyambungkan klien perangkat ke hub Azure IoT

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{Device module identity connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

Mengambil kembaran identitas modul dan memeriksa properti

Panggil get_twin untuk mengambil kembar identitas modul dari layanan Azure IoT Hub. Informasi kembar ditempatkan ke dalam variabel yang dapat diperiksa.

Contoh ini mengambil perangkat kembar dan menggunakan print perintah untuk melihat perangkat kembar dalam format JSON.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

Memperbarui properti yang dilaporkan kembar identitas modul

Anda dapat menerapkan patch untuk memperbarui properti yang dilaporkan kembar identitas modul dalam format JSON.

Untuk menerapkan patch untuk memperbarui properti yang dilaporkan:

1. Tetapkan patch JSON properti yang dilaporkan ke variabel.
2. Panggil patch_twin_reported_properties untuk menerapkan patch JSON ke properti yang dilaporkan.

Contohnya:

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

Membuat penangan panggilan balik pembaruan properti yang diinginkan kembar identitas modul

Panggil on_twin_desired_properties_patch_received untuk membuat fungsi handler atau coroutine yang dipanggil saat patch properti yang diinginkan kembar identitas modul diterima. Handler mengambil satu argumen, yaitu patch kembar dalam bentuk objek kamus JSON.

Contoh ini menyiapkan handler patch properti yang diinginkan bernama twin_patch_handler.

Contohnya:

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

Menerima twin_patch_handler dan mencetak pembaruan properti yang diinginkan JSON.

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

Sampel perangkat SDK

Azure IoT SDK for Python menyediakan sampel aplikasi perangkat yang berfungsi yang menangani tugas kembar identitas modul:

• get_twin - Sambungkan ke perangkat dan ambil informasi kembar.
• update_twin_reported_properties - Perbarui properti yang dilaporkan kembar.
• receive_twin_desired_properties - Menerima dan memperbarui properti yang diinginkan.

Membuat aplikasi backend

Bagian ini menjelaskan cara membuat aplikasi backend untuk mengambil dan memperbarui properti yang diinginkan kembar identitas modul.

Kelas IoTHubRegistryManager mengekspos semua metode yang diperlukan untuk membuat aplikasi backend untuk berinteraksi dengan kembar identitas modul dari layanan.

Pernyataan impor layanan

Tambahkan pernyataan ini import untuk menggunakan pustaka layanan.

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

Menyambungkan ke hub IoT

Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:

• Kebijakan akses bersama
• Microsoft Entra

Menyambungkan menggunakan kebijakan akses bersama

Sambungkan ke hub IoT menggunakan from_connection_string.

Metode yang update_module_twin digunakan di bagian ini memerlukan izin kebijakan akses bersama Service Connect untuk menambahkan properti yang diinginkan ke modul. Sebagai parameter untuk from_connection_string, berikan kebijakan akses bersama string koneksi yang menyertakan izin Service Connect. Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

Contohnya:

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub shared access policy connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Menyambungkan menggunakan Microsoft Entra

Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.

Untuk gambaran umum autentikasi Python SDK, lihat Mengautentikasi aplikasi Python ke layanan Azure dengan menggunakan Azure SDK untuk Python

Mengonfigurasi aplikasi Microsoft Entra

Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:

• Rahasia Klien
• Sertifikat
• Kredensial identitas federasi

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, Kontributor Kembar IoT Hub diperlukan untuk mengaktifkan akses baca dan tulis ke perangkat IoT Hub dan modul kembar. Untuk informasi selengkapnya, lihat Mengelola akses ke IoT Hub dengan menggunakan penetapan peran Azure RBAC.

Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Mengautentikasi menggunakan DefaultAzureCredential

Cara term mudah untuk menggunakan Microsoft Entra untuk mengautentikasi aplikasi backend adalah dengan menggunakan DefaultAzureCredential, tetapi disarankan untuk menggunakan metode yang berbeda di lingkungan produksi termasuk yang spesifik TokenCredential atau diurai.ChainedTokenCredential Untuk kesederhanaan, bagian ini menjelaskan autentikasi menggunakan DefaultAzureCredential dan Rahasia klien. Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential, lihat Rantai kredensial di pustaka klien Azure Identity untuk Python.

DefaultAzureCredential mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.

Microsoft Entra memerlukan paket impor ini dan pernyataan terkait import :

pip install azure-identity

from azure.identity import DefaultAzureCredential

Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan ID penyewa telah ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh DefaultAzureCredential untuk mengautentikasi aplikasi. Hasil autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke metode koneksi IoT Hub.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

AccessToken yang dihasilkan kemudian dapat diteruskan ke from_token_credential untuk menyambungkan ke IoT Hub untuk klien SDK apa pun yang menerima kredensial Microsoft Entra:

• IoTHubRegistryManager untuk membuat koneksi layanan ke IoT Hub menggunakan kredensial token Entra.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

from_token_credential memerlukan dua parameter:

• URL layanan Azure - URL layanan Azure harus dalam format {Your Entra domain URL}.azure-devices.net tanpa https:// awalan. Contohnya,MyAzureDomain.azure-devices.net.
• Token kredensial Azure

Dalam contoh ini, kredensial Azure diperoleh menggunakan DefaultAzureCredential. URL layanan Azure dan kredensial kemudian disediakan untuk IoTHubRegistryManager.from_token_credential membuat koneksi ke IoT Hub.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

Sampel kode

Untuk sampel kerja autentikasi layanan Microsoft Entra, lihat Microsoft Authentication Library (MSAL) untuk Python.

Mengambil dan memperbarui properti yang diinginkan kembar identitas modul

Anda dapat memperbarui properti yang diinginkan dari aplikasi backend menggunakan update_module_twin.

Untuk mengambil dan memperbarui properti yang diinginkan kembar identitas modul:

1. Panggil get_module_twin untuk mendapatkan versi kembar identitas modul saat ini.
2. Gunakan kelas Twin untuk menambahkan properti yang diinginkan dalam format JSON.
3. Panggil update_module_twin untuk menerapkan patch ke perangkat kembar. Anda juga dapat menggunakan replace_module_twin untuk mengganti properti dan tag yang diinginkan untuk kembar identitas modul.

Contoh ini memperbarui properti yang telemetryInterval diinginkan menjadi 122.

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity twin properties before update:" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module identity twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

Sampel layanan SDK

Azure IoT SDK untuk Python menyediakan sampel kerja aplikasi layanan yang menangani tugas kembar modul identitas perangkat. Untuk informasi selengkapnya, lihat Test IoTHub Registry Manager.

• Memerlukan Node.js versi 10.0.x atau yang lebih baru

Gambaran Umum

Artikel ini menjelaskan cara menggunakan Azure IoT SDK untuk Node.js membuat kode aplikasi layanan perangkat dan backend untuk kembar identitas modul.

Membuat aplikasi perangkat

Bagian ini menjelaskan cara menggunakan paket azure-iot-device di Azure IoT SDK untuk Node.js membuat aplikasi perangkat ke:

• Mengambil kembaran identitas modul dan memeriksa properti yang dilaporkan
• Memperbarui properti kembar yang dilaporkan identitas modul
• Menerima pemberitahuan perubahan properti yang diinginkan kembar identitas modul

Paket azure-iot-device berisi objek yang berinteraksi dengan perangkat IoT. Kelas Kembar mencakup objek khusus kembar. Bagian ini menjelaskan Client kode kelas yang digunakan untuk membaca dan menulis data kembar identitas modul perangkat.

Menginstal paket SDK

Jalankan perintah ini untuk menginstal SDK perangkat azure-iot-device di komputer pengembangan Anda:

npm install azure-iot-device --save

Menyambungkan perangkat ke IoT Hub

Aplikasi perangkat dapat mengautentikasi dengan IoT Hub menggunakan metode berikut:

• Kunci akses bersama
• Sertifikat X.509

Mengautentikasi menggunakan kunci akses bersama

Pilih protokol transportasi

Objek Client mendukung protokol ini:

• Amqp
• Http - Saat menggunakan Http, Client instans memeriksa pesan dari IoT Hub jarang (minimal setiap 25 menit).
• Mqtt
• MqttWs
• AmqpWs

Instal protokol transportasi yang diperlukan pada komputer pengembangan Anda.

Misalnya, perintah ini menginstal Amqp protokol:

npm install azure-iot-device-amqp --save

Untuk informasi selengkapnya tentang perbedaan antara dukungan MQTT, AMQP, dan HTTPS, lihat Panduan komunikasi cloud-ke-perangkat dan Memilih protokol komunikasi perangkat.

Membuat objek klien

Buat Client objek menggunakan paket yang diinstal.

Contohnya:

const Client = require('azure-iot-device').Client;

Membuat objek protokol

Buat Protocol objek menggunakan paket transportasi yang diinstal.

Contoh ini menetapkan protokol AMQP:

const Protocol = require('azure-iot-device-amqp').Amqp;

Menambahkan string koneksi perangkat dan protokol transportasi

Panggil dariConnectionString untuk menyediakan parameter koneksi perangkat:

• connStr - Modul identitas hub IoT string koneksi.
• transportCtor - Protokol transportasi.

Contoh ini menggunakan Amqp protokol transportasi:

const deviceConnectionString = "{IoT hub identity module connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Buka koneksi ke IoT Hub

Gunakan metode terbuka untuk membuka koneksi antara perangkat IoT dan IoT Hub.

Contohnya:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Mengautentikasi menggunakan sertifikat X.509

Sertifikat X.509 dilampirkan ke transportasi koneksi device-to-IoT Hub.

Untuk mengonfigurasi koneksi device-to-IoT Hub menggunakan sertifikat X.509:

1. Panggil dariConnectionString untuk menambahkan perangkat atau modul identitas string koneksi, dan jenis transportasi ke Client objek. Tambahkan x509=true ke string koneksi untuk menunjukkan bahwa sertifikat ditambahkan ke DeviceClientOptions. Contohnya:

   • Perangkat string koneksi:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

   • Modul identitas string koneksi:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

2. Konfigurasikan variabel JSON dengan detail sertifikat dan teruskan ke DeviceClientOptions.

3. Panggil setOptions untuk menambahkan sertifikat dan kunci X.509 (dan secara opsional, frase sandi) ke transportasi klien.

4. Panggil buka untuk membuka koneksi dari perangkat ke IoT Hub.

Contoh ini menunjukkan informasi konfigurasi sertifikat dalam variabel JSON. Konfigurasi clientOptions sertifikasi diteruskan ke setOptions, dan koneksi dibuka menggunakan open.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);

var clientOptions = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }

 client.setOptions(clientOptions);
 client.open(connectCallback);

Untuk informasi selengkapnya tentang autentikasi sertifikat, lihat:

• Mengautentikasi identitas dengan sertifikat X.509
• Membuat dan mengunggah sertifikat untuk pengujian

Sampel kode

Untuk sampel autentikasi sertifikat X.509 perangkat yang berfungsi, lihat Perangkat sampel sederhana X.509.

Mengambil kembaran identitas modul dan memeriksa properti yang dilaporkan

Panggil getTwin untuk mengambil informasi kembar identitas modul saat ini ke dalam objek Kembar .

Kode perangkat kemudian dapat mengakses properti kembar identitas modul.

Contohnya:

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

Memperbarui properti yang dilaporkan kembar identitas modul

Gunakan pembaruan untuk memperbarui properti yang dilaporkan perangkat. Sertakan patch berformat JSON sebagai parameter pertama dan metode panggilan balik status eksekusi fungsi sebagai parameter kedua ke metode .

Dalam contoh ini, patch kembar identitas modul berformat JSON disimpan dalam patch variabel . Patch berisi nilai pembaruan kembar connectivity identitas modul dari cellular. Patch dan handler kesalahan diteruskan ke update metode . Jika ada kesalahan, pesan kesalahan konsol akan ditampilkan.

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

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

Menerima pemberitahuan perubahan properti yang diinginkan kembar identitas modul

Buat pendengar peristiwa pembaruan properti yang diinginkan kembar identitas modul yang dijalankan saat properti yang diinginkan diubah dengan meneruskan nama metode handler panggilan balik ke twin.on.

Pendengar peristiwa properti yang diinginkan dapat mengambil formulir berikut:

• Menerima semua patch dengan satu penanganan aktivitas
• Menerima peristiwa jika ada perubahan di bawah pengelompokan properti
• Menerima peristiwa untuk perubahan properti tunggal

Menerima semua patch dengan satu penanganan aktivitas

Anda dapat membuat pendengar untuk menerima perubahan properti yang diinginkan.

Contoh kode ini menghasilkan properti apa pun yang diterima dari layanan.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Menerima peristiwa jika ada perubahan di bawah pengelompokan properti

Anda dapat membuat pendengar untuk menerima peristiwa jika ada sesuatu di bawah perubahan pengelompokan properti.

Contohnya:

1. Properti minTemperature dan maxTemperature terletak di bawah pengelompokan properti bernama properties.desired.climate changes.

2. Aplikasi layanan backend menerapkan patch ini untuk memperbarui minTemperature dan maxTemperature properti yang diinginkan:

   const twinPatch1 = {
   properties: {
      desired: {
       climate: { minTemperature: 68, maxTemperature: 76, },
       },
     },
    };
   

3. Kode ini menyiapkan pendengar peristiwa perubahan properti yang diinginkan yang memicu perubahan apa pun dalam properties.desired.climate pengelompokan properti. Jika ada perubahan properti yang diinginkan dalam grup ini, pesan perubahan suhu min dan maks ditampilkan ke konsol:

   twin.on('properties.desired.climate', function (delta) {
       if (delta.minTemperature || delta.maxTemperature) {
           console.log('updating desired temp:');
           console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
           console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
       }
   });
   

Menerima peristiwa untuk perubahan properti tunggal

Anda dapat menyiapkan pendengar untuk satu perubahan properti. Dalam contoh ini, kode untuk peristiwa ini dijalankan hanya jika fanOn nilai boolean adalah bagian dari patch. Kode menghasilkan status baru yang diinginkan fanOn setiap kali layanan memperbaruinya.

1. Aplikasi backend menerapkan patch properti yang diinginkan ini:

    const twinPatch2 = {
     properties: {
       desired: {
         climate: {
           hvac: {
             systemControl: { fanOn: true, },
           },
         },
       },
     },
   };
   

2. Pendengar hanya memicu saat fanOn properti berubah:

    twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
        console.log('setting fan state to ' + fanOn);
     });
   

Contoh lengkap

Contoh ini merangkum prinsip-prinsip bagian ini, termasuk fungsi panggilan balik multi-tingkat bersarang.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

Sampel SDK perangkat

Azure IoT SDK untuk Node.js menyediakan sampel kerja aplikasi perangkat yang menangani tugas kembar identitas modul. Untuk informasi selengkapnya, lihat:

• Module Identity Twin
• Pembantu Pengujian Modul
• Tes kembar e2e

Membuat aplikasi backend

Bagian ini menjelaskan cara membuat aplikasi backend yang mengambil kembar identitas modul dan memperbarui properti yang diinginkan.

Menginstal paket SDK layanan

Jalankan perintah ini untuk menginstal azure-iothub di komputer pengembangan Anda:

npm install azure-iothub --save

Membuat objek Registri

Kelas Registri mengekspos semua metode yang diperlukan untuk berinteraksi dengan kembar identitas modul dari aplikasi backend.

let Registry = require('azure-iothub').Registry;

Menyambungkan ke hub IoT

Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:

• Kebijakan akses bersama
• Microsoft Entra

Menyambungkan menggunakan kebijakan akses bersama

Gunakan fromConnectionString untuk menyambungkan ke hub IoT.

Metode yang update digunakan di bagian ini memerlukan izin kebijakan akses bersama Service Connect untuk menambahkan properti yang diinginkan ke modul. Sebagai parameter untuk fromConnectionString, berikan kebijakan akses bersama string koneksi yang menyertakan izin Service Connect. Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

Menyambungkan menggunakan Microsoft Entra

Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.

Untuk gambaran umum autentikasi SDK Node.js, lihat:

• Mulai menggunakan autentikasi pengguna di Azure
• Pustaka klien Azure Identity untuk JavaScript

Mengonfigurasi aplikasi Microsoft Entra

Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:

• Rahasia Klien
• Sertifikat
• Kredensial identitas federasi

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, Kontributor Kembar IoT Hub diperlukan untuk mengaktifkan akses baca dan tulis ke perangkat IoT Hub dan modul kembar. Untuk informasi selengkapnya, lihat Mengelola akses ke IoT Hub dengan menggunakan penetapan peran Azure RBAC.

Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Mengautentikasi menggunakan DefaultAzureCredential

Cara term mudah untuk menggunakan Microsoft Entra untuk mengautentikasi aplikasi backend adalah dengan menggunakan DefaultAzureCredential, tetapi disarankan untuk menggunakan metode yang berbeda di lingkungan produksi termasuk yang spesifik TokenCredential atau diurai.ChainedTokenCredential Untuk kesederhanaan, bagian ini menjelaskan autentikasi menggunakan DefaultAzureCredential dan Rahasia klien. Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential, lihat Rantai kredensial di pustaka klien Azure Identity untuk JavaScript

DefaultAzureCredential mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.

Microsoft Entra memerlukan paket ini:

npm install --save @azure/identity

Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan ID penyewa telah ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh DefaultAzureCredential untuk mengautentikasi aplikasi. Hasil autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke metode koneksi IoT Hub.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Token kredensial yang dihasilkan kemudian dapat diteruskan ke dariTokenCredential untuk terhubung ke IoT Hub untuk klien SDK apa pun yang menerima kredensial Microsoft Entra:

• Registri
• Klien
• JobClient

fromTokenCredential memerlukan dua parameter:

• URL layanan Azure - URL layanan Azure harus dalam format {Your Entra domain URL}.azure-devices.net tanpa https:// awalan. Contohnya,MyAzureDomain.azure-devices.net.
• Token kredensial Azure

Dalam contoh ini, kredensial Azure diperoleh menggunakan DefaultAzureCredential. URL domain Azure dan kredensial kemudian disediakan untuk Registry.fromTokenCredential membuat koneksi ke IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Sampel kode

Untuk sampel autentikasi layanan Microsoft Entra yang berfungsi, lihat Contoh identitas Azure.

Mengambil kembar identitas modul dan memperbarui properti yang diinginkan

Anda dapat membuat patch yang berisi pembaruan properti yang diinginkan untuk kembaran identitas modul.

Untuk memperbarui kembar identitas modul:

1. Panggil getModuleTwin untuk mengambil objek Twin perangkat.

2. Format patch yang berisi pembaruan kembar identitas modul. Patch diformat dalam JSON seperti yang dijelaskan di kelas Twin. Patch layanan backend berisi pembaruan properti yang diinginkan. Untuk informasi format patch lainnya, lihat Format tag dan properti.

3. Panggil pembaruan untuk memperbarui kembar identitas modul dengan patch.

Dalam contoh ini, kembar identitas modul diambil untuk myDeviceId dan myModuleId. Kemudian patch diterapkan ke kembar yang berisi climate informasi.

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

Sampel SDK Layanan

Azure IoT SDK untuk Node.js menyediakan sampel kerja aplikasi layanan yang menangani tugas kembar identitas modul. Untuk informasi selengkapnya, lihat:

• Module Identity Twin
• Pembantu Pengujian Modul
• Tes kembar e2e