Pelajari cara menyebarkan modul dan membuat rute di IoT Edge

Berlaku untuk: IoT Edge 1.5

Penting

IoT Edge 1.5 LTS adalah rilis didukung. IoT Edge 1.4 LTS mencapai akhir masa pakai pada 12 November 2024. Jika Anda menggunakan rilis sebelumnya, lihat Update IoT Edge.

Setiap perangkat IoT Edge menjalankan setidaknya dua modul: $edgeAgent dan $edgeHub, yang merupakan bagian dari runtime IoT Edge. Perangkat IoT Edge dapat menjalankan beberapa modul untuk proses yang berbeda. Gunakan manifes penyebaran untuk memberi tahu perangkat Anda modul mana yang akan diinstal dan cara menyiapkannya untuk bekerja sama.

Manifes penyebaran adalah dokumen JSON yang menjelaskan:

• Kembar modul IoT Edge, yang mencakup tiga komponen:
  • Gambar kontainer untuk setiap modul yang berjalan pada perangkat.
  • Kredensial untuk menggunakan registri kontainer privat yang memiliki image modul.
  • Petunjuk tentang bagaimana setiap modul dibuat dan dikelola.
• Modul kembar IoT Edge hub, yang mencakup bagaimana pesan mengalir di antara modul dan ke IoT Hub.
• Properti yang diinginkan dari modul kembar tambahan (opsional).

Semua perangkat IoT Edge memerlukan manifes penyebaran. Runtime IoT Edge yang baru diinstal menunjukkan kode error sampai Anda mengonfigurasi manifes yang valid.

Dalam tutorial Azure IoT Edge, Anda membuat manifes penyebaran dengan menggunakan wizard di portal Azure IoT Edge. Anda juga dapat menerapkan manifes penyebaran secara terprogram dengan menggunakan REST atau SDK Layanan IoT Hub. Untuk informasi selengkapnya, lihat Memahami Penyebaran IoT Edge.

Membuat manifes penyebaran

Manifes penyebaran adalah daftar modul kembar yang ditetapkan dengan properti yang diinginkan. Ini memberikan instruksi kepada perangkat IoT Edge atau grup perangkat tentang modul mana yang akan diinstal dan cara menyiapkannya. Manifes penyebaran mencakup properti yang diinginkan untuk setiap kembaran modul. Perangkat IoT Edge melaporkan properti yang dilaporkan untuk setiap modul.

Setiap manifes penyebaran memerlukan dua modul: $edgeAgent dan $edgeHub. Modul ini adalah bagian dari runtime IoT Edge yang mengelola perangkat IoT Edge dan modul yang berjalan di atasnya. Untuk informasi selengkapnya tentang modul ini, lihat Menjabarkan runtime IoT Edge dan arsitekturnya.

Anda dapat menambahkan hingga 50 modul tambahan untuk dijalankan pada perangkat IoT Edge, selain dua modul runtime.

Manifes penyebaran yang hanya memiliki runtime IoT Edge ($edgeAgent dan $edgeHub) adalah valid.

Manifes penyebaran menggunakan format ini:

