Menggunakan model IoT Plug and Play dalam solusi IoT

Artikel
08/30/2024

Artikel ini menjelaskan cara mengidentifikasi ID model perangkat IoT Plug and Play dalam solusi IoT lalu mengambil definisi modelnya.

Ada dua kategori solusi IoT yang luas:

Solusi yang dibuat khusus berfungsi dengan serangkaian model yang diketahui untuk perangkat IoT Plug and Play yang terhubung ke solusi. Anda menggunakan model ini saat mengembangkan solusi.
Solusi berbasis model berfungsi dengan model perangkat IoT Plug and Play apa pun. Membangun solusi berbasis model lebih kompleks, tetapi manfaatnya adalah solusi Anda berfungsi dengan perangkat apa pun yang ditambahkan di masa depan. Solusi IoT berbasis model mengambil model dan menggunakannya untuk menentukan telemetri, properti, dan perintah yang diterapkan perangkat.

Untuk menggunakan model IoT Plug and Play, solusi IoT:

Mengidentifikasi ID model dari model yang diimplementasikan oleh perangkat IoT Plug and Play, modul, atau modul IoT Edge yang tesambung ke solusi.
Menggunakan ID model untuk mengambil definisi model perangkat yang tersambung dari repositori model atau penyimpanan kustom.

Identifikasi ID model

Saat perangkat IoT Plug and Play tersambung ke IoT Hub, perangkat mendaftarkan ID model dari model yang diimplementasikan dengan IoT Hub.

IoT Hub memberi tahu solusi dengan ID model perangkat sebagai bagian dari alur koneksi perangkat.

Solusi bisa mendapatkan ID model perangkat IoT Plug and Play dengan menggunakan salah satu dari tiga metode berikut:

API Get Device Twin

Solusi dapat menggunakan Get Device Twin API untuk mengambil ID model perangkat IoT Plug and Play.

Tip

Untuk modul dan modul IoT Edge, gunakan ModuleClient.getTwin.

Dalam cuplikan respons device twin berikut, modelId berisi ID model perangkat IoT Plug and Play:

{
    "deviceId": "sample-device",
    "etag": "AAAAAAAAAAc=",
    "deviceEtag": "NTk0ODUyODgx",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00Z",
    "connectionState": "Disconnected",
    "lastActivityTime": "2020-07-17T06:12:26.8402249Z",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "modelId": "dtmi:com:example:TemperatureController;1",
    "version": 15,
    "properties": {...}
    }
}

API Get Digital Twin

Solusi dapat menggunakan Get Digital Twin API untuk mengambil ID model dari model yang diimplementasikan oleh perangkat IoT Plug and Play.

Dalam cuplikan respons digital twin berikut, $metadata.$model berisi ID model perangkat IoT Plug and Play:

{
    "$dtId": "sample-device",
    "$metadata": {
        "$model": "dtmi:com:example:TemperatureController;1",
        "serialNumber": {
            "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
        }
    }
}

Notifikasi kejadian perubahan digital twin

Koneksi perangkat mengakibatkan notifikasi kejadian perubahan Digital Twin. Solusi harus berlangganan notifikasi kejadian ini. Untuk mempelajari cara mengaktifkan perutean untuk kejadian digital twin, lihat Menggunakan perutean pesan IoT Hub untuk mengirim pesan perangkat ke cloud ke titik akhir yang berbeda.

Solusi dapat menggunakan kejadian yang ditunjukkan dalam cuplikan berikut guna mempelajari perangkat IoT Plug and Play yang tersambung dan mendapatkan ID modelnya:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/22/2020 8:02:27 PM
iothub-message-source:digitalTwinChangeEvents
correlation-id:100f322dc2c5
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:com:example:TemperatureController;1"
  }
]

Mengambil definisi model

Solusi menggunakan ID model yang diidentifikasi sebelumnya untuk mengambil definisi model yang sesuai.

Solusi bisa mendapatkan definisi model dengan menggunakan salah satu opsi berikut:

Repositori model

Solusi dapat mengambil model DTDL dari repositori model perangkat (DMR). DMR adalah repositori publik, yang dihosting oleh Microsoft, yang berisi kumpulan model DTDL yang dikumpulkan. Model perangkat publik yang disimpan di DMR tersedia bagi semua orang untuk dikonsumsi dan diintegrasikan dalam aplikasi mereka dari titik https://devicemodels.azure.comakhir publik .

