Bagikan melalui

Menerapkan dan memantau modul IoT Edge dalam skala besar menggunakan Azure CLI

  • Artikel

Berlaku untuk: Tanda centang IoT Edge 1.5 IoT Edge 1.5 Tanda centang IoT Edge 1.4 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.

Buat penyebaran otomatis Azure IoT Edge dengan menggunakan Azure CLI untuk mengelola penyebaran yang sedang berlangsung untuk banyak perangkat sekaligus. Penyebaran otomatis untuk IoT Edge adalah bagian dari fitur manajemen perangkat Azure IoT Hub. Penyebaran adalah proses dinamis yang memungkinkan Anda untuk menyebarkan beberapa modul ke beberapa perangkat, melacak status dan kesehatan modul, dan membuat perubahan jika diperlukan.

Dalam artikel ini, Anda menyiapkan Azure CLI dan ekstensi IoT. Anda kemudian mempelajari cara menggunakan modul ke set perangkat IoT Edge dan memantau kemajuannya menggunakan perintah CLI yang tersedia.

Prasyarat

  • IoT Hub di langganan Azure Anda.

  • Satu atau beberapa perangkat IoT Edge.

    Jika Anda tidak menyiapkan perangkat IoT Edge, Anda dapat membuatnya di komputer virtual Azure. Ikuti langkah-langkah di salah satu artikel panduan memulai ini: Membuat perangkat Linux virtual atau Membuat perangkat Windows virtual.

  • Azure CLI di lingkungan Anda. Versi Azure CLI Anda harus 2.0.70 atau lebih tinggi. Gunakan az --version untuk memvalidasi. Versi ini mendukung perintah ekstensi az dan memperkenalkan kerangka kerja perintah Knack.

  • Ekstensi IoT untuk Azure CLI.

Mengonfigurasi manifes penerapan

Manifes penyebaran adalah dokumen JSON yang menjelaskan modul mana yang akan disebarkan, bagaimana data mengalir di antara modul, dan properti yang diinginkan dari modul twin. Untuk informasi lebih lanjut, lihat Pelajari cara menyebarkan modul dan membuat rute di IoT Edge.

Untuk menyebarkan modul menggunakan Azure CLI, simpan manifes penyebaran secara lokal sebagai file .txt. Anda menggunakan jalur file di bagian berikutnya saat menjalankan perintah untuk menerapkan konfigurasi ke perangkat Anda.

Berikut adalah manifes penyebaran dasar dengan satu modul sebagai contoh:

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.5",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Catatan

Manifes penyebaran sampel ini menggunakan skema versi 1.1 untuk agen dan hub IoT Edge. Skema versi 1.1 dirilis bersama dengan IoT Edge versi 1.0.10. Skema ini memungkinkan fitur seperti urutan mulai modul dan prioritas rute.

Penyebaran berlapis

Penyebaran berlapis adalah jenis penyebaran otomatis yang dapat ditumpuk di atas satu sama lain. Untuk informasi selengkapnya tentang penyebaran berlapis, lihat Memahami penyebaran otomatis IoT Edge untuk satu perangkat atau dalam skala besar.

Penyebaran berlapis dapat dibuat dan dikelola dengan Azure CLI seperti penyebaran otomatis lainnya, hanya dengan beberapa perbedaan. Setelah penerapan berlapis dibuat, Azure CLI bekerja untuk memproses penerapan berlapis sama seperti yang dilakukan pada penerapan lainnya. Untuk membuat penyebaran berlapis, tambahkan bendera --layered ke perintah buat.

Perbedaan kedua adalah dalam pembangunan manifes penyebaran. Sementara penerapan otomatis standar harus berisi modul runtime sistem selain modul pengguna apa pun, penerapan berlapis hanya dapat berisi modul pengguna. Penerapan berlapis juga memerlukan penerapan otomatis standar pada perangkat untuk memasok komponen yang diperlukan dari setiap perangkat IoT Edge, seperti modul runtime sistem.

Berikut adalah manifes penerapan berlapis dasar dengan satu modul sebagai contoh:

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.5"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Catatan

Manifes penerapan berlapis ini memiliki format yang sedikit berbeda dari manifes penerapan standar. Properti yang diinginkan dari modul runtime diciutkan menggunakan notasi titik. Pemformatan ini diperlukan agar portal Microsoft Azure mengenali penyebaran berlapis. Contohnya:

  • properties.desired.modules.<module_name>
  • properties.desired.routes.<route_name>

