使用相關的檔案功能來參考多個更新檔案

當您需要在單一更新中表達不同更新檔案之間的關聯性時，請使用相關檔案功能。

將更新匯入至 IoT 中樞裝置更新時，內含更新承載相關中繼資料的匯入資訊清單是必要項目。 在最簡單的案例中，匯入資訊清單中的檔案層級中繼資料可以是更新承載檔案的一般清單。 不過，針對更進階的案例，相關檔案功能可讓您指定多個更新檔案之間的關聯性。

使用相關檔案功能建立匯入資訊清單時，您可以將相關檔案的集合新增至一或多個主要承載檔案。 此概念的範例是裝置更新差異更新功能，此功能會使用相關檔案來指定與完整映像檔相關聯的差異更新。 在差異情節中，相關檔案功能允許將完整映像和差異更新同時匯入為單一更新動作，然後您可以將兩者之一部署到裝置。 不過，相關檔案功能不限於差異更新，因為其設計目的是要根據客戶自己的獨特情節來進行擴充。

如何定義相關的檔案

相關的檔案功能適用於第 5 版以上版本的匯入資訊清單。

當您將相關檔案新增至匯入資訊清單時，請包含下列資訊:

• 檔案詳細資料

  藉由提供檔案名稱、大小和雜湊碼來定義相關檔案。

• 下載處理常式

  指定如何處理這些相關檔案以產生目標檔案。 您可以在匯入資訊清單中包含 downloadHandler 屬性來指定處理方法。 如果您在 file 元素中指定 relatedFiles 的非空白集合，則需要包含 downloadHandler。 您可以使用簡單的 id 屬性來指定 downloadHandler。 下載處理常式 id 的限制為 64 個 ASCII 字元。

• 相關檔案屬性

  您可以為裝置上的更新處理常式提供額外的中繼資料，以了解如何解譯及正確使用您指定為相關檔案的檔案。 這個中繼資料會被作為 properties 屬性包的一部分新增至 file 和 relatedFile 物件。

如需相關檔案匯入結構描述的詳細資訊，請參閱 relatedFiles 物件。

使用相關檔案的範例匯入資訊清單

下列範例匯入資訊清單會示範如何使用相關的檔案功能來匯入 delta 更新。 在此範例中，您可以看到 files 區段中，指定的完整映像 (full-image-file-name) 中包含了 properties 項目。 properties 項目接著會在其下方有相關聯的 relatedFiles 項目。 在 relatedFiles 區段中，您可以看到差異更新檔案 (delta-from-v1-file-name) 的另一個 properties 區段，以及 downloadHandler 項目，其中列出適當的 id (microsoft/delta:1)。

注意

此範例會使用 delta 更新來示範如何參考相關檔案。 如果您想要使用 delta 更新作為功能，請在 delta 更新文件內進行深入了解。

    {
      "updateId": {
        // provider, name, version
      },
      "compatibility": [
        {
          // manufacturer, model, etc.
        }
      ],
      "instructions": {
        "steps": [
          // Inline steps...
        ]
      },
      "files": [
        {  
          // standard file properties
          "fileName": "full-image-file-name",
          "sizeInBytes": 12345,
          "hashes": {
            "SHA256": "full-image-file-hash"
          },
          "mimeType": "application/octet-stream",
          // new properties
          "properties  ": {},
          "relatedFiles": [
            {
              // delta from version 1.0.0.0
              // standard file properties
              "fileName": "delta-from-v1-file-name",
              "sizeInBytes": 1234,
              "hashes": {
                "SHA256": "delta-from-v1-file-hash"
              },
              "mimeType": "application/octet-stream",
              // new properties
              "properties": {
                "microsoft.sourceFileHash": "delta-source-file-hash",
                "microsoft.sourceFileHashAlgorithm": "sha256"
              }
            }  
          ],
          // handler to download/process our related files
      "downloadHandler": {
        "id": "microsoft/delta:1"
      }
    }
  ],
  "createdDateTime": "2021-12-01T01:12:21Z",
  "manifestVersion": "5.0"
    }

使用相關檔案的 init 命令範例

用於建立匯入資訊清單的 az iot du init v5 命令支援選擇性 --related-file 參數。

--related-file 參數會採用 path 和 properties 索引鍵:

--related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}' 

例如：

az iot du update init v5 \
--update-provider Microsoft --update-name myBundled --update-version 2.0 \
--compat manufacturer=Contoso model=SpaceStation \
--step handler=microsoft/script:1 properties='{"arguments": "--pre"}' description="Pre-install script" \
--file path=/my/update/scripts/preinstall.sh downloadHandler=microsoft/delta:1 \
--related-file path=/my/update/scripts/related_preinstall.json properties='{"microsoft.sourceFileHashAlgorithm": "sha256"}' \
--step updateId.provider=Microsoft updateId.name=SwUpdate updateId.version=1.1 \
--step handler=microsoft/script:1 properties='{"arguments": "--post"}' description="Post-install script" \
--file path=/my/update/scripts/postinstall.sh

下一步

• 瞭解匯入資訊清單結構描述
• 瞭解差異更新