Menanggapi kejadian IoT Hub menggunakan Event Grid untuk memicu tindakan

Azure IoT Hub terintegrasi dengan Azure Event Grid, sehingga pengguna dapat mengirim notifikasi kejadian ke layanan lain dan memicu proses hilir. Konfigurasikan aplikasi bisnis Anda untuk mendengarkan kejadian IoT Hub sehingga Anda dapat menanggapi kejadian penting dengan cara yang andal, dapat diskalakan, dan aman. Misalnya, bangun aplikasi yang memperbarui database, membuat tiket kerja, dan mengirimkan pemberitahuan email setiap kali perangkat IoT baru didaftarkan ke hub IoT Anda.

Azure Event Grid adalah layanan perutean kejadian yang dikelola penuh yang menggunakan model publikasi-berlangganan. Event Grid memiliki dukungan bawaan untuk layanan Azure seperti Azure Functions dan Azure Logic Apps, dan dapat memberikan pemberitahuan kejadian ke layanan non-Azure menggunakan webhook. Untuk daftar lengkap handler peristiwa yang didukung Event Grid, lihat Pengenalan Azure Event Grid.

Azure Event Grid architecture

Ketersediaan regional

Integrasi Event Grid tersedia untuk hub IoT yang terletak di wilayah tempat Event Grid didukung. Untuk daftar wilayah terbaru, lihat Pengantar Azure Event Grid.

Jenis kejadian

Azure IoT Hub menerbitkan jenis kejadian berikut:

Jenis peristiwa Deskripsi
Microsoft.Devices.DeviceCreated Diterbitkan saat perangkat didaftarkan ke hub IoT.
Microsoft.Devices.DeviceDeleted Diterbitkan saat perangkat dihapus dari hub IoT.
Microsoft.Devices.DeviceConnected Diterbitkan saat perangkat disambungkan ke hub IoT.
Microsoft.Devices.DeviceDisconnected Diterbitkan saat perangkat terputus sambungannya dari hub IoT.
Microsoft.Devices.DeviceTelemetry Diterbitkan saat pesan telemetri dikirim ke hub IoT

Gunakan portal Microsoft Azure atau Azure CLI untuk mengonfigurasi kejadian mana yang akan diterbitkan dari setiap hub IoT. Misalnya, coba tutorial Mengirim pemberitahuan email tentang kejadian Azure IoT Hub menggunakan Azure Logic Apps.

Skema peristiwa

Kejadian Azure IoT Hub berisi semua informasi yang Anda perlukan untuk merespons perubahan dalam siklus hidup perangkat Anda. Anda dapat mengidentifikasi kejadian IoT Hub dengan memeriksa apakah properti eventType dimulai dengan Microsoft.Devices. Untuk informasi selanjutnya tentang cara menggunakan properti kejadian Event Grid, lihat skema kejadian Event Grid.

Skema yang tersambung dengan perangkat

Contoh berikut menunjukkan skema kejadian yang tersambung perangkat:

[{  
  "id": "f6bbf8f4-d365-520d-a878-17bf7238abd8",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceConnected",
  "eventTime": "2018-06-02T19:17:44.4383997Z",
  "data": {
      "deviceConnectionStateEventInfo": {
        "sequenceNumber":
          "000000000000000001D4132452F67CE200000002000000000000000000000001"
      },
    "hubName": "egtesthub1",
    "deviceId": "LogicAppTestDevice",
    "moduleId" : "DeviceModuleID",
  }, 
  "dataVersion": "1",
  "metadataVersion": "1"
}]

Skema Telemetri Perangkat

Pesan telemetri perangkat harus dalam format JSON yang valid dengan contentType diatur ke application/json dan contentEncoding diatur ke UTF-8 di properti sistem pesan. Kedua properti ini tidak peka huruf besar/kecil. Jika pengoden konten tidak diatur, IoT Hub akan menulis pesan dalam format berenkode base 64.