Contoh sebelumnya menunjukkan penyebaran berlapis yang mengatur properties.desired untuk modul. Jika penyebaran berlapis ini menargetkan perangkat di mana modul yang sama sudah diterapkan, itu akan menimpa properti yang diinginkan yang ada. Untuk memperbarui properti yang diinginkan alih-alih menimpanya, Anda dapat menentukan sub bagian baru. Contohnya:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties": {
    "SendData": true,
    "SendInterval": 5
  }
}

Hal yang sama juga dapat diungkapkan dengan:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties.SendData" : true,
  "properties.desired.layeredProperties.SendInterval": 5
}

Catatan

Saat ini, semua penerapan berlapis harus menyertakan objek edgeAgent agar dianggap valid. Bahkan jika penyebaran berlapis hanya memperbarui properti modul, sertakan objek kosong. Misalnya: "$edgeAgent":{}. Penerapan berlapis dengan objek edgeAgent kosong akan ditampilkan sebagai ditargetkan di modul kembar edgeAgent, bukan diterapkan.

Singkatnya, untuk membuat penyebaran berlapis:

  • Tambahkan bendera --layered ke perintah pembuatan Azure CLI.
  • Jangan sertakan modul sistem.
  • Gunakan notasi titik penuh pada $edgeAgent dan $edgeHub.

Untuk informasi selengkapnya tentang mengonfigurasi modul kembar dalam penerapan berlapis, lihat Penerapan berlapis.

Mengidentifikasi perangkat menggunakan tag

Sebelum dapat membuat penyebaran, Anda harus dapat menentukan perangkat mana yang ingin Anda pengaruhi. Azure IoT Edge mengidentifikasi perangkat menggunakan tag di perangkat kembar.

Setiap perangkat dapat memiliki beberapa tag yang ditentukan dengan cara apa pun yang masuk akal untuk solusi Anda. Misalnya, jika Mengelola kampus gedung pintar, Anda dapat menambahkan tag berikut ke perangkat:

"tags":{
  "location":{
    "building": "20",
    "floor": "2"
  },
  "roomtype": "conference",
  "environment": "prod"
}

Untuk informasi selengkapnya tentang perangkat kembar dan tag, lihat Memahami dan menggunakan perangkat kembar di IoT Hub.

Membuat penyebaran

Anda menyebarkan modul ke perangkat target dengan membuat penyebaran yang terdiri dari manifes penyebaran serta parameter lainnya.

Gunakan perintah buat penyebaran az iot edge untuk membuat penyebaran:

az iot edge deployment create --deployment-id [deployment id] --hub-name [hub name] --content [file path] --labels "[labels]" --target-condition "[target query]" --priority [int]

Gunakan perintah yang sama dengan bendera --layered untuk membuat penyebaran berlapis.

