Mulai dengan manajemen perangkat

• Memerlukan Visual Studio

Gambaran Umum

Artikel ini menjelaskan cara menggunakan Azure IoT SDK untuk .NET untuk membuat kode aplikasi layanan perangkat dan backend untuk pesan langsung perangkat.

Membuat aplikasi perangkat

Bagian ini menjelaskan cara menggunakan kode aplikasi perangkat untuk membuat pendengar panggilan balik metode langsung.

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

Kelas DeviceClient mengekspos semua metode yang diperlukan untuk berinteraksi dengan pesan perangkat dari perangkat.

Sambungkan ke perangkat menggunakan metode CreateFromConnectionString bersama dengan string koneksi perangkat dan protokol transportasi koneksi.

Parameter CreateFromConnectionStringprotokol transportasi TransportType mendukung protokol transportasi berikut:

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_Only
• Http1

Contoh ini terhubung ke perangkat menggunakan Mqtt protokol transportasi.

static string DeviceConnectionString = "{IoT hub device connection string}";
static deviceClient = null;
deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Mengautentikasi menggunakan sertifikat X.509

Untuk menyambungkan perangkat ke IoT Hub menggunakan sertifikat X.509:

1. Gunakan DeviceAuthenticationWithX509Certificate untuk membuat objek yang berisi informasi perangkat dan sertifikat. DeviceAuthenticationWithX509Certificate diteruskan sebagai parameter kedua ke DeviceClient.Create (langkah 2).

2. Gunakan DeviceClient.Create untuk menyambungkan perangkat ke IoT Hub menggunakan sertifikat X.509.

Dalam contoh ini, informasi perangkat dan sertifikat diisi dalam objek yang diteruskan authDeviceAuthenticationWithX509Certificate ke DeviceClient.Create.

Contoh ini menunjukkan nilai parameter input sertifikat sebagai variabel lokal untuk kejelasan. Dalam sistem produksi, simpan parameter input sensitif dalam variabel lingkungan atau lokasi penyimpanan lain yang lebih aman. Misalnya, gunakan Environment.GetEnvironmentVariable("HOSTNAME") untuk membaca variabel lingkungan nama host.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

Untuk informasi selengkapnya tentang autentikasi sertifikat, lihat:

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

Sampel kode

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

• Menyambungkan dengan sertifikat X.509
• DeviceClientX509AuthenticationE2ETests
• Proyek terpandu - Memprovisikan perangkat IoT dengan aman dan dalam skala besar dengan IoT Hub Device Provisioning Service

Membuat pendengar panggilan balik metode langsung

Gunakan SetMethodHandlerAsync untuk menginisialisasi pendengar panggilan balik metode langsung. Pendengar dikaitkan dengan kata kunci nama metode, seperti "reboot". Nama metode dapat digunakan dalam IoT Hub atau aplikasi backend untuk memicu metode panggilan balik pada perangkat.

Contoh ini menyiapkan pendengar panggilan balik bernama onReboot yang akan memicu ketika nama metode langsung "reboot" dipanggil.

try
{
      // setup callback for "reboot" method
      deviceClient.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
      Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
      Console.ReadLine();

      Console.WriteLine("Exiting...");

      // as a good practice, remove the "reboot" handler
      deviceClient.SetMethodHandlerAsync("reboot", null, null).Wait();
      deviceClient.CloseAsync().Wait();
}
catch (Exception ex)
{
      Console.WriteLine();
      Console.WriteLine("Error in sample: {0}", ex.Message);
}

Melanjutkan contoh, onReboot metode panggilan balik mengimplementasikan metode langsung pada perangkat.

Fungsi handler memanggil MethodResponse untuk mengirim pengakuan respons ke aplikasi panggilan.

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
      // In a production device, you would trigger a reboot 
      // scheduled to start after this method returns.
      // For this sample, we simulate the reboot by writing to the console
      // and updating the reported properties.
      try
      {
         Console.WriteLine("Rebooting!");
      }
      catch (Exception ex)
      {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
      }

      string result = @"{""result"":""Reboot started.""}";
      return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Sampel perangkat SDK

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

• Sampel Metode
• Perangkat Simulasi dengan Perintah
• Pengontrol Suhu
• Sampel Termostat

Membuat aplikasi backend

Bagian ini menjelaskan cara memicu metode langsung pada perangkat.

Kelas ServiceClient mengekspos semua metode yang diperlukan untuk membuat aplikasi backend untuk mengirim panggilan metode langsung ke perangkat.

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 hub IoT

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