{
  "modulesContent": {
    "$edgeAgent": { // required
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": { //required
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules and to IoT Hub
      }
    },
    "module1": {  // optional
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  // optional
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

Mengonfigurasi modul

Tentukan bagaimana runtime IoT Edge menginstal modul dalam penyebaran Anda. Agen IoT Edge adalah komponen runtime yang mengelola penginstalan, pembaruan, dan pelaporan status untuk perangkat IoT Edge. Jadi, modul kembar $edgeAgent memiliki informasi konfigurasi dan manajemen untuk semua modul. Informasi ini mencakup parameter konfigurasi untuk agen IoT Edge itu sendiri.

Properti $edgeAgent menggunakan format ini:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // let the IoT Edge agent use container images that aren't public
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            // configuration and management details
          },
          "edgeHub": {
            // configuration and management details
          }
        },
        "modules": {
          "module1": {
            // configuration and management details
          },
          "module2": {
            // configuration and management details
          }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Skema agen IoT Edge versi 1.1 dirilis dengan IoT Edge versi 1.0.10 dan memungkinkan Anda mengatur urutan startup modul. Gunakan skema versi 1.1 untuk penyebaran IoT Edge apa pun yang menjalankan versi 1.0.10 atau yang lebih baru.

Konfigurasi dan pengelolaan modul

Tentukan modul mana yang berjalan pada perangkat IoT Edge dan cara menyiapkan dan mengelolanya di daftar properti yang diinginkan agen IoT Edge.

Untuk daftar lengkap properti yang diinginkan yang dapat atau harus Anda sertakan, lihat Properti agen IoT Edge dan hub IoT Edge.

Contohnya:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": { ... },
        "systemModules": {
          "edgeAgent": { ... },
          "edgeHub": { ... }
        },
        "modules": {
          "module1": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "myacr.azurecr.io/module1:latest",
              "createOptions": "{}"
            }
          },
          "module2": { ... }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Setiap modul memiliki properti pengaturan dengan gambar modul, alamat untuk gambar kontainer dalam registri kontainer, dan createOptions apa pun untuk menyiapkan gambar saat startup. Untuk informasi selengkapnya, lihat Cara mengonfigurasi opsi pembuatan kontainer untuk modul IoT Edge.

Modul edgeHub dan modul kustom juga memiliki tiga properti yang memberi tahu agen IoT Edge cara mengelolanya:

• Status: Apakah modul berjalan atau berhenti saat pertama kali disebarkan. Harus diisi.

• RestartPolicy: Kapan dan jika agen IoT Edge memulai ulang modul jika berhenti. Jika modul berhenti tanpa kesalahan apa pun, modul tidak dimulai ulang secara otomatis. Untuk informasi selengkapnya, lihat Docker Docs - Mulai kontainer secara otomatis. Harus diisi.

• StartupOrder: Diperkenalkan dalam IoT Edge versi 1.0.10. Urutan yang digunakan agen IoT Edge untuk memulai modul saat pertama kali disebarkan. Urutan menggunakan bilangan bulat, di mana modul dengan nilai startup 0 dimulai terlebih dahulu dan kemudian angka yang lebih tinggi mengikuti. Modul $edgeAgent tidak memiliki nilai startup karena selalu dimulai terlebih dahulu. Opsional.

  Agen IoT Edge memulai modul-modul sesuai dengan urutan nilai pengaktifan, tetapi tidak menunggu setiap modul diinisialisasi sepenuhnya sebelum memulai modul berikutnya.

  Pengaturan urutan startup dapat membantu jika beberapa modul bergantung pada modul lain. Misalnya, Anda mungkin ingin modul edgeHub dimulai terlebih dahulu sehingga siap merutekan pesan saat modul lain dimulai. Atau Anda mungkin ingin memulai modul penyimpanan sebelum memulai modul yang mengirim data ke modul tersebut. Tetapi selalu rancang modul Anda untuk menangani kegagalan modul lain. Kontainer dapat berhenti dan memulai ulang kapan saja, dan berapa kali.

  Catatan

  Mengubah properti modul akan memulai ulang modul tersebut. Misalnya, mulai ulang terjadi jika Anda mengubah properti untuk:

  • gambar modul
  • Opsi pembuatan kontainer Docker
  • variabel lingkungan
  • kebijakan hidupkan ulang
  • kebijakan penarikan gambar
  • versi
  • urutan startup

  Jika Anda tidak mengubah properti modul apa pun, sebuah mulai ulang modul tidak akan terjadi.

Menyatakan rute

IoT Edge hub mengelola komunikasi antara modul, IoT Hub, dan perangkat hilir. Modul kembar $edgeHub memiliki properti yang diinginkan yang disebut routes yang menentukan bagaimana pesan bergerak dalam penyebaran. Anda dapat menyiapkan beberapa rute dalam penyebaran yang sama.

Deklarasikan rute dalam properti yang diinginkan $edgeHub menggunakan sintaks ini:

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

