Mulai dengan perangkat kembar

• Memerlukan Visual Studio

Gambaran Umum

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

Membuat aplikasi perangkat

Aplikasi perangkat dapat membaca dan menulis properti yang dilaporkan kembar, dan diberi tahu tentang perubahan properti kembar yang diinginkan yang diatur oleh aplikasi backend atau IoT Hub.

Bagian ini menjelaskan cara menggunakan kode aplikasi perangkat untuk:

• Mengambil perangkat kembar dan memeriksa properti yang dilaporkan
• Memperbarui properti kembar perangkat yang dilaporkan
• Membuat handler panggilan balik pembaruan properti yang diinginkan

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;

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

Protokol Http1 tidak didukung untuk pembaruan kembar perangkat.

Contoh ini terhubung ke perangkat menggunakan Mqtt protokol transportasi.

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

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

Mengambil perangkat kembar dan memeriksa properti

Panggil GetTwinAsync untuk mengambil properti kembar perangkat saat ini. Ada banyak properti objek Kembar yang dapat Anda gunakan untuk mengakses area tertentu dari Twin data JSON termasuk Properties, , StatusTags, dan Version.

Contoh ini mengambil properti kembar perangkat dan mencetak nilai kembar dalam format JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Memperbarui properti kembar perangkat yang dilaporkan

Untuk memperbarui properti yang dilaporkan kembar:

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

Contohnya:

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

Membuat handler panggilan balik pembaruan properti yang diinginkan

Buat handler panggilan balik pembaruan properti yang diinginkan yang dijalankan ketika properti yang diinginkan diubah di perangkat kembar dengan meneruskan nama metode handler panggilan balik ke SetDesiredPropertyUpdateCallbackAsync.

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

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

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

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

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

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

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

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

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Sampel perangkat SDK

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

Membuat aplikasi backend

Aplikasi backend terhubung ke perangkat melalui IoT Hub dan dapat membaca properti yang dilaporkan dan diinginkan perangkat, menulis properti yang diinginkan perangkat, dan menjalankan kueri perangkat.

Bagian ini menjelaskan cara membuat kode aplikasi backend untuk:

• Membaca dan memperbarui bidang kembar perangkat
• Membuat kueri kembar perangkat

Kelas RegistryManager mengekspos semua metode yang diperlukan untuk membuat aplikasi backend untuk berinteraksi dengan perangkat ganda dari layanan.

Tambahkan Paket NuGet layanan

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

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 ke perangkat menggunakan CreateFromConnectionString. Aplikasi Anda memerlukan izin sambungkan layanan untuk memodifikasi properti kembar perangkat yang diinginkan, dan memerlukan izin baca registri untuk mengkueri registri identitas. Tidak ada kebijakan akses bersama default yang hanya berisi kedua izin ini, jadi Anda perlu membuatnya jika belum ada. Berikan kebijakan akses bersama ini string koneksi sebagai parameter ke fromConnectionString. Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Menyambungkan menggunakan Microsoft Entra

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

Mengonfigurasi aplikasi Microsoft Entra

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

• Rahasia Klien
• Sertifikat
• Kredensial identitas federasi

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

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

Mengautentikasi menggunakan DefaultAzureCredential

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

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

Microsoft Entra memerlukan paket NuGet ini dan pernyataan terkait using :

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

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

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

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

TokenCredential tokenCredential = new DefaultAzureCredential();

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

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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

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

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

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

Sampel kode

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

Membaca dan memperbarui bidang kembar perangkat

Anda dapat mengambil bidang kembar perangkat saat ini ke objek Kembar dengan memanggil GetTwinAsync.

Kelas Twin ini mencakup properti yang sesuai dengan setiap bagian perangkat kembar. Twin Gunakan properti kelas untuk melihat dan memperbarui bidang kembar perangkat. Anda dapat menggunakan Twin properti objek untuk memperbarui beberapa bidang kembar sebelum menulis pembaruan ke perangkat menggunakan UpdateTwinAsync.

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

Membaca dan memperbarui tag kembar perangkat

Gunakan properti Tag kembar perangkat untuk membaca dan menulis informasi tag perangkat.

Memperbarui tag menggunakan objek kembar

Contoh ini membuat location patch tag, menetapkannya ke Twin objek menggunakan Tags properti , lalu menerapkan patch menggunakan UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

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