• Kebijakan akses bersama
• Microsoft Entra

Menyambungkan menggunakan kebijakan akses bersama

Sambungkan aplikasi backend menggunakan CreateFromConnectionString.

Untuk memanggil metode langsung pada perangkat melalui Azure IoT Hub, layanan Anda memerlukan izin koneksi layanan. Secara default, setiap IoT Hub dibuat dengan kebijakan akses bersama bernama layanan yang memberikan izin ini.

Sebagai parameter untuk CreateFromConnectionString, berikan kebijakan akses bersama layanan . Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

ServiceClient serviceClient;
string connectionString = "{IoT hub service shared access policy connection string}";
serviceClient = ServiceClient.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.

Memanggil metode pada perangkat

Untuk memanggil metode pada perangkat:

1. Buat objek CloudToDeviceMethod . Berikan nama metode langsung perangkat sebagai parameter.
2. Panggil InvokeDeviceMethodAsync untuk memanggil metode pada perangkat.

Contoh ini memanggil metode "reboot" untuk memulai boot ulang pada perangkat. Metode "reboot" dipetakan ke pendengar di perangkat seperti yang dijelaskan di bagian Buat pendengar panggilan balik metode langsung di artikel ini.

string targetDevice = "myDeviceId";
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult response = await serviceClient.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

Sampel layanan SDK

Azure IoT SDK untuk .NET menyediakan sampel kerja aplikasi layanan yang menangani tugas pesan. Untuk informasi selengkapnya, lihat:

• Memanggil Metode Perangkat
• Tes E2E Metode
• Pengontrol Suhu
• Sampel Termostat

• Memerlukan Java SE Development Kit 8. Pastikan Anda memilih Java 8 di bawah Dukungan jangka panjang untuk menavigasi ke unduhan untuk JDK 8.

Gambaran Umum

Artikel ini menjelaskan cara menggunakan Azure IoT SDK for Java untuk membuat kode aplikasi layanan perangkat dan backend untuk metode langsung perangkat.

Membuat aplikasi perangkat

Bagian ini menjelaskan cara menggunakan kode aplikasi perangkat untuk membuat pendengar panggilan balik metode langsung.

Kelas DeviceClient mengekspos semua metode yang Anda butuhkan untuk berinteraksi dengan metode langsung pada perangkat.

Pernyataan impor perangkat

Gunakan pernyataan impor perangkat berikut untuk mengakses Azure IoT SDK untuk Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

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

Untuk menyambungkan ke perangkat:

1. Gunakan IotHubClientProtocol untuk memilih protokol transportasi. Contohnya:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. DeviceClient Gunakan konstruktor untuk menambahkan string koneksi dan protokol utama perangkat.

   String connString = "{IoT hub device connection string}";
   DeviceClient client = new DeviceClient(connString, protocol);
   

3. Gunakan buka untuk menyambungkan perangkat ke hub IoT. Jika klien sudah terbuka, metode tidak melakukan apa pun.

   client.open(true);
   

Mengautentikasi menggunakan sertifikat X.509

Untuk menyambungkan perangkat ke IoT Hub menggunakan sertifikat X.509:

1. Buat objek SSLContext menggunakan buildSSLContext.
2. Tambahkan informasi ke SSLContextobjek ClientOptions .
3. Panggil DeviceClient menggunakan ClientOptions informasi untuk membuat koneksi device-to-IoT Hub.

Contoh ini menunjukkan nilai parameter input sertifikat sebagai variabel lokal untuk kejelasan. Dalam sistem produksi, simpan parameter input sensitif dalam variabel lingkungan atau lokasi penyimpanan lain yang lebih aman. Misalnya, gunakan Environment.GetEnvironmentVariable("PUBLICKEY") untuk membaca variabel lingkungan string sertifikat kunci publik.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

Untuk informasi selengkapnya tentang autentikasi sertifikat, lihat:

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

Sampel kode

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

• Sampel x509 kirim-terima
• Kirim peristiwa x509

Membuat pendengar panggilan balik metode langsung

Gunakan subscribeToMethods untuk menginisialisasi pendengar panggilan balik metode langsung. subscribeToMethods mendengarkan metode langsung masuk hingga koneksi dihentikan. Nama metode dan payload diterima untuk setiap panggilan metode langsung.

Pendengar harus memanggil DirectMethodResponse untuk mengirim pengakuan respons metode ke aplikasi panggilan.

Contoh:

client.subscribeToMethods(
    (methodName, methodData, context) ->
    {
        System.out.println("Received a direct method invocation with name " + methodName + " and payload " + methodData.getPayloadAsJsonString());
        return new DirectMethodResponse(200, methodData);
    },
    null);
System.out.println("Successfully subscribed to direct methods");

Sampel perangkat SDK

Azure IoT SDK for Java menyertakan sampel kerja untuk menguji konsep aplikasi perangkat yang dijelaskan dalam artikel ini. Untuk informasi selengkapnya, lihat Sampel Metode Langsung.

Membuat aplikasi backend

Bagian ini menjelaskan cara memulai boot ulang jarak jauh pada perangkat menggunakan metode langsung.

Kelas ServiceClientDeviceMethod berisi metode yang dapat digunakan layanan untuk mengakses metode langsung.

Pernyataan impor layanan

Gunakan pernyataan impor layanan berikut untuk mengakses Azure IoT SDK untuk Java.

import com.microsoft.azure.sdk.iot.service.methods.DirectMethodRequestOptions;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodsClient;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodResponse;

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 konstruktor DeviceMethod untuk menambahkan string koneksi utama layanan dan menyambungkan ke IoT Hub.

Untuk memanggil metode langsung pada perangkat melalui Azure IoT Hub, layanan Anda memerlukan izin koneksi layanan. Secara default, setiap IoT Hub dibuat dengan kebijakan akses bersama bernama layanan yang memberikan izin ini.

Sebagai parameter untuk DeviceMethod konstruktor, berikan kebijakan akses bersama layanan . Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

Contohnya:

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(iotHubConnectionString);

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 Java SDK, lihat Autentikasi Azure dengan Java dan Azure Identity.

Untuk kesederhanaan, bagian ini berfokus pada menjelaskan autentikasi menggunakan rahasia klien.

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 informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential, lihat Rantai kredensial di pustaka klien Azure Identity untuk Java.

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.

Anda dapat mengautentikasi kredensial aplikasi Microsoft Entra menggunakan DefaultAzureCredentialBuilder. Simpan parameter koneksi seperti tenantID rahasia klien, clientID, dan nilai rahasia klien sebagai variabel lingkungan. TokenCredential Setelah dibuat, teruskan ke ServiceClient atau penyusun lain sebagai parameter 'info masuk'.

Dalam contoh ini, DefaultAzureCredentialBuilder upaya untuk mengautentikasi koneksi dari daftar yang dijelaskan dalam DefaultAzureCredential. Hasil dari autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke konstruktor seperti ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Mengautentikasi menggunakan ClientSecretCredentialBuilder

Anda dapat menggunakan ClientSecretCredentialBuilder untuk membuat info masuk menggunakan informasi rahasia klien. Jika berhasil, metode ini mengembalikan TokenCredential yang dapat diteruskan ke ServiceClient atau penyusun lainnya sebagai parameter 'info masuk'.

Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan nilai ID penyewa telah ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh ClientSecretCredentialBuilder untuk membangun kredensial.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Kelas autentikasi lainnya

Java SDK juga menyertakan kelas-kelas ini yang mengautentikasi aplikasi backend dengan Microsoft Entra:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

Sampel kode

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

Memanggil metode pada perangkat

Panggil DeviceMethod.invoke untuk memanggil metode pada perangkat dan mengembalikan status hasil.

Parameter invoke payload bersifat opsional. Gunakan null jika tidak ada payload yang disediakan. Parameter payload dapat mengambil formulir data yang berbeda termasuk string, byte array, dan HashMap. Misalnya, lihat Pengujian Metode Langsung.

Contoh ini memanggil metode "reboot" untuk memulai boot ulang pada perangkat. Metode "reboot" dipetakan ke pendengar di perangkat seperti yang dijelaskan di bagian Buat pendengar panggilan balik metode langsung di artikel ini.

Contohnya:

String deviceId = "myFirstDevice";
String methodName = "reboot";
String payload = "Test payload";
Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
if (result == null)
{
    throw new IOException("Method invoke returns null");
}
System.out.println("Status=" + result.getStatus());

Sampel layanan SDK

Azure IoT SDK for Java menyediakan sampel kerja aplikasi layanan yang menangani tugas metode langsung. Untuk informasi selengkapnya, lihat:

• Sampel metode langsung
• Sampel layanan termostat

• Python SDK - Python versi 3.7 atau yang lebih baru direkomendasikan. 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 metode langsung perangkat.

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

Membuat aplikasi perangkat

