複数ステップの順序指定実行
複数ステップの順序指定実行により、無線による更新をデプロイするとき、インストール前とインストール後のタスクを実行できます。 この機能は、パブリック プレビュー リフレッシュ更新マニフェスト v4 スキーマの一部です。
次の変更 (パブリック プレビュー リフレッシュ リリースの一部) を確認する前に、更新マニフェストに関するドキュメントを参照してください。
複数ステップの順序指定実行には、次の 2 種類のステップがあります。
- インライン ステップ (既定)
- 参照ステップ
1 つのインライン ステップを含む更新マニフェストの例を次に示します。
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "e2e-test"
}
],
"instructions": {
"steps": [
{
"description": "Example APT update that install libcurl4-doc on a host device.",
"handler": "microsoft/apt:1",
"files": [
"apt-manifest-1.0.json"
],
"handlerProperties": {
"installedCriteria": "apt-update-test-1.0"
}
}
]
},
"manifestVersion": "4.0",
"importedDateTime": "2021-11-16T14:54:55.8858676Z",
"createdDateTime": "2021-11-16T14:50:47.3511877Z"
}
2 つのインライン ステップを含む更新マニフェストの例を次に示します。
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "e2e-test"
}
],
"instructions": {
"steps": [
{
"description": "Install libcurl4-doc on host device",
"handler": "microsoft/apt:1",
"files": [
"apt-manifest-1.0.json"
],
"handlerProperties": {
"installedCriteria": "apt-update-test-2.2"
}
},
{
"description": "Install tree on host device",
"handler": "microsoft/apt:1",
"files": [
"apt-manifest-tree-1.0.json"
],
"handlerProperties": {
"installedCriteria": "apt-update-test-tree-2.2"
}
}
]
},
"manifestVersion": "4.0",
"importedDateTime": "2021-11-16T20:21:33.6514738Z",
"createdDateTime": "2021-11-16T20:19:29.4019035Z"
}
1 つの参照ステップを含む更新マニフェストの例を次に示します。
子更新を参照する親更新
{ "updateId": {...}, "isDeployable": true, "compatibility": [ { "manufacturer": "du-device", "model": "e2e-test" } ], "instructions": { "steps": [ { "type": "reference", "description": "Cameras Firmware Update", "updateId": { "provider": "contoso", "name": "virtual-camera", "version": "1.2" } } ] }, "manifestVersion": "4.0", "importedDateTime": "2021-11-17T07:26:14.7484389Z", "createdDateTime": "2021-11-17T07:22:10.6014567Z" }インライン ステップを含む子更新
{ "updateId": { "provider": "contoso", "name": "virtual-camera", "version": "1.2" }, "isDeployable": false, "compatibility": [ { "group": "cameras" } ], "instructions": { "steps": [ { "description": "Cameras Update - pre-install step", "handler": "microsoft/script:1", "files": [ "contoso-camera-installscript.sh" ], "handlerProperties": { "scriptFileName": "contoso-camera-installscript.sh", "arguments": "--pre-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path", "installedCriteria": "contoso-virtual-camera-1.2-step-0" } }, { "description": "Cameras Update - firmware installation (failure - missing file)", "handler": "microsoft/script:1", "files": [ "contoso-camera-installscript.sh", "camera-firmware-1.1.json" ], "handlerProperties": { "scriptFileName": "missing-contoso-camera-installscript.sh", "arguments": "--firmware-file camera-firmware-1.1.json --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path", "installedCriteria": "contoso-virtual-camera-1.2-step-1" } }, { "description": "Cameras Update - post-install step", "handler": "microsoft/script:1", "files": [ "contoso-camera-installscript.sh" ], "handlerProperties": { "scriptFileName": "contoso-camera-installscript.sh", "arguments": "--post-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path", "installedCriteria": "contoso-virtual-camera-1.2-stop-2" } } ] }, "referencedBy": [ { "provider": "DU-Client-Eng", "name": "MSOE-Update-Demo", "version": "3.1" } ], "manifestVersion": "4.0", "importedDateTime": "2021-11-17T07:26:14.7376536Z", "createdDateTime": "2021-11-17T07:22:09.2232968Z", "etag": "\"ad7a553d-24a8-492b-9885-9af424d44d58\"" }
注意
更新マニフェストでは、installedCriteria 文字列を使用してステップを実行するかどうかを判断する場合は、各ステップに異なる installedCriteria 文字列が含まれている必要があります。
親更新と子更新
更新マニフェストがお互いを参照している場合、最上位レベルのマニフェストを親更新と呼び、参照ステップで指定されているマニフェストを子更新と呼びます。
現時点では、子更新に参照ステップを含めることはできません。 この制限はインポート時に検証され、それに従っていない場合、インポートは失敗します。
親更新のインライン ステップ
親更新で指定されているインライン ステップはホスト デバイスに適用されます。 ここで、ステップ ハンドラー (別名: 更新コンテンツ ハンドラー) に渡される ADUC_WorkflowData オブジェクトには、Selected Components データは含まれません。 この種類のステップのハンドラーを Component-Aware ハンドラーにすることはできません。
ステップ コンテンツ ハンドラーは、ステップごとに IsInstalled 検証ロジックを適用します。 デバイス更新エージェントのステップ ハンドラーは、IsInstalled() の結果が "true" を意味する結果コード "900" であるかどうか確認することで、特定の更新が既にインストールされているかどうかを判断します。 更新が既にインストールされている場合、DU エージェントは、デバイスに既に存在する更新を再インストールしないようにするために、以後のステップをスキップします。これは、その更新を使用してステップを実行するかどうかを判断するためです。
更新結果を報告するために、ステップ ハンドラーの実行結果を、--result-file オプションで指定した目的の結果ファイル内の ADUC_Result 構造体に書き込む必要があります。 その後は、実行の結果に基づきます。成功した場合は 0 が返され、致命的なエラーの場合は -1 または0xFFが返されます。
詳細については、ステップ コンテンツ ハンドラーに関するページと、カスタム コンポーネント対応コンテンツ ハンドラーの実装に関するページを参照してください。
親更新の参照ステップ
親更新で指定されている参照ステップは、ホスト デバイス上のコンポーネントまたはホスト デバイスに接続されているコンポーネントに適用されます。 参照ステップは、子更新と呼ばれる別の更新の更新識別子を含むステップです。
ステップ ハンドラーは、参照ステップを処理するとき、参照ステップ データで指定されているデタッチされた更新マニフェスト ファイルをダウンロードし、その後、そのファイルの整合性を検証します。 次に、ステップ ハンドラーは、子更新マニフェストを解析し、子更新マニフェストからのデータと親更新マニフェストからのファイル URL 情報を結合することで、ADUC_Workflow オブジェクト (別名: 子ワークフロー データ) を作成します。 この子ワークフロー データには、"1" に設定された "level" プロパティもあります。
注意
現時点では、子更新に参照ステップを含めることはできません。
デタッチされた更新マニフェスト
IoT Hub ツイン データのサイズ制限が原因のデプロイ エラーを回避するために、大規模な更新マニフェストは、デタッチされた更新マニフェストと呼ばれる JSON データ ファイルの形式で提供されます。
大規模なコンテンツを含む更新が Device Update for IoT Hub にインポートされる場合、生成される更新マニフェストには、Detached Update Manifest という名前の別のペイロード ファイルが含まれます。このペイロード ファイルには、更新マニフェストの全データが含まれます。
デバイスまたはモジュール ツインの UpdateManifest プロパティには、デタッチされた更新マニフェスト ファイルの情報が含まれます。
デバイス更新エージェントは、PnP プロパティ変更イベントを処理するとき、デタッチされた更新マニフェスト ファイルを自動的にダウンロードし、更新マニフェストの全データを含む ADUC_WorkflowData オブジェクトを作成します。