Cara menggunakan REST API IoT Central untuk mengelola manifes penyebaran

  • Artikel

Manifes penyebaran memungkinkan Anda menentukan modul yang harus diunduh dan dikonfigurasi oleh runtime IoT Edge. Perangkat IoT Edge dapat mengunduh manifes penyebaran saat pertama kali terhubung ke aplikasi IoT Central Anda. Artikel ini menjelaskan cara mengelola manifes penyebaran yang disimpan di aplikasi IoT Central Anda dengan menggunakan REST API.

Untuk mempelajari lebih lanjut tentang IoT Edge dan IoT Central, lihat Sambungkan perangkat Azure IoT Edge ke aplikasi Azure IoT Central.

Setiap panggilan IoT Central REST API memerlukan header otorisasi. Untuk mempelajari selengkapnya, lihat Cara mengautentikasi dan mengotorisasi panggilan IoT Central REST API.

Untuk dokumentasi referensi untuk IoT Central REST API, lihat Referensi IoT Central REST API.

Tip

Anda dapat menggunakan Postman untuk mencoba panggilan REST API yang dijelaskan dalam artikel ini. Unduh koleksi IoT Central Postman dan impor ke Postman. Dalam koleksi, Anda harus mengatur variabel seperti subdomain aplikasi dan token admin.

Untuk mempelajari cara mengelola manifes penyebaran dengan menggunakan UI IoT Central, lihat Mengelola manifes penyebaran IoT Edge di aplikasi IoT Central Anda.

REST API manifes penyebaran

IoT Central REST API memungkinkan Anda:

  • Menambahkan manifes penyebaran ke aplikasi Anda
  • Memperbarui manifes penyebaran di aplikasi Anda
  • Mendapatkan daftar manifes penyebaran dalam aplikasi
  • Mendapatkan manifes penyebaran berdasarkan ID
  • Menghapus manifes penyebaran di aplikasi Anda

Catatan

REST API manifes penyebaran saat ini dalam pratinjau.

Menambahkan manifes penyebaran

Gunakan permintaan berikut untuk membuat manifes penyebaran baru.

PUT https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview

Contoh berikut menunjukkan isi permintaan yang menambahkan manifes penyebaran yang menentukan tiga modul:

{
  "id": "envsensorv1",
  "displayName": "Environmental sensor deployment manifest",
  "data": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.0",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.4",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
                "createOptions": "{}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.0",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.0",
          "routes": {
            "route": "FROM /* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 10
        }
      }
    }
  }
}

Isi permintaan memiliki beberapa bidang yang diperlukan:

  • id: ID unik untuk manifes penyebaran di aplikasi IoT Central.
  • displayName: nama untuk manifes penyebaran yang ditampilkan di UI.
  • data: manifes penyebaran IoT Edge.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "envsensorv1",
  "data": {
    "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.4",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
                "createOptions": "{}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.0",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "route": "FROM /* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 10
        }
      }
    }
  },
  "displayName": "Environmental sensor deployment manifest",
  "etag": "\"0500f164-0000-1100-0000-637cf09c0000\""
}

Mendapatkan manifes penyebaran

Gunakan permintaan berikut untuk mengambil detail manifes penyebaran dari aplikasi Anda:

GET https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview

Anda bisa mendapatkan deploymentManifestId nilai dengan menggunakan DAFTAR API manifes penyebaran.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "envsensor",
  "data": {
    "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.4",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
                "createOptions": "{}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.0",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "route": "FROM /* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 10
        }
      }
    }
  },
  "displayName": "Environmental sensor deployment manifest",
  "etag": "\"0500f663-0000-1100-0000-637cec590000\""
}

Perbarui manifes penyebaran

PATCH https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview

Isi permintaan sampel berikut memperbarui pengaturan properti yang SendIntervalSimuatedTemperatureSetting diinginkan untuk modul:

{
  "data": {
    "modulesContent": {
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendInterval": 30
        }
      }
    }
  }
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "envsensorv1",
  "data": {
    "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.4",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
                "createOptions": "{}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.0",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.2",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "route": "FROM /* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 30
        }
      }
    }
  },
  "displayName": "Environmental sensor deployment manifest",
  "etag": "\"05003065-0000-1100-0000-637cf1b00000\""
}

Menghapus manifes penyebaran

Gunakan permintaan berikut untuk menghapus manifes penyebaran:

DELETE https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview

Mencantumkan manifes penyebaran

Gunakan permintaan berikut untuk mengambil daftar manifes penyebaran dari aplikasi Anda:

GET https://{your app subdomain}/api/deploymentManifests?api-version=2022-10-31-preview

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "value": [
    {
      "id": "envsensor",
      "data": {
        "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.4",
                    "createOptions": "{}"
                  }
                },
                "edgeHub": {
                  "type": "docker",
                  "status": "running",
                  "restartPolicy": "always",
                  "settings": {
                    "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
                    "createOptions": "{}"
                  }
                }
              },
              "modules": {
                "SimulatedTemperatureSensor": {
                  "version": "1.0",
                  "type": "docker",
                  "status": "running",
                  "restartPolicy": "always",
                  "settings": {
                    "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
                    "createOptions": "{}"
                  }
                }
              }
            }
          },
          "$edgeHub": {
            "properties.desired": {
              "schemaVersion": "1.1",
              "routes": {
                "route": "FROM /* INTO $upstream"
              },
              "storeAndForwardConfiguration": {
                "timeToLiveSecs": 7200
              }
            }
          },
          "SimulatedTemperatureSensor": {
            "properties.desired": {
              "SendData": true,
              "SendInterval": 10
            }
          }
        }
      },
      "displayName": "Environmental sensor deployment manifest",
      "etag": "\"0500f663-0000-1100-0000-637cec590000\""
    },
    {
        // More deployment manifests
    }
  ]
}

Menetapkan manifes penyebaran ke perangkat

Untuk menggunakan manifes penyebaran yang sudah disimpan di aplikasi IoT Central Anda, pertama-tama gunakan DAPATKAN API manifes penyebaran untuk mengambilnya. Gunakan permintaan berikut untuk menetapkan manifes penyebaran ke perangkat IoT Edge di aplikasi IoT Central Anda:

POST https://{your app subdomain}.azureiotcentral.com/api/devices/{your IoT Edge device ID}/applyDeploymentManifest?api-version=2022-10-31-preview

Isi permintaan sampel berikut menetapkan manifes penyebaran ke perangkat IoT Edge:

{
  "data": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.0",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.4",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
                "createOptions": "{}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.0",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.0",
          "routes": {
            "route": "FROM /* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 10
        }
      }
    }
  }
}

Langkah berikutnya

Sekarang setelah Anda mempelajari cara mengelola manifes penyebaran dengan REST API, langkah selanjutnya yang disarankan adalah mempelajari Cara menggunakan IoT Central REST API untuk mengelola perangkat.