IoT Edge skema hub versi 1 dirilis dengan IoT Edge versi 1.0.10 dan memungkinkan Anda mengatur prioritas rute dan waktu hidup. Gunakan skema versi 1.1 untuk penyebaran IoT Edge apa pun yang menjalankan versi 1.0.10 atau yang lebih baru.

Setiap rute memerlukan sumber untuk pesan masuk dan sink untuk pesan keluar. Kondisi ini bersifat opsional dan memungkinkan Anda memfilter pesan.

Tetapkan prioritas ke rute untuk memproses pesan penting terlebih dahulu. Fitur ini membantu ketika koneksi upstream lemah atau terbatas dan Anda perlu memprioritaskan data krusial daripada pesan telemetri standar.

Sumber

Sumber menentukan tempat pesan berasal. IoT Edge dapat merutekan pesan dari modul atau perangkat hilir.

Dengan menggunakan SDK IoT, modul dapat mengatur antrean output tertentu untuk pesan mereka dengan menggunakan ModuleClient kelas . Antrean output tidak diperlukan, tetapi membantu mengelola beberapa rute. Perangkat hilir menggunakan kelas DeviceClient di SDK IoT untuk mengirim pesan ke perangkat gateway IoT Edge, sama seperti mereka mengirim pesan ke IoT Hub. Untuk informasi selengkapnya, lihat Mahami dan gunakan SDK Azure IoT Hub.

Properti sumber dapat menggunakan salah satu nilai ini:

Sumber	Deskripsi
/*	Semua pesan perangkat ke cloud atau pemberitahuan perubahan kembar dari modul atau perangkat hilir apa pun.
/twinChangeNotifications	Setiap perubahan kembar (properti yang dilaporkan) yang berasal dari modul atau perangkat hilir apa pun.
/messages/*	Pesan perangkat ke cloud apa pun yang dikirim oleh modul dengan atau tanpa output, atau oleh perangkat hilir (downstream device).
/messages/modules/*	Pesan perangkat ke cloud apa pun yang dikirim oleh modul melalui beberapa atau tanpa output.
/messages/modules/<moduleId>/*	Pesan apa pun dari perangkat ke cloud yang dikirim oleh modul tertentu melalui beberapa output atau tanpa output.
/messages/modules/<moduleId>/outputs/*	Pesan apa pun dari perangkat ke cloud yang dikirim oleh modul tertentu melalui output tertentu.
/messages/modules/<moduleId>/outputs/<output>	Pesan perangkat ke cloud apa pun yang dikirim oleh modul tertentu melalui output tertentu.

Kondisi

Kondisi bersifat opsional dalam pernyataan rute. Untuk meneruskan semua pesan dari sumber ke sink, hilangkan klausa WHERE . Atau, gunakan bahasa kueri IoT Hub untuk memfilter pesan atau jenis pesan yang memenuhi kondisi. IoT Edge rute tidak mendukung pemfilteran pesan berdasarkan tag atau properti kembar.

Pesan yang berpindah antar modul dalam IoT Edge menggunakan format yang sama dengan pesan antara perangkat Anda dan Azure IoT Hub. Semua pesan menggunakan format JSON dan memiliki parameter systemProperties, appProperties, dan body .

Buat kueri di sekitar salah satu dari tiga parameter dengan menggunakan sintaks ini:

• Properti sistem: $<propertyName> atau {$<propertyName>}
• Properti aplikasi: <propertyName>
• Properti badan: $body.<propertyName>

Untuk contoh cara membuat kueri untuk properti pesan, lihat Ekspresi kueri rute pesan perangkat ke cloud.

Misalnya, Anda mungkin ingin memfilter pesan yang tiba di perangkat gateway dari perangkat hilir. Pesan yang dikirim dari modul menyertakan properti sistem yang disebut connectionModuleId. Untuk merutekan pesan dari perangkat hilir langsung ke IoT Hub dan mengecualikan pesan modul, gunakan rute ini:

FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream

Wastafel

Sink menentukan tempat untuk mengirim pesan. Hanya modul dan IoT Hub yang dapat menerima pesan. Anda tidak dapat merutekan pesan ke perangkat lain. Properti sink tidak mendukung karakter pengganti.

Properti sink dapat menggunakan salah satu nilai ini:

Wastafel	Deskripsi
$upstream	Kirim pesan ke IoT Hub
BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")	Mengirim pesan ke input tertentu dari modul tertentu

IoT Edge memberikan jaminan setidaknya sekali. IoT Edge hub menyimpan pesan secara lokal jika rute tidak dapat mengirimkan pesan ke sink-nya. Misalnya, jika hub IoT Edge tidak dapat tersambung ke IoT Hub atau modul target tidak tersambung.

IoT Edge hub menyimpan pesan hingga waktu yang ditetapkan dalam properti yang diinginkan dari hub IoT EdgestoreAndForwardConfiguration.timeToLiveSecs.

Prioritas dan waktu hidup

Deklarasikan rute sebagai string yang menentukan rute, atau sebagai objek dengan string rute, bilangan bulat prioritas, dan bilangan bulat waktu hidup.

Opsi 1

"route1": "FROM <source> WHERE <condition> INTO <sink>",

Opsi 2 (diperkenalkan dalam IoT Edge versi 1.0.10 dengan skema hub IoT Edge versi 1.1)

"route2": {
  "route": "FROM <source> WHERE <condition> INTO <sink>",
  "priority": 0,
  "timeToLiveSecs": 86400
}

Nilai prioritas berkisar dari 0 hingga 9, di mana 0 adalah prioritas tertinggi. Sistem mengantre pesan berdasarkan titik akhir mereka. Sistem memproses semua pesan prioritas 0 untuk titik akhir tertentu sebelum memproses prioritas 1 pesan untuk titik akhir yang sama. Jika beberapa rute untuk titik akhir yang sama memiliki prioritas yang sama, sistem memproses pesan dalam urutan kedatangannya. Jika Anda tidak menetapkan prioritas, rute menggunakan prioritas terendah.

Properti timeToLiveSecs menggunakan nilai dari konfigurasi storeAndForwardConfiguration hub IoT Edge kecuali jika Anda mengaturnya secara langsung. Nilainya bisa berupa bilangan bulat positif.

Untuk detail mengenai cara antrean prioritas dikelola, lihat Route priority and time-to-live.

Menentukan dan memperbarui properti yang diinginkan

Manifes penyebaran menetapkan properti yang diinginkan untuk setiap modul yang disebarkan ke perangkat IoT Edge. Properti yang diinginkan dalam manifes penyebaran menggantikan properti yang diinginkan yang saat ini ada pada kembaran modul.

Jika Anda tidak mengatur properti yang diinginkan dari kembar modul dalam manifes penyebaran, IoT Hub tidak mengubah kembar modul. Sebagai gantinya, atur properti yang diinginkan secara terprogram.

Mekanisme yang sama yang memungkinkan Anda mengubah kembar perangkat juga memungkinkan Anda mengubah kembar modul. Untuk informasi selengkapnya, lihat panduan pengembang kembaran modul.

Contoh manifes penyebaran

Contoh berikut menunjukkan seperti apa dokumen manifes penyebaran yang valid.

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {
              "ContosoRegistry": {
                "username": "myacr",
                "password": "<password>",
                "address": "myacr.azurecr.io"
              }
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            "type": "docker",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.5",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 1,
            "env": {
              "tempLimit": {"value": "100"}
            },
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "sensorToFilter": {
            "route": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
            "priority": 0,
            "timeToLiveSecs": 1800
          },
          "filterToIoTHub": {
            "route": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream",
            "priority": 1,
            "timeToLiveSecs": 1800
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 100
        }
      }
    }
  }
}

Langkah berikutnya

• Untuk daftar lengkap properti yang dapat atau harus Anda sertakan dalam $edgeAgent dan $edgeHub, lihat Properti agen IoT Edge dan hub IoT Edge.
• Sekarang setelah Anda tahu cara kerja modul IoT Edge, pelajari tentang persyaratan dan alat untuk mengembangkan modul IoT Edge.