Anda dapat memperkaya kejadian telemetri perangkat sebelum dipublikasikan ke Event Grid dengan memilih titik akhir sebagai Event Grid. Untuk informasi selanjutnya, lihat Gambaran Umum Pengayaan Pesan.

Contoh berikut menunjukkan skema kejadian telemetri perangkat:

[{  
  "id": "9af86784-8d40-fe2g-8b2a-bab65e106785",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceTelemetry",
  "eventTime": "2019-01-07T20:58:30.48Z",
  "data": {
      "body": {
          "Weather": {
              "Temperature": 900
            },
            "Location": "USA"
        },
        "properties": {
            "Status": "Active"
        },
        "systemProperties": {
          "iothub-content-type": "application/json",
          "iothub-content-encoding": "utf-8",
          "iothub-connection-device-id": "d1",
          "iothub-connection-auth-method": "{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
          "iothub-connection-auth-generation-id": "123455432199234570",
          "iothub-enqueuedtime": "2019-01-07T20:58:30.48Z",
          "iothub-message-source": "Telemetry"
        }
  },
  "dataVersion": "",
  "metadataVersion": "1"
}]

Skema yang dibuat perangkat

Contoh berikut menunjukkan skema kejadian yang dibuat perangkat:

[{
  "id": "56afc886-767b-d359-d59e-0da7877166b2",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceCreated",
  "eventTime": "2018-01-02T19:17:44.4383997Z",
  "data": {
    "twin": {
      "deviceId": "LogicAppTestDevice",
      "etag": "AAAAAAAAAAE=",
      "deviceEtag":"null",
      "status": "enabled",
      "statusUpdateTime": "0001-01-01T00:00:00",
      "connectionState": "Disconnected",
      "lastActivityTime": "0001-01-01T00:00:00",
      "cloudToDeviceMessageCount": 0,
      "authenticationType": "sas",
      "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
      },
      "version": 2,
      "properties": {
        "desired": {
          "$metadata": {
            "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
          },
          "$version": 1
        },
        "reported": {
          "$metadata": {
            "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
          },
          "$version": 1
        }
      }
    },
    "hubName": "egtesthub1",
    "deviceId": "LogicAppTestDevice"
  },
  "dataVersion": "1",
  "metadataVersion": "1"
}]

Peringatan

Data kembar yang terkait dengan acara pembuatan perangkat adalah konfigurasi default dan tidak boleh diandalkan untuk properti perangkat aktual dan lainnya dalam perangkat yang baru dibuat. Untuk authenticationType dan properti perangkat lainnya di perangkat yang baru dibuat, gunakan API Register Manager yang disediakan di SDK Azure IoT.

Untuk deskripsi terperinci dari setiap properti, lihat Skema kejadian Azure Event Grid untuk IoT Hub.

Memfilter kejadian

Langganan kejadian IoT Hub dapat memfilter kejadian berdasarkan jenis kejadian, konten data, dan subjek, yang merupakan nama perangkat.

Event Grid memungkinkan pemfilteran pada jenis kejadian, subjek, dan konten data. Saat membuat langganan Event Grid, Anda dapat memilih untuk berlangganan kejadian IoT yang dipilih. Filter subjek dalam Event Grid berfungsi berdasarkan kecocokan Dimulai Dengan (awalan) dan Berakhir Dengan (akhiran). Filter menggunakan operator AND, sehingga kejadian dengan subjek yang cocok dengan awalan dan akhiran dikirimkan kepada pelanggan.

Subjek Kejadian IoT menggunakan format:

devices/{deviceId}

Event Grid juga memungkinkan pemfilteran pada atribut setiap kejadian, termasuk konten data. Hal ini memungkinkan Anda untuk memilih kejadian apa yang dikirimkan berdasarkan konten pesan telemetri. Silakan lihat pemfilteran tingkat lanjut untuk melihat contoh. Untuk memfilter pada isi pesan telemetri, Anda harus mengatur contentType menjadi application/json dan contentEncoding menjadi UTF-8 di properti sistem pesan. Kedua properti ini tidak peka huruf besar/kecil.

