適用於 IoT 中樞 匯入指令清單架構的 Azure 裝置更新
當您將更新匯入IoT中樞的 Azure 裝置更新時，您也會提交相關聯的 JSON 匯入指令清單檔案，以定義更新的重要資訊。 本文說明用來建立 JSON 匯入指令清單檔的架構。
若要深入瞭解匯入指令清單概念和檔案結構，請參閱適用於 IoT 中樞 匯入指令清單的 Azure 裝置更新。 若要瞭解如何建立檔案，請參閱準備更新以匯入裝置更新以進行 IoT 中樞。
結構描述
匯入指令清單 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 |
匯入資訊清單結構描述版本。 必須是 5.0。 | Yes |
| createdDateTime | string |
以 ISO 8601 格式匯入指令清單建立日期和時間，例如 "2020-10-02T22:18:04.9446744Z"。 |
Yes |
更新物件
物件 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"
}
}
相容性物件
物件 compatibility 描述此更新所相容裝置的1-5個屬性。 每個屬性都是 string 類型名稱/值組。 名稱長度必須為 1-32 個字元，且值長度必須為 1-64 個字元。 您無法使用相同的完全相同的相容性屬性集搭配多個更新提供者和名稱組合。
例如：
{
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
]
}
Instructions 物件
物件 instructions 提供更新安裝指示。 指令物件包含要執行的清單 steps 。 不允許其他屬性。
步驟可以是要執行的程式代碼，或是其他更新的指標。 如果未type提供任何值，則步驟物件預設為 inline 。
| 屬性 | 類型 | 描述 | 必要 |
|---|---|---|---|
| 步驟 | array[1-10] |
數位中的每個 steps 元素都必須是 內嵌步驟對象 或 參考步驟物件。 |
Yes |
例如：
{
"instructions": {
"steps": [
{
"type": "inline",
...
},
{
"type": "reference",
...
}
]
}
}
內嵌步驟物件
inline Step 對像是執行程式代碼執行的安裝指示步驟。
| 屬性 | 類型 | 描述 | 必要 |
|---|---|---|---|
| type | string |
執行程式碼執行的指示步驟類型。 必須是 inline。 如果未提供任何值，則預設為 inline。 |
No |
| description | string |
選擇性的指示步驟描述。 最大長度：64 個字元。 | No |
| 處理常式 | string |
裝置上可執行此步驟的處理常式的身分識別。 模式： ^\S+/\S+:\d{1,5}$最小長度：五個字元 長度上限：32 個字元 範例： microsoft/script:1、microsoft/swupdate:2、microsoft/apt:1 |
Yes |
| 檔 | string [1-10] |
更新檔案的名稱，定義為 代理程序傳遞給處理程式的檔案物件 。 每個元素長度都必須是 1-255 個字元。 | Yes |
| handlerProperties | inlineStepHandlerProperties |
代理程式傳遞至處理程式做為自變數的 JSON 物件。 | No |
不允許其他屬性。
例如：
{
"steps": [
{
"description": "pre-install script",
"handler": "microsoft/script:1",
"handlerProperties": {
"arguments": "--pre-install"
},
"files": [
"configure.sh"
]
}
]
}
參考步驟物件
reference步驟對像是安裝另一個更新的安裝指示步驟。
| 屬性 | 類型 | 描述 | 必要 |
|---|---|---|---|
| type | referenceStepType |
安裝另一個更新的指示步驟類型。 必須是 reference。 |
Yes |
| description | stepDescription |
選擇性的指示步驟描述。 最大長度：64 個字元。 | No |
| updateId | updateId |
唯一更新識別碼。 | Yes |
不允許其他屬性。
例如：
{
"steps": [
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.HeatingElement",
"version": "1.0"
}
}
]
}
Files 物件
每個 files 物件都是更新承載檔案，例如二進位、韌體或腳本檔案，在更新內必須是唯一的。
| 屬性 | 類型 | 描述 | 必要 |
|---|---|---|---|
| filename | string |
更新承載檔案名稱。 長度上限：255 個字元 | Yes |
| sizeInBytes | number |
檔案大小 (以位元組數為單位)。 大小上限：2147483648 個位元組 | Yes |
| hashes | fileHashes |
Base64 編碼的檔案雜湊會使用演算法名稱作為索引鍵。 至少必須指定 SHA-256 演算法，而且代理程式支援時可以指定其他演算法。 如需如何計算哈希的詳細資訊，請參閱 Hashes物件 。 | Yes |
| relatedFiles | relatedFile[0-4] |
與一或多個主要承載檔案相關的檔案集合。 如需詳細資訊，請參閱 relatedFiles 物件。 | No |
| downloadHandler | downloadHandler |
指定如何處理任何相關的檔案。 | 是，如果使用 relatedFiles。 如需詳細資訊，請參閱 downloadHandler 物件。 |
不允許其他屬性。
例如：
{
"files": [
{
"fileName": "full-image-file-name",
"sizeInBytes": 12345,
"hashes": {...},
"relatedFiles": [
{
"fileName": "delta-from-v1-file-name",
"sizeInBytes": 1234,
"hashes": {
"SHA256": "delta-from-v1-file-hash"
},
"properties": {...}
}
],
"downloadHandler": {
"id": "microsoft/delta:1"
}
}
]
}
Hashes 物件
物件 hashes 包含base64編碼的檔案哈希，其演算法名稱稱為索引鍵。 至少必須指定 SHA-256 演算法，而如果代理程式支援，則可以指定其他的演算法。 如需如何正確計算哈希的範例，請參閱 Get-AduFileHashes AduUpdate.psm1 腳本中的 函式。
| 屬性 | 類型 | 描述 | 必要 |
|---|---|---|---|
| sha256 | string |
使用 SHA-256 演算法的 Base64 編碼檔案雜湊值。 | Yes |
允許其他屬性。
例如：
{
"hashes": {
"sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
}
}
relatedFiles 物件
relatedFiles物件包含與一或多個主要承載檔案相關的檔案集合。 如需詳細資訊，請參閱使用相關的檔案功能來參考多個更新檔案。
| 屬性 | 類型 | 描述 | 必要 |
|---|---|---|---|
| filename | string |
與主要承載檔案相關聯的相關檔案清單。 | Yes |
| sizeInBytes | number |
檔案大小 (以位元組數為單位)。 大小上限：2147483648個字節。 | Yes |
| hashes | fileHashes |
Base64 編碼的檔案雜湊會使用演算法名稱作為索引鍵。 如需詳細資訊，請參閱 Hashes 物件。 | Yes |
| 性能 | relatedFilesProperties [0-5] |
最多五個索引鍵/值組，其中索引鍵限製為64個ASCII字元，而此值為JObject，最多256個ASCII字元。 | No |
允許其他屬性。
例如：
"relatedFiles": [
{
"filename": "in1_in2_deltaupdate.dat",
"sizeInBytes": 102910752,
"hashes": {
"sha256": "2MIldV8LkdKenjJasgTHuYi+apgtNQ9FeL2xsV3ikHY="
},
"properties": {
"microsoft.sourceFileHashAlgorithm": "sha256",
"microsoft.sourceFileHash": "YmFYwnEUddq2nZsBAn5v7gCRKdHx+TUntMz5tLwU+24="
}
}
],
downloadHandler 物件
物件 downloadHandler 會指定如何處理任何相關的檔案。
| 屬性 | 類型 | 描述 | 必要 |
|---|---|---|---|
| id | string |
的 downloadHandler標識碼。 具有 64 個 ASCII 字元的限制。 |
是，如果使用 relatedFiles |
不允許其他屬性。
例如：
"downloadHandler": {
"id": "microsoft/delta:1"
}