Bagian ini menjelaskan cara menggunakan kode aplikasi perangkat untuk membuat pendengar panggilan balik metode langsung.

Kelas IoTHubDeviceClient berisi metode yang dapat digunakan untuk bekerja dengan metode langsung.

Pernyataan impor perangkat

Tambahkan pernyataan impor ini ke akses IoTHubDeviceClient dan MethodResponse.

# import the device client library
from azure.iot.device import IoTHubDeviceClient, MethodResponse

Menyambungkan ke perangkat

Aplikasi perangkat dapat mengautentikasi dengan IoT Hub menggunakan metode berikut:

• Kunci akses bersama
• Sertifikat X.509

Mengautentikasi menggunakan kunci akses bersama

Gunakan create_from_connection_string untuk menyambungkan aplikasi ke perangkat menggunakan perangkat string koneksi.

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

Mengautentikasi menggunakan sertifikat X.509

Untuk menyambungkan perangkat ke IoT Hub menggunakan sertifikat X.509:

1. Gunakan create_from_x509_certificate untuk menambahkan parameter sertifikat X.509
2. Panggil sambungkan untuk menyambungkan klien perangkat

Contoh ini menunjukkan nilai parameter input sertifikat sebagai variabel lokal untuk kejelasan. Dalam sistem produksi, simpan parameter input sensitif dalam variabel lingkungan atau lokasi penyimpanan lain yang lebih aman. Misalnya, gunakan os.getenv("HOSTNAME") untuk membaca variabel lingkungan nama host.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

Untuk informasi selengkapnya tentang autentikasi sertifikat, lihat:

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

Sampel kode

Untuk sampel kerja autentikasi sertifikat X.509 perangkat, lihat contoh yang nama filenya berakhiran x509 pada skenario hub Asinkron.

Membuat panggilan balik metode langsung

Gunakan on_method_request_received untuk membuat fungsi handler atau coroutine yang dipanggil saat metode langsung diterima. Pendengar dikaitkan dengan kata kunci nama metode, seperti "reboot". Nama metode dapat digunakan dalam IoT Hub atau aplikasi backend untuk memicu metode panggilan balik pada perangkat.

Fungsi handler harus membuat MethodResponse dan meneruskannya ke send_method_response untuk mengirim pengakuan respons metode langsung ke aplikasi panggilan.

Contoh ini menyiapkan handler metode langsung bernama method_request_handler.

try:
    # Attach the handler to the client
    client.on_method_request_received = method_request_handler
except:
    # In the event of failure, clean up
    client.shutdown()

Dalam contoh ini, method_request_handler metode panggilan balik mengimplementasikan metode langsung pada perangkat. Kode dijalankan ketika metode langsung "rebootDevice" dipanggil dari aplikasi layanan. Metode ini memanggil send_method_response untuk mengirim pengakuan respons metode langsung ke aplikasi panggilan.