Untuk kejadian non-telemetri seperti DeviceConnected, DeviceDisconnected, DeviceCreated, dan DeviceDeleted, pemfilteran Event Grid dapat digunakan saat membuat langganan. Untuk kejadian telemetri, selain pemfilteran di Event Grid, pengguna juga dapat memfilter pada perangkat kembar, properti dan isi pesan melalui kueri perutean pesan.

Saat Anda berlangganan kejadian telemetri melalui Event Grid, Azure IoT Hub membuat rute pesan default untuk mengirim pesan perangkat jenis sumber data ke Event Grid. Untuk informasi selengkapnya tentang perutean pesan, lihat perutean pesan IoT Hub. Rute ini akan terlihat di portal di bawah IoT Hub > Perutean Pesan. Hanya satu rute ke Event Grid yang dibuat terlepas dari jumlah langganan EG yang dibuat untuk kejadian telemetri. Jadi, jika Anda memerlukan beberapa langganan dengan filter yang berbeda, Anda dapat menggunakan operator OR dalam kueri ini pada rute yang sama. Pembuatan dan penghapusan rute dikendalikan melalui langganan kejadian telemetri melalui Event Grid. Anda tidak dapat membuat atau menghapus rute ke Event Grid menggunakan Perutean Pesan IoT Hub.

Untuk memfilter pesan sebelum data telemetri dikirim, Anda bisa memperbarui kueri perutean Anda. Perhatikan bahwa kueri perutean dapat diterapkan ke isi pesan hanya jika isinya adalah JSON. Anda juga harus mengatur contentType menjadi application/json dan contentEncoding menjadi UTF-8 dalam properti sistem pesan.

Batasan untuk acara yang terhubung ke perangkat dan perangkat yang terputus

Untuk menerima kejadian status sambungan perangkat, perangkat harus memanggil operasi pengiriman telemetri dari perangkat ke cloud atau penerimaan pesan dari cloud ke perangkat dengan IoT Hub. Namun, jika perangkat menggunakan protokol AMQP untuk tersambung dengan Azure IoT Hub, kami menyarankan perangkat untuk memanggil operasi penerimaan pesan dari cloud ke perangkat. Jika tidak, pemberitahuan status sambungannya mungkin tertunda beberapa menit. Jika perangkat Anda tersambung dengan protokol MQTT, IoT Hub akan membuat tautan cloud ke perangkat tetap terbuka. Untuk membuka tautan cloud ke perangkat untuk AMQP, panggil Receive Async API.

Tautan perangkat ke cloud tetap terbuka selama perangkat mengirim telemetri.

Jika perangkat sering tersambung dan terputus, IoT Hub tidak mengirim setiap status koneksi, tetapi menerbitkan status koneksi saat ini yang diambil pada rekam jepret berkala 60 detik. Baik menerima kejadian status sambungan yang sama dengan nomor urut yang berbeda maupun kejadian status sambungan yang berbeda, keduanya berarti bahwa ada perubahan dalam status sambungan perangkat.

Tips untuk menggunakan kejadian

Aplikasi yang menangani kejadian IoT Hub harus mengikuti praktik yang disarankan ini:

  • Beberapa langganan dapat dikonfigurasi untuk merutekan kejadian ke penanganan aktivitas yang sama, sehingga jangan anggap kejadian berasal dari sumber tertentu. Selalu periksa topik pesan untuk memastikan bahwa itu berasal dari hub IoT yang Anda harapkan.

  • Jangan berasumsi bahwa semua kejadian yang Anda terima adalah jenis yang Anda harapkan. Selalu periksa eventType sebelum memproses pesan.

  • Pesan dapat diterima tidak sesuai urutan atau setelah penundaan. Gunakan bidang etag untuk memahami apakah informasi Anda tentang objek sudah diperbarui untuk kejadian yang dibuat perangkat atau yang dihapus perangkat.

Langkah berikutnya