Memperbarui tag menggunakan string JSON

Anda dapat membuat dan menerapkan patch pembaruan informasi kembar perangkat berformat JSON. IoT Hub mengurai dan menerapkan patch jika diformat dengan benar.

Contoh ini memanggil GetTwinAsync untuk mengambil bidang kembar perangkat saat ini ke dalam Twin objek, membuat patch berformat tag JSON dengan informasi lokasi wilayah dan pabrik, lalu memanggil UpdateTwinAsync untuk menerapkan patch untuk memperbarui perangkat kembar. Pesan kesalahan ditampilkan jika UpdateTwinAsync gagal.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Menampilkan dan memperbarui properti yang diinginkan kembar

Gunakan properti perangkat kembar TwinProperties.Desired untuk membaca dan menulis informasi properti yang diinginkan perangkat. Perbarui properti kembar Desired menggunakan patch berformat JSON.

Contoh ini memanggil GetTwinAsync untuk mengambil bidang kembar perangkat saat ini ke dalam Twin objek, memperbarui properti yang diinginkan kembar speed , lalu memanggil UpdateTwinAsync untuk menerapkan Twin objek untuk memperbarui perangkat kembar.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Metode pembaruan kembar lainnya

Anda juga dapat menerapkan pembaruan kembar menggunakan metode SDK ini:

• Panggil ReplaceTwinAsync untuk menggantikan seluruh perangkat kembar.
• Panggil UpdateTwins2Async untuk memperbarui daftar kembar yang sebelumnya dibuat dalam sistem.

Membuat kueri kembar perangkat

Bagian ini menunjukkan dua kueri kembar perangkat. Kueri kembar perangkat adalah kueri seperti SQL yang mengembalikan kumpulan hasil kembar perangkat.

Untuk membuat kueri kembar perangkat, panggil CreateQuery untuk mengirimkan kueri SQL kembar dan mendapatkan Antarmuka IQuery . Anda dapat secara opsional memanggil CreateQuery dengan parameter kedua untuk menentukan jumlah maksimum item per halaman.

Panggilan GetNextAsTwinAsync atau GetNextAsJsonAsync metode berikutnya sebanyak yang diperlukan untuk mengambil semua hasil kembar.

• GetNextAsTwinAsync untuk mengambil hasil halaman berikutnya sebagai objek Kembar .
• GetNextAsJsonAsync untuk mengambil hasil halaman berikutnya sebagai string JSON.

Antarmuka IQuery mencakup properti boolean HasMoreResults yang dapat Anda gunakan untuk memeriksa apakah ada lebih banyak hasil kembar untuk diambil.

Contoh kueri ini hanya memilih perangkat kembar perangkat yang terletak di pabrik Redmond43 .

var query = registryManager.CreateQuery(
"SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
var twinsInRedmond43 = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43: {0}", 
string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

Contoh kueri ini menyempurnakan kueri pertama untuk memilih hanya perangkat yang juga tersambung melalui jaringan seluler.

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));

Sampel layanan SDK

Azure IoT SDK untuk .NET menyediakan sampel kerja aplikasi layanan yang menangani tugas kembar perangkat. Untuk informasi selengkapnya, lihat Sampel Manajer Registri.

• 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 untuk Java untuk membuat kode aplikasi layanan perangkat dan backend untuk perangkat kembar.

Membuat aplikasi perangkat

Aplikasi perangkat dapat membaca dan menulis properti yang dilaporkan kembar, dan diberi tahu tentang perubahan properti kembar yang diinginkan yang diatur oleh aplikasi backend atau IoT Hub.

Bagian ini menjelaskan cara membuat kode aplikasi perangkat untuk:

• Mengambil dan melihat perangkat kembar
• Memperbarui properti kembar perangkat yang dilaporkan
• Berlangganan perubahan properti yang diinginkan

Kelas DeviceClient mengekspos semua metode yang Anda butuhkan untuk berinteraksi dengan perangkat ganda dari 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.DeviceTwin.*;

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 perangkat ke IoT Hub:

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

Mengambil dan melihat perangkat kembar

Setelah membuka koneksi klien, panggil getTwin untuk mengambil properti kembar saat ini ke dalam Twin objek.

Contohnya:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Memperbarui properti yang dilaporkan kembar perangkat