Perintah buat untuk penerapan menggunakan parameter berikut:

  • --layered. Bendera opsional untuk mengidentifikasi penerapan sebagai penerapan berlapis.
  • --deployment-id - Nama penyebaran yang akan dibuat di hub IoT. Beri penyebaran Anda nama unik hingga 128 huruf kecil. Hindari spasi dan karakter tidak valid berikut: & ^ [ ] { } \ | " < > /. Parameter ini diperlukan.
  • --content. Jalur file ke manifes penyebaran JSON. Parameter ini diperlukan.
  • --hub-name. Nama hub IoT tempat penerapan akan dibuat. Hub harus berada dalam langganan saat ini. Ubah langganan Anda saat ini dengan perintah az account set -s [subscription name].
  • --labels. Pasangan nama/nilai yang menjelaskan dan membantu Anda melacak penerapan Anda. Label mengambil pemformatan JSON untuk nama dan nilai. Misalnya: {"HostPlatform":"Linux", "Version:"3.0.1"}.
  • --target-condition. Kondisi yang menentukan perangkat mana yang akan ditargetkan dengan penerapan ini. Kondisi ini didasarkan pada tag kembar perangkat atau properti yang dilaporkan perangkat kembar, dan harus cocok dengan format ekspresi. Misalnya: tags.environment='test' and properties.reported.devicemodel='4000x'. Jika kondisi target tidak ditentukan, maka penyebaran tidak diterapkan ke perangkat apa pun.
  • --priority. Bilangan bulat positif. Jika dua atau lebih penerapan ditargetkan pada perangkat yang sama, penerapan dengan nilai numerik tertinggi untuk prioritas akan diterapkan.
  • --metrics. Metrik yang mengkueri properti edgeHub yang dilaporkan untuk melacak status penerapan. Metrik menggunakan input JSON atau jalur file. Misalnya: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

Untuk memantau penyebaran menggunakan Azure CLI, lihat Memantau penyebaran IoT Edge.

Catatan

Saat penyebaran IoT Edge baru dibuat, terkadang diperlukan waktu hingga 5 menit agar IoT Hub memproses konfigurasi baru dan menyebarkan properti baru yang diinginkan ke perangkat yang ditargetkan.

Mengubah penyebaran

Saat Anda memodifikasi penyebaran, perubahan akan segera mereplikasi ke semua perangkat yang ditargetkan.

Jika Anda memperbarui kondisi target, pembaruan berikut terjadi:

  • Jika perangkat tidak memenuhi kondisi target lama tetapi memenuhi kondisi target baru, dan penerapan ini merupakan prioritas tertinggi untuk perangkat tersebut, maka penerapan ini akan diterapkan ke perangkat.
  • Jika perangkat yang saat ini menjalankan penerapan ini tidak lagi memenuhi kondisi target, perangkat akan mencopot pemasangan penerapan ini dan mengambil penerapan prioritas tertinggi berikutnya.
  • Jika perangkat yang saat ini menjalankan penyebaran ini tidak lagi memenuhi persyaratan target dan tidak memenuhi persyaratan target penyebaran lainnya, maka tidak ada perubahan yang terjadi pada perangkat. Perangkat terus menjalankan modulnya saat ini dalam statusnya saat ini, tetapi tidak lagi dikelola sebagai bagian dari penyebaran ini. Setelah memenuhi kondisi target penyebaran lain, perangkat menghapus penyebaran ini dan mengambil penyebaran baru.

Anda tidak dapat memperbarui konten penyebaran, yang mencakup modul dan rute yang ditentukan dalam manifes penyebaran. Jika Anda ingin memperbarui konten penyebaran, Anda dapat melakukannya dengan membuat penyebaran baru yang menargetkan perangkat yang sama dengan prioritas yang lebih tinggi. Anda dapat memodifikasi properti tertentu dari modul yang ada, termasuk kondisi target, label, metrik, dan prioritas.

Gunakan perintah pembaruan penyebaran az iot edge untuk memperbarui penyebaran:

az iot edge deployment update --deployment-id [deployment id] --hub-name [hub name] --set [property1.property2='value']

Perintah pembaruan penyebaran mengambil parameter berikut:

  • --deployment-id - Nama penyebaran yang ada di IoT hub.
  • --hub-name. Nama IoT hub tempat penyebaran berada. Hub harus berada dalam langganan saat ini. Beralih ke langganan yang diinginkan dengan perintah az account set -s [subscription name].
  • --set. Memperbarui properti dalam penyebaran. Anda dapat memperbarui properti berikut:
    • targetCondition (misalnya, targetCondition=tags.location.state='Oregon')
    • labels
    • priority
  • --add. Menambahkan properti baru ke penyebaran, termasuk kondisi target atau label.
  • --remove. Menghapus properti yang ada, termasuk kondisi target atau label.

Menghapus penyebaran

Saat Anda menghapus penyebaran, perangkat apa pun menggunakan penerapan prioritas tertinggi berikutnya. Jika perangkat Anda tidak memenuhi kondisi target penyebaran lainnya, modul tidak akan dihapus saat penyebaran dihapus.

Gunakan perintah hapus penyebaran az iot edge untuk menghapus penyebaran:

az iot edge deployment delete --deployment-id [deployment id] --hub-name [hub name]

Perintah deployment delete mengambil parameter berikut:

  • --deployment-id - Nama penyebaran yang ada di IoT hub.
  • --hub-name. Nama IoT hub tempat penyebaran berada. Hub harus berada dalam langganan saat ini. Beralih ke langganan yang diinginkan dengan perintah az account set -s [subscription name].

Langkah berikutnya

Pelajari selengkapnya tentang Menyebarkan modul ke perangkat IoT Edge.