將更新匯入 IoT 中樞的裝置更新：結構描述和其他資訊

如果您想要將更新匯入 IoT 中樞裝置更新，請務必先檢閱概念和操作指南。 如果您對匯入指令清單架構的詳細數據或 API 許可權的相關信息感興趣，請參閱下方。

匯入資訊清單 JSON 結構描述會裝載於 SchemaStore.org。

結構描述

屬性	類型​	描述	必要
$schema	string	JSON 結構描述參考。	No
updateId	updateId	唯一更新識別碼。	Yes
description	string	選用的更新描述。 長度上限：512 個字元	No
compatibility	compatibility	此更新與其相容的裝置屬性集的清單。	Yes
instructions	instructions	更新安裝指示。	Yes
files	file [0-10]	更新承載檔案的清單。 所有檔案大小的總和不得超過 2 GB。 如果所有指示步驟都是參考步驟，則可以是空白或 Null。	No
manifestVersion	string	匯入資訊清單結構描述版本。 必須是 4.0。	Yes
createdDateTime	string	日期與時間匯入資訊清單是以 ISO 8601 格式建立。 範例: "2020-10-02T22:18:04.9446744Z"	Yes

不允許其他屬性。

updateId 物件

updateID 物件是每個更新的唯一識別碼。

屬性	類型​	描述	必要
提供者	string	正在建立或直接負責更新的實體。 它可以是公司名稱。 模式：^[a-zA-Z0-9.-]+$ 長度上限：64 個字元	Yes
name	string	更新類別的識別碼。 它可以是裝置類別或型號名稱。 模式：^[a-zA-Z0-9.-]+$ 長度上限：64 個字元	Yes
version	string	兩到四個部分、以點分隔的數值版本號碼。 每個部分都必須是介於 0 到 2147483647 之間的數字，而且會捨棄前置零。 模式：^\d+(?:\.\d+)+$ 範例："1.0"、"2021.11.8"	Yes

不允許其他屬性。

例如：

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

相容性物件

相容性物件會描述此更新與其相容的裝置屬性。

• 類型：object
• 屬性下限：1
• 屬性上限：5

每個屬性都是類型字串的名稱-值組。

• 屬性名稱長度下限：1
• 屬性名稱長度上限：32
• 屬性值長度下限：1
• 屬性值長度上限：64

同一組完全相同的相容性屬性不能與一個以上的提供者及名稱組合搭配使用。

例如：

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

instructions 物件

instructions 物件會提供更新安裝指示。 instructions 物件包含要執行的步驟清單。 步驟可以是要執行的程式碼或另一個更新的指標。

屬性	類型​	描述	必要
steps	array[1-10]	陣列中的每個元素都必須是 inlineStep 物件或 referenceStep 物件。	Yes

不允許其他屬性。

例如：

{
  "instructions": {
    "steps": [
      {
        "type": "inline",
        ...
      },
      {
        "type": "reference",
        ...
      }
    ]
  }
}

inlineStep 物件

inline 步驟物件是執行程式碼執行的安裝指令步驟。

屬性	類型​	描述	必要
type	string	執行程式碼執行的指示步驟類型。 必須是 inline。 如果未提供任何值，則預設為 inline。	No
description	string	選擇性的指示步驟描述。 長度上限：64 個字元	No
處理常式	string	裝置上可執行此步驟的處理常式的身分識別。 模式：^\S+/\S+:\d{1,5}$ 長度下限：5 個字元 長度上限：32 個字元 範例：microsoft/script:1、microsoft/swupdate:1、microsoft/apt:1	Yes
files	string [1-10]	代理程式將傳遞給處理常式、定義為 files 物件的更新檔案的名稱。 陣列中的每個元素長度必須介於 1 到 255 個字元之間。	Yes
handlerProperties	inlineStepHandlerProperties	代理程式將傳遞至處理常式做為引數的 JSON 物件。	No

不允許其他屬性。

例如：

{
  "steps": [
    {
      "description": "pre-install script",
      "handler": "microsoft/script:1",
      "handlerProperties": {
        "arguments": "--pre-install"
      },
      "files": [
        "configure.sh"
      ]
    }
  ]
}

referenceStep 物件

reference 步驟物件是會安裝另一個更新的安裝指示步驟。

屬性	類型​	描述	必要
type	referenceStepType	安裝另一個更新的指示步驟類型。 必須是 reference。	Yes
description	stepDescription	選擇性的指示步驟描述。 長度上限：64 個字元	No
updateId	updateId	唯一更新識別碼。	Yes

不允許其他屬性。

例如：

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

file 物件

file 物件是更新承載檔案，例如二進位檔、韌體、指令碼等。每個檔案物件在更新內都必須是唯一的。

屬性	類型​	描述	必要
filename	string	更新承載檔案名稱。 長度上限：255 個字元	Yes
sizeInBytes	number	檔案大小 (以位元組數為單位)。 大小上限：2147483648 個位元組	Yes
hashes	fileHashes	Base64 編碼的檔案雜湊會使用演算法名稱作為索引鍵。 至少必須指定 SHA-256 演算法，而如果代理程式支援，則可以指定額外的演算法。 如需如何計算雜湊的詳細資料，請參閱下方。	Yes

不允許其他屬性。

例如：

{
  "files": [
    {
      "filename": "configure.sh",
      "sizeInBytes": 7558,
      "hashes": {...}
    }
  ]
}

fileHashes 物件

Base64 編碼的檔案雜湊會使用演算法名稱作為索引鍵。 至少必須指定 SHA-256 演算法，而如果代理程式支援，則可以指定其他的演算法。 如需如何正確計算雜湊的範例，請參閱 AduUpdate.psm1 指令碼中的 Get-AduFileHashes 函式。

屬性	類型​	描述	必要
sha256	string	使用 SHA-256 演算法的 Base64 編碼檔案雜湊值。	Yes

允許其他屬性。

例如：

{
  "hashes": {
    "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
  }
}

下一步

深入了解匯入概念。

如果您已準備就緒，請嘗試匯入操作指南，其將逐步引導您完成匯入程序。