Pelajari cara menyebarkan modul dan membuat rute di IoT Edge

Berlaku untuk: IoT Edge 1.5 IoT Edge 1.4

Penting

IoT Edge 1.5 LTS dan IoT Edge 1.4 LTS adalah rilis yang didukung. IoT Edge 1.4 LTS adalah akhir masa pakai pada 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 sejumlah proses. Gunakan manifes penyebaran untuk memberi tahu perangkat Anda modul mana yang akan dipasang dan cara mengonfigurasinya agar berfungsi bersama.

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.
  • Kredensial untuk mengakses registri kontainer privat yang berisi gambar modul.
  • Petunjuk tentang bagaimana setiap modul harus dibuat dan dikelola.
• Kembaran modul hub IoT Edge, yang mencakup bagaimana pesan mengalir di antara modul dan akhirnya ke IoT Hub.
• Properti yang diinginkan dari modul kembar tambahan (opsional).

Semua perangkat IoT Edge harus dikonfigurasi dengan manifes penyebaran. Runtime IoT Edge yang baru dipasang melaporkan kode kesalahan hingga dikonfigurasi dengan manifes yang valid.

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

Membuat manifes penyebaran

Pada tingkat tinggi, manifes penyebaran adalah daftar kembaran modul yang dikonfigurasi dengan properti yang diinginkan. Manifes penyebaran memberi tahu perangkat IoT Edge (atau sekelompok perangkat) modul mana yang akan dipasang dan cara mengonfigurasinya. Manifes penyebaran mencakup properti yang diinginkan untuk setiap kembaran modul. Perangkat IoT Edge melaporkan kembali properti yang dilaporkan untuk setiap modul.

Dua modul diperlukan dalam setiap manifes penyebaran: $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.

Selain dua modul runtime tersebut, Anda dapat menambahkan hingga 50 modul Anda sendiri untuk dijalankan pada perangkat IoT Edge.

Manifes penyebaran yang hanya berisi runtime IoT Edge (edgeAgent dan edgeHub) valid.

Manifes penyebaran mengikuti 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. Oleh karena itu, kembaran modul $edgeAgent berisi informasi konfigurasi dan pengelolaan 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":{
              // give the IoT Edge agent access to 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 bersama dengan IoT Edge versi 1.0.10, dan memungkinkan urutan startup modul. Versi skema 1.1 disarankan untuk semua penyebaran IoT Edge 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 yang disebarkan ke perangkat IoT Edge dan cara modul tersebut harus dikonfigurasi 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 yang berisi citra modul, alamat untuk citra kontainer dalam registri kontainer, dan semua createOptions untuk mengonfigurasi citra 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 harus dijalankan atau dihentikan saat pertama kali digunakan. Harus diisi.

• RestartPolicy: Kapan dan apakah agen IoT Edge harus memulai ulang modul jika berhenti. Jika modul dihentikan tanpa kesalahan apa pun, modul tidak akan 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 mana yang harus dimulai oleh agen IoT Edge saat pertama kali disebarkan. Urutan dinyatakan dengan bilangan bulat, di mana modul yang diberi nilai startup 0 dimulai terlebih dahulu dan kemudian diikuti dengan nomor yang lebih tinggi. Modul edgeAgent tidak memiliki nilai startup karena selalu dimulai terlebih dahulu. Opsional.

  Agen IoT Edge memulai modul dalam urutan nilai startup, tetapi tidak menunggu setiap modul selesai dimulai sebelum pergi ke yang berikutnya.

  Urutan startup sangat membantu jika beberapa modul bergantung pada modul lainnya. Misalnya, Anda mungkin ingin modul edgeHub dimulai terlebih dahulu sehingga siap merutekan pesan ketika modul lain dimulai. Atau Anda mungkin ingin memulai modul penyimpanan sebelum memulai modul yang mengirim data ke modul tersebut. Namun, Anda harus selalu mendesain modul untuk menangani kegagalan modul lain. Ini adalah sifat kontainer yang dapat dihentikan dan dimulai ulang kapan saja dan berkali-kali.

  Catatan

  Perubahan pada properti modul akan mengakibatkan modul tersebut dimulai ulang. Misalnya, mulai ulang akan 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, modul tidak akan dimulai ulang.

Menyatakan rute

Hub IoT Edge mengelola komunikasi antara modul, IoT Hub, dan perangkat hilir apa pun. Oleh karena itu, kembaran modul $edgeHub berisi properti yang diinginkan yang disebut rute yang menyatakan bagaimana pesan diteruskan dalam penyebaran. Anda dapat memiliki beberapa rute dalam penyebaran yang sama.

Rute dinyatakan dalam properti $edgeHub yang diinginkan dengan sintaks berikut:

{
  "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 bersama dengan IoT Edge versi 1.0.10, dan memungkinkan prioritas rute dan waktu hidup. Versi skema 1.1 disarankan untuk semua penyebaran IoT Edge yang menjalankan versi 1.0.10 atau yang lebih baru.

Setiap rute membutuhkan sumber tempat asal pesan dan sink tempat tujuan pengiriman pesan. Kondisi adalah bagian opsional yang dapat digunakan untuk memfilter pesan.

Anda dapat menetapkan prioritas pada rute yang diinginkan untuk memastikan bahwa pesannya diproses terlebih dahulu. Fitur ini sangat membantu dalam skenario saat koneksi hulu lemah atau terbatas dan Anda memiliki data penting yang harus diprioritaskan melalui pesan telemetri standar.

Sumber

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

Dengan SDK IoT, modul dapat mendeklarasikan antrean output tertentu untuk pesan mereka menggunakan kelas ModuleClient. Antrean output tidak diperlukan, tetapi berguna untuk mengelola beberapa rute. Perangkat hilir dapat menggunakan kelas DeviceClient dari SDK IoT untuk mengirim pesan ke perangkat gateway IoT Edge dengan cara yang sama seperti mereka akan mengirim pesan ke IoT Hub. Untuk informasi selengkapnya, lihat Memahami dan menggunakan Azure IoT Hub SDK.

Properti sumber bisa berupa salah satu nilai berikut 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. Jika Anda ingin meneruskan semua pesan dari sumber ke sink, jangan ubah klausul WHERE sepenuhnya. Atau Anda dapat menggunakan bahasa kueri IoT Hub untuk memfilter pesan atau jenis pesan tertentu yang memenuhi kondisi tersebut. Rute IoT Edge tidak mendukung pemfilteran pesan berdasarkan tag atau properti kembar.

Pesan yang diteruskan antar modul di IoT Edge memiliki format yang sama dengan pesan yang diteruskan antara perangkat Anda dan Azure IoT Hub. Semua pesan diformat sebagai JSON dan memiliki parameter systemProperties, appProperties, isi.

Anda dapat menyusun kueri di sekitar salah satu dari tiga parameter dengan sintaks berikut:

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

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

Contoh yang khusus untuk IoT Edge adalah ketika Anda ingin memfilter pesan yang tiba di perangkat gateway dari perangkat hilir. Pesan yang dikirim dari modul menyertakan properti sistem yang disebut connectionModuleId. Jadi, jika Anda ingin merutekan pesan dari perangkat hilir langsung ke IoT Hub, gunakan rute berikut untuk mengecualikan pesan modul:

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

Sink

Sink menentukan tempat tujuan pengiriman pesan. Hanya modul dan IoT Hub yang dapat menerima pesan. Pesan tidak dapat dirutekan ke perangkat lain. Tidak ada opsi karakter kartubebas di properti sink.

Properti sink bisa berupa salah satu nilai berikut:

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

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

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

Prioritas dan time-to-live

Rute dapat dinyatakan hanya dengan string yang menentukan rute, atau sebagai objek yang mengambil string rute, bilangan bulat prioritas, dan bilangan bulat time-to-live.

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 bisa 0-9, inklusif, dengan keterangan, 0 adalah prioritas tertinggi. Pesan dimasukkan ke antrean berdasarkan titik akhirnya. Semua pesan prioritas 0 yang menargetkan titik akhir tertentu diproses sebelum pesan prioritas 1 yang menargetkan titik akhir yang sama diproses, dan tidak berfungsi. Jika beberapa rute untuk titik akhir yang sama memiliki prioritas yang sama, pesan mereka diproses secara first-come-first-served. Jika tidak ada prioritas yang ditentukan, rute ditetapkan ke prioritas terendah.

Properti timeToLiveSecs mewarisi nilainya dari IoT storeAndForwardConfiguration hub IoT Edge, kecuali diatur secara eksplisit. Nilainya bisa berupa bilangan bulat positif.

Untuk informasi selengkapnya tentang cara antrean prioritas dikelola, lihat halaman referensi untuk Prioritas rute dan time-to-live.

Menentukan dan memperbarui properti yang diinginkan

Manifes penyebaran menentukan 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 menentukan properti yang diinginkan kembar modul dalam manifes penyebaran, IoT Hub tidak akan memodifikasi modul kembar dengan cara apa pun. Sebagai alternatif, Anda dapat mengatur properti yang diinginkan secara terprogram.

Mekanisme yang sama yang memungkinkan Anda memodifikasi kembaran perangkat digunakan untuk memodifikasi kembaran modul. Untuk informasi selengkapnya, lihat panduan pengembang kembaran modul.

Contoh manifes penyebaran

Contoh berikut menunjukkan tampilan 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 disertakan dalam $edgeAgent dan $edgeHub, lihat Properti agen IoT Edge dan hub IoT Edge.

• Setelah Anda mengetahui bagaimana modul IoT Edge digunakan, Pahami persyaratan dan alat untuk mengembangkan modul IoT Edge.