# Define the handler for method requests
def method_request_handler(method_request):
    if method_request.name == "rebootDevice":
        # Act on the method by rebooting the device
        print("Rebooting device")
        time.sleep(20)
        print("Device rebooted")
        # Create a method response indicating the method request was resolved
        resp_status = 200
        resp_payload = {"Response": "This is the response from the device"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)
    else:
        # Create a method response indicating the method request was for an unknown method
        resp_status = 404
        resp_payload = {"Response": "Unknown method"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

    # Send the method response
    client.send_method_response(method_response)

Sampel perangkat SDK

Azure IoT SDK for Python menyediakan sampel kerja aplikasi perangkat yang menangani tugas metode langsung. Untuk informasi selengkapnya, lihat Menerima metode langsung.

Membuat aplikasi backend

Bagian ini menjelaskan cara menggunakan aplikasi layanan backend untuk memanggil metode langsung pada perangkat.

Kelas IoTHubRegistryManager mengekspos semua metode yang diperlukan untuk membuat aplikasi backend untuk mengirim pesan ke perangkat.

Pernyataan impor layanan

Tambahkan pernyataan impor ini untuk terhubung ke Iot Hub, mengirim metode langsung cloud-ke-perangkat, dan menerima respons metode langsung perangkat.

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult

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.

Untuk memanggil metode langsung pada perangkat melalui Azure IoT Hub, layanan Anda memerlukan izin koneksi layanan. Secara default, setiap IoT Hub dibuat dengan kebijakan akses bersama bernama layanan yang memberikan izin ini.

Sebagai parameter untuk from_connection_string, berikan kebijakan akses bersama layanan . 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 service 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.

Memanggil metode pada perangkat

Anda dapat memanggil metode langsung berdasarkan nama pada perangkat. Nama metode mengidentifikasi metode . Dalam contoh perangkat berikut dan sebelumnya yang ditunjukkan dalam Membuat panggilan balik metode langsung, nama metode langsung adalah "rebootDevice".

Untuk memanggil metode langsung pada perangkat:

1. Buat objek CloudToDeviceMethod . Berikan nama metode dan payload sebagai parameter.
2. Panggil invoke_device_method untuk memanggil metode langsung pada perangkat. Berikan ID perangkat dan CloudToDeviceMethod objek payload sebagai parameter.

Contoh ini memanggil CloudToDeviceMethod untuk memanggil metode langsung bernama "rebootDevice" pada perangkat. Setelah metode langsung berhasil dipanggil, payload respons metode langsung ditampilkan.

CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10

try:
    print ( "" )
    print ( "Invoking device to reboot..." )

    # Call the direct method.
    deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
    response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

    print ( "Successfully invoked the device to reboot." )

    print ( "The device has returned this payload:" )
    print ( response.payload )

except Exception as ex:
    print ( "" )
    print ( "Unexpected error {0}".format(ex) )
    return

Sampel layanan SDK

Azure IoT SDK untuk Python menyediakan sampel kerja aplikasi layanan yang menangani tugas metode langsung. Untuk informasi selengkapnya, lihat:

• Sinkronisasi pembantu layanan
• Operasi layanan

• 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 metode langsung perangkat.

Membuat aplikasi perangkat

Bagian ini menjelaskan cara menggunakan kode aplikasi perangkat untuk membuat panggilan balik metode langsung.

Menginstal paket SDK

Paket azure-iot-device berisi objek yang berinteraksi dengan perangkat IoT. 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:

• Sertifikat X.509
• Kunci akses bersama

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.

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-to-device dan Pilih protokol komunikasi.

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 - Perangkat string koneksi.
• transportCtor - Protokol transportasi.

Contoh ini menggunakan Amqp protokol transportasi:

const deviceConnectionString = "{IoT hub device 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);
  }
})

Membuat panggilan balik metode langsung

Panggil onDeviceMethod untuk membuat fungsi handler panggilan balik atau coroutine yang dipanggil saat metode langsung diterima. Pendengar dikaitkan dengan kata kunci nama metode, seperti "reboot". Nama metode dapat digunakan dalam IoT Hub atau aplikasi backend untuk memicu metode panggilan balik pada perangkat.

Fungsi handler panggilan balik harus memanggil response.send untuk mengirim pesan pengakuan respons ke aplikasi panggilan.

Contoh ini menyiapkan handler metode langsung bernama onReboot yang dipanggil ketika nama metode langsung "reboot" digunakan.

client.onDeviceMethod('reboot', onReboot);

Dalam contoh ini, onReboot metode panggilan balik mengimplementasikan metode langsung pada perangkat. Kode dijalankan ketika metode langsung "reboot" dipanggil dari aplikasi layanan. Fungsi ini memanggil response.send untuk mengirim pesan pengakuan respons ke aplikasi panggilan.

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

Sampel perangkat SDK

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

• Sampel metode perangkat
• Pengujian E2E metode perangkat
• Perangkat reboot pola DM

Membuat aplikasi backend

Bagian ini menjelaskan cara memanggil metode langsung pada perangkat.

Menginstal paket SDK layanan

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

npm install azure-iothub --save

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.

Untuk memanggil metode langsung pada perangkat melalui Azure IoT Hub, layanan Anda memerlukan izin koneksi layanan. Secara default, setiap IoT Hub dibuat dengan kebijakan akses bersama bernama layanan yang memberikan izin ini.

Sebagai parameter untuk CreateFromConnectionString, berikan string koneksi kebijakan akses bersama layanan. Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(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.

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.

Memanggil metode pada perangkat

Gunakan invokeDeviceMethod untuk memanggil metode langsung berdasarkan nama pada perangkat. Parameter nama metode mengidentifikasi metode langsung.

Contoh ini memanggil metode "reboot" untuk memulai boot ulang pada perangkat. Metode "reboot" dipetakan ke fungsi handler panggilan balik pada perangkat seperti yang dijelaskan di bagian Buat panggilan balik metode langsung di artikel ini.

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

Sampel layanan SDK

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

• Metode modul
• Pengujian metode perangkat
• Pengujian E2E metode perangkat
• Pemutusan sambungan metode