將更新匯入到 IoT 中樞裝置更新

發行項
06/27/2022

若要從 IoT 中樞裝置更新將更新部署至裝置，您必須先將該更新匯入到裝置更新服務。本文會概述一些關於匯入更新所需要了解的重要概念。

匯入資訊清單

匯入資訊清單是 JSON 檔案，可定義所要匯入更新的重要相關資訊。您會在匯入過程中同時提交匯入資訊清單和一或多個相關聯的更新檔案 (例如，韌體更新套件)。匯入資訊清單中所定義的中繼資料可用來擷取更新。有些中繼資料也可在部署階段使用，例如，用來驗證是否已正確安裝更新。

例如：

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  },
  "isDeployable": false,
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ],
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "firmware.swu"
        ],
        "handlerProperties": {
          "installedCriteria": "1.0"
        }
      }
    ]
  },
  "files": [
    {
      "filename": "firmware.swu",
      "sizeInBytes": 7558,
      "hashes": {
        "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
      }
    }
  ],
  "createdDateTime": "2022-01-19T06:23:52.6996916Z",
  "manifestVersion": "4.0"
}

匯入資訊清單包含數個項目，這些項目分別代表重要的 IoT 中樞裝置更新概念。本節會概述這些項目。如需完整匯入結構描述的相關資訊，請參閱匯入資訊清單 JSON 結構描述。

更新身分識別

更新身分識別 (或稱 updateId) 是 IoT 中樞裝置更新中的更新所具有的唯一識別碼。其由三個部分組成：

提供者：建立或直接負責更新的實體。這通常是公司名稱。
名稱：更新類別的識別碼。這通常是裝置類別或型號名稱。
版本：可讓此更新與具有相同提供者和名稱的其他更新有所區別的版本號碼。

例如：

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  }
}

注意

UpdateId 僅供裝置更新服務使用，可能會與裝置上實際軟體元件的身分識別不同。

相容性

相容性會定義可安裝更新的裝置所符合的準則。其內含裝置屬性，這些屬性是裝置所回報的一組任意索引鍵值組。只有具有相符屬性的裝置有資格進行部署。更新可藉由擁有多組裝置屬性而與多個裝置類別相容。

以下舉例說明的更新，只能部署到將 Contoso 和 Toaster 回報為其裝置製造商和型號的裝置。

{
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ]
}

Instructions

指示部分包含可供裝置代理程式安裝更新的必要資訊或步驟。最簡單的更新只包含一個內嵌步驟。該步驟會使用已向裝置代理程式註冊的處理常式來執行所含的承載檔案：

{
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

秘訣

在匯入資訊清單 3.0 版或較舊版本中，handler 相當於 updateType。

更新可包含多個步驟：

{
  "instructions": {
    "steps": [
      {
        "description": "pre-install script",
        "handler": "microsoft/script:1",
        "handlerProperties": {
          "arguments": "--pre-install"
        },
        "files": [
          "configure.sh"
        ]
      },
      {
        "description": "firmware package",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

更新可包含參考步驟，以指示裝置代理程式使用自己的匯入資訊清單一起安裝另一個更新，並建立父代和子系更新關聯性。例如，toaster 的更新可包含兩個子系更新：

{
  "instructions": {
    "steps": [
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.HeatingElement",
          "version": "1.0"
        }
      },
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.Sensors",
          "version": "1.0"
        }
      }
    ]
  }
}

注意

更新可包含以任何方式組合的內嵌步驟和參考步驟。

檔案

檔案部分包含更新承載檔案的中繼資料，例如其名稱、大小和雜湊。 IoT 中樞裝置更新會在匯入過程中，使用此中繼資料來驗證完整性。然後，再將相同的資訊轉送至裝置代理程式，以在安裝之前重複驗證完整性。

注意

只包含參考步驟的更新在父代更新中不會有任何更新承載檔案。

建立匯入資訊清單

您可以使用任何文字編輯器來建立匯入資訊清單 JSON 檔案。 GitHub 上的 Azure/iot-hub-device-update 中也有範例指令碼，能以程式設計方式建立匯入資訊清單。

重要事項

透過 Azure 入口網站匯入時，匯入資訊清單 JSON 檔案名稱必須以 .importmanifest.json 結尾。

秘訣

在建立匯入資訊清單時，請使用 Visual Studio Code 來啟用自動完成和 JSON 結構描述驗證。

匯入更新的限制

每個 IoT 中樞裝置更新執行個體都會強制執行某些限制。如果您尚未檢閱這些限制，請參閱裝置更新限制。

後續步驟

若要深入了解匯入程序，請參閱準備要匯入的更新。
檢閱匯入資訊清單結構描述。

共用方式為