Setelah mengambil kembar saat ini, Anda dapat mulai membuat pembaruan properti yang dilaporkan. Anda juga dapat membuat pembaruan properti yang dilaporkan tanpa mendapatkan kembar saat ini selama Anda memiliki versi properti yang dilaporkan dengan benar. Jika Anda mengirim properti yang dilaporkan dan menerima kesalahan "prasyarat gagal", maka versi properti yang dilaporkan sudah kedaluwarsa. Dalam hal ini, dapatkan versi terbaru dengan memanggil getTwin lagi.

Untuk memperbarui properti yang dilaporkan:

1. Panggil getReportedProperties untuk mengambil properti kembar yang dilaporkan ke dalam objek TwinCollection .

2. Gunakan put untuk memperbarui properti yang dilaporkan dalam TwinCollection objek. Panggil put untuk setiap pembaruan properti yang dilaporkan.

3. Gunakan updateReportedProperties untuk menerapkan grup properti yang dilaporkan yang diperbarui menggunakan metode .put

Contohnya:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

Berlangganan perubahan properti yang diinginkan

Panggil subscribeToDesiredProperties untuk berlangganan perubahan properti yang diinginkan. Klien ini menerima panggilan balik dengan Twin objek setiap kali properti yang diinginkan diperbarui. Panggilan balik tersebut berisi kumpulan properti yang diinginkan penuh, atau hanya properti yang diinginkan yang diperbarui tergantung pada bagaimana properti yang diinginkan diubah.

Contoh ini berlangganan perubahan properti yang diinginkan. Setiap perubahan properti yang diinginkan diteruskan ke handler bernama DesiredPropertiesUpdatedHandler.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

Dalam contoh ini, properti yang DesiredPropertiesUpdatedHandler diinginkan mengubah panggilan balik handler panggilan balik memanggil getDesiredProperties untuk mengambil perubahan properti, lalu mencetak properti kembar yang diperbarui.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

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 Kembar Perangkat.

Membuat aplikasi backend

Bagian ini menjelaskan cara membuat aplikasi backend yang:

• Memperbarui tag kembar perangkat
• Mengkueri perangkat menggunakan filter pada tag dan properti

Kelas ServiceClientDeviceTwin berisi metode yang dapat digunakan layanan untuk mengakses perangkat kembar.

Pernyataan impor layanan

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

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Menyambungkan ke IoT Hub

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

• Kebijakan akses bersama
• Microsoft Entra

Menyambungkan menggunakan kebijakan akses bersama

Gunakan konstruktor DeviceTwin untuk membuat koneksi ke hub IoT. Objek DeviceTwin menangani komunikasi dengan hub IoT Anda.

Aplikasi Anda memerlukan izin sambungkan layanan untuk memodifikasi properti kembar perangkat yang diinginkan, dan memerlukan izin baca registri untuk mengkueri registri identitas. Tidak ada kebijakan akses bersama default yang hanya berisi kedua izin ini, jadi Anda perlu membuatnya jika belum ada. Berikan kebijakan akses bersama ini string koneksi sebagai parameter ke fromConnectionString. Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

Objek DeviceTwinDevice mewakili perangkat kembar dengan properti dan tagnya.

Contohnya:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

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.

Memperbarui bidang kembar perangkat

Untuk memperbarui bidang kembar perangkat:

1. Gunakan getTwin untuk mengambil bidang kembar perangkat saat ini

   Contoh ini mengambil dan mencetak bidang kembar perangkat:

   // Get the device twin from IoT Hub
   System.out.println("Device twin before update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

2. HashSet Menggunakan objek ke sekelompok pasangan tag kembar add

3. Menggunakan setTags untuk menambahkan sekelompok pasangan tag dari tags objek ke DeviceTwinDevice objek

4. Menggunakan updateTwin untuk memperbarui kembar di hub IoT

   Contoh ini memperbarui tag kembar perangkat wilayah dan pabrik untuk perangkat kembar:

   // Update device twin tags if they are different
   // from the existing values
   String currentTags = device.tagsToString();
   if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {
   
   // Create the tags and attach them to the DeviceTwinDevice object
   Set<Pair> tags = new HashSet<Pair>();
   tags.add(new Pair("region", region));
   tags.add(new Pair("plant", plant));
   device.setTags(tags);
   
   // Update the device twin in IoT Hub
   System.out.println("Updating device twin");
   twinClient.updateTwin(device);
   }
   
   // Retrieve and display the device twin with the tag values from IoT Hub
   System.out.println("Device twin after update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

Membuat kueri kembar perangkat

Bagian ini menunjukkan dua kueri kembar perangkat. Kueri kembar perangkat adalah kueri seperti SQL yang mengembalikan kumpulan hasil kembar perangkat.

Kelas Kueri berisi metode yang dapat digunakan untuk membuat kueri gaya SQL ke IoT Hub untuk kembar, pekerjaan, pekerjaan perangkat, atau data mentah.

Untuk membuat kueri perangkat:

1. Menggunakan createSqlQuery untuk membuat kueri SQL kembar

2. Menggunakan queryTwin untuk menjalankan kueri

3. Gunakan hasNextDeviceTwin untuk memeriksa apakah ada perangkat kembar lain dalam tataan hasil

4. Gunakan getNextDeviceTwin untuk mengambil perangkat kembar berikutnya dari kumpulan hasil

Contoh kueri berikut mengembalikan maksimum 100 perangkat.

Contoh kueri ini hanya memilih perangkat kembar perangkat yang terletak di pabrik Redmond43 .

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Contoh kueri ini menyempurnakan kueri pertama untuk memilih hanya perangkat yang juga tersambung melalui jaringan seluler.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Sampel layanan SDK

Azure IoT SDK for Java menyediakan sampel kerja aplikasi layanan yang menangani tugas kembar perangkat. Untuk informasi selengkapnya, lihat Sampel Kembar Perangkat.

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

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

Aplikasi perangkat dapat membaca dan menulis properti yang dilaporkan kembar, dan diberi tahu tentang perubahan properti kembar yang diinginkan yang diatur oleh aplikasi backend atau IoT Hub.

Kelas IoTHubDeviceClient berisi metode yang dapat digunakan untuk bekerja dengan perangkat kembar.

Bagian ini menjelaskan cara membuat kode aplikasi perangkat yang:

• Mengambil perangkat kembar dan memeriksa properti yang dilaporkan
• Patch melaporkan properti kembar perangkat

Pernyataan impor perangkat

Tambahkan kode ini untuk mengimpor IoTHubDeviceClient fungsi dari azure.iot.device SDK.

from azure.iot.device import IoTHubDeviceClient

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 perangkat ke IoT Hub:

1. Panggil create_from_connection_string untuk menambahkan string koneksi utama perangkat.
2. Panggil sambungkan untuk menyambungkan klien perangkat.

Contohnya:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

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.

Mengambil perangkat kembar dan memeriksa properti yang dilaporkan

Anda dapat mengambil dan memeriksa informasi kembar perangkat termasuk tag dan properti. Informasi kembar perangkat yang diambil cocok dengan data berformat JSON kembar perangkat yang dapat Anda lihat untuk perangkat di portal Azure.

Panggil get_twin untuk mendapatkan perangkat kembar dari layanan Azure IoT Hub. Informasi kembar ditempatkan ke dalam variabel yang dapat dicetak atau diperiksa.

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

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

Patch melaporkan properti kembar perangkat

Anda dapat menerapkan patch untuk memperbarui properti yang dilaporkan perangkat dalam format JSON.

Untuk menerapkan patch untuk memperbarui properti yang dilaporkan:

1. Tetapkan patch JSON properti yang dilaporkan ke variabel.
2. Panggil patch_twin_reported_properties untuk menerapkan patch JSON ke properti yang dilaporkan. Ini adalah panggilan sinkron, yang berarti bahwa fungsi ini tidak kembali sampai patch dikirim ke layanan dan diakui.

Jika patch_twin_reported_properties mengembalikan kesalahan, fungsi ini akan memunculkan kesalahan yang sesuai.

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

Anda juga dapat memanggil metode ini untuk memperbarui kembar perangkat:

• Panggil replace_twin untuk mengganti tag kembar perangkat dan properti yang diinginkan.
• Panggil update_twin untuk memperbarui tag kembar perangkat dan properti yang diinginkan.

Penangan patch properti yang diinginkan masuk

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

Contoh ini menyiapkan handler patch properti yang diinginkan bernama twin_patch_handler.

Contohnya:

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

Menerima twin_patch_handler dan mencetak pembaruan properti yang diinginkan JSON.

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

Sampel perangkat SDK

Azure IoT SDK untuk Python menyertakan sampel berikut:

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

Membuat aplikasi backend

Aplikasi backend terhubung ke perangkat melalui IoT Hub dan dapat membaca properti yang dilaporkan dan diinginkan perangkat, menulis properti yang diinginkan perangkat, dan menjalankan kueri perangkat.

Bagian ini menjelaskan cara membuat aplikasi backend untuk:

• Memperbarui tag kembar dan properti yang diinginkan
• Mengkueri perangkat menggunakan filter pada tag dan properti

Kelas IoTHubRegistryManager mengekspos semua metode yang diperlukan untuk membuat aplikasi backend untuk berinteraksi dengan perangkat ganda dari layanan.

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. Aplikasi Anda memerlukan izin sambungkan layanan untuk memodifikasi properti kembar perangkat yang diinginkan, dan memerlukan izin baca registri untuk mengkueri registri identitas. Tidak ada kebijakan akses bersama default yang hanya berisi kedua izin ini, jadi Anda perlu membuatnya jika belum ada. Berikan kebijakan akses bersama ini string koneksi sebagai parameter ke fromConnectionString. Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

Contohnya:

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

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

Memperbarui tag kembar dan properti yang diinginkan

Anda dapat memperbarui tag kembar perangkat dan properti yang diinginkan dari aplikasi backend secara bersamaan menggunakan update_twin.

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

Contoh ini memperbarui region dan plant menandai informasi, dan mengatur properti yang power_level diinginkan ke 1.

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

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

Membuat kueri kembar perangkat

Anda dapat mengkueri informasi kembar perangkat menggunakan kueri kembar perangkat. Kueri kembar perangkat adalah kueri seperti SQL yang mengembalikan kumpulan hasil kembar perangkat.

Untuk menggunakan kueri kembar perangkat:

1. Gunakan objek QuerySpecification untuk menentukan permintaan kueri seperti SQL.

2. Gunakan query_iot_hub untuk mengkueri IoTHub dan mengambil informasi kembar perangkat menggunakan spesifikasi kueri seperti SQL.

Contoh ini menjalankan dua kueri. Yang pertama hanya memilih perangkat kembar perangkat yang terletak di Redmond43 pabrik, dan yang kedua menyempurnakan kueri untuk memilih hanya perangkat yang juga terhubung melalui jaringan seluler. Hasil dicetak setelah setiap kueri.

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

print()

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

print()

Sampel layanan SDK

Azure IoT SDK untuk Python menyediakan sampel kerja aplikasi layanan yang menangani tugas kembar perangkat. Untuk informasi selengkapnya, lihat Sampel Kueri Manajer Registri.

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

Membuat aplikasi perangkat

Aplikasi perangkat dapat membaca dan menulis properti yang dilaporkan kembar, dan diberi tahu tentang perubahan properti kembar yang diinginkan yang diatur oleh aplikasi backend atau IoT Hub.

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

• Mengambil perangkat kembar dan memeriksa properti yang dilaporkan
• Memperbarui properti kembar perangkat yang dilaporkan
• Menerima pemberitahuan perubahan properti yang diinginkan

Menginstal paket SDK perangkat

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

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

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

npm install azure-iot-device-mqtt --save

Untuk informasi selengkapnya tentang perbedaan antara dukungan MQTT, AMQP, dan HTTPS, lihat Panduan komunikasi cloud-to-device dan Pilih protokol komunikasi.

Membuat modul klien

Buat Client modul menggunakan paket yang diinstal.

Contohnya:

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

Membuat modul protokol

Buat Protocol modul menggunakan paket transportasi yang diinstal.

Contoh ini menetapkan protokol MQTT:

const Protocol = require('azure-iot-device-mqtt').Mqtt;

Menambahkan string koneksi perangkat dan protokol transportasi

Panggil dariConnectionString untuk menyediakan parameter koneksi perangkat:

• connStr - string koneksi yang merangkum izin "device connect" untuk hub IoT. string koneksi berisi nama host, ID perangkat & kunci akses bersama dalam format ini: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
• transportCtor - Protokol transportasi.

Contoh ini menggunakan Mqtt protokol transportasi:

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

Buka koneksi ke IoT Hub

Gunakan metode terbuka untuk membuka koneksi antara perangkat IoT dan IoT Hub. Gunakan .catch(err) untuk menangkap kesalahan dan menjalankan kode handler.

Contohnya:

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Mengambil perangkat kembar dan memeriksa properti yang dilaporkan

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

Contohnya:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Memperbarui properti kembar perangkat yang dilaporkan

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

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

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Menerima pemberitahuan perubahan properti yang diinginkan

Buat pendengar peristiwa pembaruan properti yang diinginkan yang dijalankan ketika properti yang diinginkan diubah di perangkat dengan meneruskan nama metode handler panggilan balik ke twin.on.

Pendengar peristiwa properti yang diinginkan dapat mengambil salah satu formulir berikut:

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

Menerima semua patch dengan satu penanganan aktivitas

Anda dapat membuat pendengar untuk menerima perubahan properti yang diinginkan.

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

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

Menerima peristiwa jika ada perubahan di bawah pengelompokan properti

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

Contohnya:

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

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

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

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

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

Menerima peristiwa untuk perubahan properti tunggal

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

1. Aplikasi backend menerapkan patch properti yang diinginkan ini:

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

2. Pendengar hanya memicu saat fanOn properti berubah:

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

Sampel SDK perangkat

Azure IoT SDK untuk Node.js berisi dua sampel kembar perangkat:

• Kembar perangkat sampel sederhana

• Kembar perangkat sampel sederhana dengan SAS

Membuat aplikasi backend

Aplikasi backend terhubung ke perangkat melalui IoT Hub dan dapat membaca properti yang dilaporkan dan diinginkan perangkat, menulis properti yang diinginkan perangkat, dan menjalankan kueri perangkat.

Bagian ini menjelaskan cara membuat aplikasi backend yang:

• Mengambil dan memperbarui perangkat kembar
• Membuat kueri kembar perangkat

Menginstal paket SDK layanan

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

npm install azure-iothub --save

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

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. Aplikasi Anda memerlukan izin sambungkan layanan untuk memodifikasi properti kembar perangkat yang diinginkan, dan memerlukan izin baca registri untuk mengkueri registri identitas. Tidak ada kebijakan akses bersama default yang hanya berisi kedua izin ini, jadi Anda perlu membuatnya jika belum ada. Berikan kebijakan akses bersama ini string koneksi sebagai parameter ke fromConnectionString. Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.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.

Mengambil dan memperbarui perangkat kembar

Anda dapat membuat patch yang berisi tag dan pembaruan properti yang diinginkan untuk perangkat kembar.

Untuk memperbarui perangkat kembar:

1. Panggil getTwin untuk mengambil objek kembar perangkat.

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

1. Panggil pembaruan untuk memperbarui perangkat kembar dengan patch.

Dalam contoh ini, perangkat kembar diambil untuk myDeviceId, maka patch diterapkan ke kembar yang berisi location pembaruan tag .region: 'US', plant: 'Redmond43'

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Membuat kueri kembar perangkat

Anda dapat membuat kueri perangkat seperti SQL untuk mengumpulkan informasi dari kembar perangkat.

Gunakan createQuery untuk membuat kueri yang dapat dijalankan pada instans hub IoT untuk menemukan informasi tentang perangkat atau pekerjaan.

createQuery mencakup dua parameter:

• sqlQuery - Kueri yang ditulis sebagai string SQL.
• pageSize - Jumlah hasil yang diinginkan per halaman (opsional. default: 1000, maks: 10000).

Jika parameter pageSize ditentukan, objek kueri berisi hasMoreResults properti boolean yang dapat Anda periksa dan gunakan nextAsTwin metode untuk mendapatkan halaman hasil kembar berikutnya sebanyak yang diperlukan untuk mengambil semua hasil. Metode yang disebut next tersedia untuk hasil yang bukan kembar perangkat, misalnya, hasil kueri agregasi.

Contoh kueri ini hanya memilih perangkat kembar perangkat yang terletak di Redmond43 pabrik.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

Contoh kueri ini menyempurnakan kueri pertama untuk memilih hanya perangkat yang juga tersambung melalui jaringan seluler.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Sampel SDK Layanan

Azure IoT SDK untuk Node.js menyediakan sampel kerja aplikasi layanan yang menangani tugas kembar perangkat. Untuk informasi selengkapnya, lihat Device Twin Backend Service - Proyek ini digunakan untuk mengirim pembaruan patch kembar perangkat untuk perangkat tertentu.