Mulai dengan manajemen perangkat

Aplikasi back-end dapat menggunakan primitif Azure IoT Hub, seperti device twins dan direct methods, untuk memulai dan memantau tindakan manajemen perangkat dari jarak jauh pada perangkat.

Gunakan metode langsung dari aplikasi back-end untuk memulai tindakan manajemen perangkat, seperti boot ulang, reset pabrik, dan pembaruan firmware.

Perangkat bertanggung jawab untuk:

  • Menangani permintaan metode langsung yang dikirim dari IoT Hub
  • Memulai tindakan khusus perangkat yang sesuai pada perangkat
  • Menyediakan pembaruan status melalui properti yang dilaporkan ke IoT Hub

Artikel ini menunjukkan kepada Anda bagaimana aplikasi back-end dan aplikasi perangkat dapat bekerja sama untuk memulai dan memantau tindakan perangkat jarak jauh menggunakan metode langsung.

  • Aplikasi layanan memanggil metode langsung untuk memulai ulang di aplikasi perangkat melalui hub IoT.
  • Aplikasi perangkat menangani metode langsung untuk me-reboot perangkat.

Catatan

Fitur yang dijelaskan dalam artikel ini hanya tersedia di tingkat standar IoT Hub. Untuk informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat dan ukuran IoT Hub yang tepat untuk solusi Anda.

Catatan

Artikel ini dimaksudkan untuk melengkapi sampel Azure IoT SDK yang dirujuk dari dalam artikel ini. Anda dapat menggunakan alat SDK untuk membangun aplikasi perangkat dan back-end.

Prasyarat

  • Sebuah hub IoT

  • Perangkat terdaftar

  • Jika aplikasi Anda menggunakan protokol MQTT, pastikan port 8883 terbuka di firewall Anda. Protokol MQTT berkomunikasi melalui port 8883. Port ini dapat diblokir di beberapa lingkungan jaringan perusahaan dan pendidikan. Untuk informasi selengkapnya dan cara mengatasi masalah ini, lihat Menyambungkan ke IoT Hub (MQTT).

  • 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 yang diperlukan untuk perangkat

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

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan perangkat menggunakan tanda tangan akses bersama, juga disebut autentikasi kunci simetris. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi > IoT Keamanan koneksi.

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 protokol Mqtt.

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:

Sampel kode

Untuk contoh praktis autentikasi sertifikat X.509 perangkat, lihat:

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 menetapkan pendengar callback bernama onReboot yang akan diaktifkan 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 ini, metode panggilan balik onReboot 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));
}

Catatan

Untuk mempermudah, artikel ini tidak menerapkan kebijakan percobaan kembali. Dalam kode produksi, Anda harus menerapkan kebijakan coba lagi (seperti exponential backoff), sesuai saran dalam artikel Penanganan kesalahan sementara.

Sampel perangkat SDK

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

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 yang diperlukan untuk layanan

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

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

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi IoT > Keamanan cloud.

Terhubung dengan 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, sediakan kebijakan layanan akses bersama. 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);

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

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, IoT Hub Twin Contributor 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 termudah 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 yang disederhanakan 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 Identitas
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:

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

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

Dalam contoh ini, TokenCredential diteruskan 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 penerima pada perangkat seperti yang dijelaskan di bagian Buat pendengar callback metode langsung dalam 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:

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

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan perangkat menggunakan tanda tangan akses bersama, juga disebut autentikasi kunci simetris. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi > IoT Keamanan koneksi.

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

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan perangkat menggunakan tanda tangan akses bersama, juga disebut autentikasi kunci simetris. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi > IoT Keamanan koneksi.

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 dengan menggunakan informasi ClientOptions untuk membuat koneksi perangkat ke 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:

Sampel kode

Untuk contoh praktis autentikasi sertifikat X.509 perangkat, lihat:

Membuat pendengar panggilan balik metode langsung

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

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

Contohnya:

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");

Catatan

Untuk mempermudah, artikel ini tidak menerapkan kebijakan percobaan kembali. Dalam kode produksi, Anda harus menerapkan kebijakan coba lagi (seperti exponential backoff), sesuai saran dalam artikel Penanganan kesalahan sementara.

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

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi IoT > Keamanan cloud.

Terhubung dengan 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 untuk 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);

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

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, IoT Hub Twin Contributor 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 termudah 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 yang disederhanakan 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. Setelah TokenCredential dibuat, teruskan ke ServiceClient atau pembangun lain sebagai parameter 'kredensial'.

Dalam contoh ini, DefaultAzureCredentialBuilder berusaha 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 kredensial menggunakan rahasia klien. Jika berhasil, metode ini mengembalikan TokenCredential yang dapat diteruskan ke ServiceClient atau pembangun lainnya sebagai parameter 'kredensial'.

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:

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 penerima pada perangkat seperti yang dijelaskan di bagian Buat pendengar callback metode langsung dalam 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:

  • 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

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan perangkat menggunakan tanda tangan akses bersama, juga disebut autentikasi kunci simetris. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi > IoT Keamanan koneksi.

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:

Sampel kode

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

Membuat pemanggilan 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, metode panggilan balik method_request_handler melaksanakan 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 Metode penerimaan 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 menghubungkan ke IoT Hub, mengirim metode langsung dari cloud ke perangkat, dan menerima respons metode langsung dari 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

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi IoT > Keamanan cloud.

Terhubung dengan 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, sediakan kebijakan layanan akses bersama. 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)

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

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, IoT Hub Twin Contributor 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 termudah 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 yang disederhanakan 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:

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

Dalam contoh ini, kredensial Azure diperoleh menggunakan DefaultAzureCredential. URL layanan Azure dan kredensial kemudian disediakan untuk IoTHubRegistryManager.from_token_credential guna 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 Pustaka Autentikasi Microsoft (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 bagian Membuat callback metode langsung, nama metode langsung tersebut 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 dipanggil dengan sukses, payload responsnya 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:

  • 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

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan perangkat menggunakan tanda tangan akses bersama, juga disebut autentikasi kunci simetris. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi > IoT Keamanan koneksi.

Mengautentikasi menggunakan sertifikat X.509

Sertifikat X.509 dilampirkan ke saluran 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:

    • String koneksi perangkat

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

    • String sambungan modul identitas:

      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, kata sandi) ke transport 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:

Sampel kode

Untuk contoh yang berfungsi dari autentikasi sertifikat perangkat X.509, lihat Contoh perangkat X.509 yang sederhana.

Mengautentikasi menggunakan kunci akses bersama

Pilih protokol transportasi

Objek Client mendukung protokol ini:

  • Amqp
  • Http - Saat menggunakan Http, Client instans jarang memeriksa pesan dari IoT Hub (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 transpor yang terinstal.

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 - String koneksi perangkat.
  • 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 pemanggilan balik metode langsung

Panggil onDeviceMethod untuk membuat fungsi pengendali panggilan balik atau coroutine yang dipanggil ketika sebuah 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, metode panggilan balik onReboot melaksanakan 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:

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

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi IoT > Keamanan cloud.

Terhubung dengan 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 untuk 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);

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

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 federatif

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, IoT Hub Twin Contributor 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 termudah 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 yang disederhanakan 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:

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

Dalam contoh ini, kredensial Azure diperoleh menggunakan DefaultAzureCredential. URL domain Azure dan kredensial kemudian diberikan kepada Registry.fromTokenCredential untuk 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 penangan panggilan balik pada perangkat seperti yang dijelaskan di Buat panggilan balik metode langsung bagian 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:

  • Last updated on