如何使用 IoT Central REST API 來管理部署資訊清單

文章
08/08/2024

部署資訊清單可讓您指定 IoT Edge 執行階段應下載和設定的模組。第一次連線到 IoT Central 應用程式時，IoT Edge 裝置可以下載部署資訊清單。本文說明如何使用 REST API 來管理儲存在 IoT Central 應用程式中的部署資訊清單。

若要深入了解 IoT Edge 和 IoT Central，請參閱將 Azure IoT Edge 裝置連線至 Azure IoT Central 應用程式。

每個 IoT Central REST API 呼叫都需要授權標頭。若要深入了解，請參閱如何驗證和授權 IoT Central REST API 呼叫。

如需 IoT Central REST API 的參考文件，請參閱 Azure IoT Central REST API 參考。

若要了解如何使用 IoT Central UI 來管理部署資訊清單，請參閱在 IoT Central 應用程式中管理 IoT Edge 部署資訊清單。

部署資訊清單 REST API

IoT Central REST API \(英文\) 可讓您：

將部署資訊清單新增至您的應用程式
更新應用程式中的部署資訊清單
取得應用程式中的部署資訊清單
依識別碼取得部署資訊清單
刪除應用程式中的部署資訊清單

注意

部署資訊清單 REST API 目前為預覽狀態。

新增部署資訊清單

使用下列要求來建立新的部署資訊清單。

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

下列範例顯示的要求本文新增了定義三個模組的部署資訊清單：

{
  "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
        }
      }
    }
  }
}

要求本文有一些必要欄位：

id：IoT Central 應用程式中部署資訊清單的唯一識別碼。
displayName：UI 中顯示的部署指令清單名稱。
data：IoT Edge 部署資訊清單。

此要求的回應如下列範例所示：

{
  "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\""
}

取得部署資訊清單

可使用下列要求，從您的應用程式擷取部署資訊清單的詳細資料：

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

您可以使用列出部署資訊清單 API 來取得 deploymentManifestId 值。

此要求的回應如下列範例所示：

{
  "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\""
}

更新部署資訊清單

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

下列範例要求本文會更新 SimuatedTemperatureSetting 模組的 SendInterval 所需屬性設定：

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

此要求的回應如下列範例所示：

{
  "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\""
}

刪除部署資訊清單

使用下列要求來刪除部署資訊清單：

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

列出部署資訊清單

可使用下列要求，從您的應用程式擷取部署資訊清單清單：

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

此要求的回應如下列範例所示：

{
  "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
    }
  ]
}

將部署資訊清單指派給裝置

若要使用已儲存在IoT Central 應用程式中的部署指令清單，請先使用取得部署指令清單 API 來擷取它。使用下列要求，將部署資訊清單指派給 IoT Central 應用程式中的 IoT Edge 裝置：

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

下列範例要求本文會將部署資訊清單指派給 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
        }
      }
    }
  }
}

下一步

現在您已了解如何使用 REST API 管理部署資訊清單，建議的下一個步驟是了解如何使用 IoT Central REST API 來管理裝置。

分享方式：

如何使用 IoT Central REST API 來管理部署資訊清單

部署資訊清單 REST API

新增部署資訊清單

取得部署資訊清單

更新部署資訊清單

刪除部署資訊清單

列出部署資訊清單

將部署資訊清單指派給裝置

下一步

意見反映

更多資源