Share via

関連ファイル機能を使用して複数の更新ファイルを参照する

  • [アーティクル]

1 回の更新でさまざまな更新ファイル間のリレーションシップを表す必要がある場合は、関連ファイル機能を使います。

Device Update for IoT Hub に更新をインポートする場合、更新のペイロードに関するメタデータを含むインポート マニフェストが必要です。 最も単純なケースでは、インポート マニフェストのファイルレベルのメタデータが、更新ペイロード ファイルのフラット リストである場合があります。 ただし、より高度なシナリオでは、関連ファイル機能を使用して、複数の更新ファイル間のリレーションシップを指定できます。

関連ファイル機能を使ってインポート マニフェストを作成する場合、"関連" ファイルのコレクションを "プライマリ" ペイロード ファイルの 1 つ以上に追加できます。 この概念の例は、Device Update の差分更新機能です。これは、関連ファイルを使って、完全なイメージ ファイルに関連付けられた差分更新ファイルを指定する機能です。 差分シナリオでは、関連ファイル機能により、完全なイメージと差分更新ファイルの両方を 1 つの更新アクションとしてインポートし、いずれかをデバイスにデプロイできます。 ただし、関連ファイル機能は、お客様が独自のシナリオに応じて拡張できるように設計されているため、差分更新に限定されません。

関連ファイル機能は、バージョン 5 以降のインポート マニフェストで使用できます。

関連ファイルをインポート マニフェストに追加する場合は、次の情報を含めます。

  • ファイルの詳細

    ファイル名、サイズ、ハッシュを指定して、関連ファイルを定義します。

  • ダウンロード ハンドラー

    これらの関連ファイルを処理してターゲット ファイルを生成する方法を指定します。 プロセス方法を指定するには、インポート マニフェストに downloadHandler プロパティを含めます。 file 要素で relatedFiles の空でないコレクションを指定する場合は、downloadHandler を含める必要があります。 単純な id プロパティを使って downloadHandler を指定できます。 ダウンロード ハンドラー id には、64 文字という ASCII 文字の制限があります。

  • 関連ファイルのプロパティ

    デバイス上の更新ハンドラーが、関連ファイルとして指定したファイルをどのように解釈し、適切に使うかを把握するために、追加のメタデータを指定できます。 このメタデータは、properties プロパティ バッグの一部として file と relatedFile の各オブジェクトに追加されます。

関連ファイルのインポート スキーマの詳細については、「relatedFiles オブジェクト」を参照してください。

次のインポート マニフェストの例では、関連ファイル機能を使用してどのように差分更新をインポートするかを示します。 この例では、files セクションに、properties 項目で指定した完全なイメージ (full-image-file-name) があることがわかります。 properties 項目には、その下に関連付けられた relatedFiles 項目があります。 relatedFiles セクションの中には、差分更新ファイル (delta-from-v1-file-name) 用の別の properties セクションと、適切な id が一覧表示された downloadHandler 項目が表示されています (microsoft/delta:1)。

Note

この例では、差分更新を使用して関連ファイルを参照する方法を示します。 差分更新を機能として使う場合は、差分更新のドキュメントで詳細を確認してください。

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

インポート マニフェストを作成するための 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

次のステップ