Setelah Anda mengidentifikasi ID model untuk koneksi perangkat baru, ikuti langkah berikut:

Ambil definisi model menggunakan ID model dari repositori model. Untuk informasi selengkapnya, lihat Mengatasi model.
Dengan menggunakan definisi model dari perangkat yang tersambung, Anda dapat memperkirakan kemampuan perangkat.
Dengan menggunakan kemampuan perangkat yang dijumlahkan, Anda dapat memungkinkan pengguna berinteraksi dengan perangkat.

Mengatasi model

Konvensi DMR mencakup artefak lain untuk menyederhanakan konsumsi model yang dihosting. Berbagai fitur ini opsional untuk repositori kustom atau privat.

Indeks. Semua DTMIs yang tersedia diekspos melalui indeks yang disusun oleh urutan file json, misalnya: https://devicemodels.azure.com/index.page.2.json
Diperluas. File dengan semua dependensi tersedia untuk setiap antarmuka, misalnya: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Metadata. File ini mengekspos atribut kunci dari repositori dan disegarkan secara berkala dengan salinan bayangan model terbaru yang diterbitkan. Ini termasuk fitur yang diimplementasikan repositori seperti apakah indeks model atau file model yang diperluas tersedia. Anda dapat mengakses metadata DMR di https://devicemodels.azure.com/metadata.json

Untuk mengakses model DTDL publik secara terprogram di DMR, Anda dapat menggunakan yang ModelsRepositoryClient tersedia dalam paket NuGet Azure.IoT.ModelsRepository. Klien ini dikonfigurasi secara default untuk mengkueri DMR publik yang tersedia di devicemodels.azure.com dan dapat dikonfigurasi ke repositori kustom apa pun.

Klien menerima DTMI sebagai input dan mengembalikan kamus dengan semua antarmuka yang diperlukan:

using Azure.IoT.ModelsRepository;

var client = new ModelsRepositoryClient();
ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

Output yang diharapkan menampilkan DTMI dari tiga antarmuka yang ditemukan dalam rantai dependensi:

dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1

ModelsRepositoryClient dapat dikonfigurasi untuk mengkueri DMR kustom--tersedia melalui https--dan untuk menentukan resolusi dependensi dengan menggunakan ModelDependencyResolution bendera:

Dinonaktifkan. Mengembalikan antarmuka yang ditentukan saja, tanpa dependensi apa pun.
Diaktifkan. Mengembalikan semua antarmuka dalam rantai dependensi

Tip

Repositori kustom mungkin tidak mengekspos .expanded.json file. Ketika file ini tidak tersedia, klien akan mundur untuk memproses setiap dependensi secara lokal.

Kode sampel berikut menunjukkan cara menginisialisasi ModelsRepositoryClient dengan menggunakan URL dasar repositori kustom, dalam hal ini menggunakan raw URL dari GITHub API tanpa menggunakan expanded formulir karena tidak tersedia di raw titik akhir. AzureEventSourceListener diinisialisasi untuk memeriksa permintaan HTTP yang dilakukan oleh klien:

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

var client = new ModelsRepositoryClient(
    new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));

ModelResult model = await client.GetModelAsync(
    "dtmi:com:example:TemperatureController;1", 
    dependencyResolution: ModelDependencyResolution.Enabled);

model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

Ada lebih banyak sampel yang tersedia di repositori GitHub Azure SDK: Azure.Iot.ModelsRepository/samples.

Penyimpanan kustom

Solusi dapat menyimpan definisi model ini dalam sistem file lokal, di penyimpanan file publik, atau menggunakan implementasi kustom.

Setelah Anda mengidentifikasi ID model untuk koneksi perangkat baru, ikuti langkah berikut:

Ambil definisi model menggunakan ID model dari penyimpanan kustom Anda.
Dengan menggunakan definisi model dari perangkat yang tersambung, Anda dapat memperkirakan kemampuan perangkat.
Dengan menggunakan kemampuan perangkat yang dijumlahkan, Anda dapat memungkinkan pengguna berinteraksi dengan perangkat.

Langkah berikutnya

Sekarang setelah Anda mempelajari cara mengintegrasikan model IoT Plug and Play dalam solusi IoT, beberapa langkah berikutnya yang disarankan adalah:

Bagikan melalui