Pelajari cara menyebarkan modul dan membuat rute di IoT Edge

Berlaku untuk: IoT Edge 1.5

Penting

IoT Edge 1.5 LTS adalah rilis yang didukung. IoT Edge 1.4 LTS adalah akhir masa pakai per 12 November 2024. Jika Anda menggunakan rilis sebelumnya, lihat Memperbarui 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 agen IoT Edge, yang mencakup tiga komponen:
  • Gambar kontainer untuk setiap modul yang berjalan pada perangkat
  • Info masuk untuk menggunakan registri kontainer privat yang memiliki gambar modul
  • Petunjuk tentang bagaimana setiap modul dibuat dan dikelola
• Kembar modul 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 kesalahan sampai dikonfigurasi dengan 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 IoT Hub Service SDK. Untuk informasi selengkapnya, lihat Memahami penyebaran IoT Edge.

Membuat manifes penyebaran

Manifes penyebaran adalah daftar modul kembar yang ditetapkan dengan properti yang diinginkan. Ini memberi tahu perangkat IoT Edge atau sekelompok perangkat mana yang akan diinstal modul 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 perangkat tersebut. Untuk informasi selengkapnya tentang modul ini, lihat Memahami 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) yang valid.

Manifes penyebaran menggunakan struktur 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 cara runtime IoT Edge memasang modul dalam penyebaran Anda. Agen IoT Edge adalah komponen runtime yang mengelola pemasangan, 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 mengikuti struktur 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

Daftar properti yang diinginkan agen IoT Edge adalah tempat Anda menentukan modul mana yang dijalankan pada perangkat IoT Edge dan bagaimana modul tersebut disiapkan dan dikelola.

Untuk daftar lengkap properti yang diinginkan yang dapat atau harus disertakan, 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, itu tidak dimulai secara otomatis. Untuk informasi selengkapnya, lihat Docker Docs - Mulai kontainer secara otomatis. Harus diisi.

• StartupOrder: Diperkenalkan di 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 sesuai urutan nilai pemulaannya, tetapi tidak menunggu hingga tiap modul selesai mulai sebelum memulai yang 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 Docker
  • variabel lingkungan
  • kebijakan hidupkan ulang
  • kebijakan penarikan gambar
  • versi
  • urutan startup

  Jika tidak ada properti modul yang diubah, pembaruan modul tidak akan dipicu.

Menyatakan rute

Hub IoT Edge mengelola komunikasi antara modul, IoT Hub, dan perangkat hilir. Modul kembar $edgeHub memiliki properti yang diinginkan yang disebut rute 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": { ... }
  }
}

Skema hub IoT Edge 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 SDK IoT, modul dapat mengatur antrean output tertentu untuk pesan mereka menggunakan kelas ModuleClient. 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 Memahami dan menggunakan Azure IoT Hub SDK.

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 melalui beberapa atau tanpa output, atau oleh perangkat hilir
/messages/modules/*	Setiap pesan perangkat-ke-cloud yang dikirim oleh modul melalui beberapa output atau tanpa output
/messages/modules/<moduleId>/*	Setiap pesan perangkat-ke-cloud yang dikirim oleh modul tertentu melalui beberapa output atau tanpa output
/messages/modules/<moduleId>/outputs/*	Setiap pesan perangkat-ke-cloud yang dikirim oleh modul tertentu melalui beberapa output
/messages/modules/<moduleId>/outputs/<output>	Setiap pesan perangkat-ke-cloud yang dikirim oleh modul tertentu melalui output tertentu

Kondisi

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

Pesan yang berpindah antar modul di 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 menggunakan sintaks ini:

• Properti sistem: $<propertyName> atau {$<propertyName>}
• Properti aplikasi: <propertyName>
• Properti isi: $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

Titik pembuangan menentukan lokasi di mana pesan dikirim. 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	Mengirim pesan ke IoT Hub
BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")	Mengirim pesan ke input tertentu dari modul tertentu

IoT Edge memberikan setidaknya sekali jaminan. Hub IoT Edge 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.

Hub IoT Edge menyimpan pesan sampai waktu yang ditentukan dalam properti storeAndForwardConfiguration.timeToLiveSecs dari properti yang diinginkan untuk hub IoT Edge.

Prioritas dan time-to-live

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 di 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. Pesan diantrikan pada titik akhir mereka. Semua pesan prioritas 0 untuk titik akhir tertentu diproses sebelum pesan prioritas 1 untuk titik akhir yang sama. Jika beberapa rute untuk titik akhir yang sama memiliki prioritas yang sama, pesan diproses sesuai urutan kedatangannya. Jika Anda tidak menetapkan prioritas, rute menggunakan prioritas terendah.

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

Untuk informasi lebih lanjut tentang bagaimana antrean prioritas dikelola, lihat Prioritas rute dan 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 menimpa properti yang diinginkan yang saat ini dalam kembaran modul.

Jika Anda tidak mengatur properti target modul kembar dalam manifes penyebaran, IoT Hub tidak mengubah modul kembar. 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.