関連ファイル機能を使用して複数の更新ファイルを参照する
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"
}
関連ファイルを使用した 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
次のステップ
- 詳細については、インポート マニフェストのスキーマに関する記事を参照してください。
- 詳細については、差分更新に関する記事を参照してください。