複数ステップの順序付け実行を使用すると、オンプレミスの更新プログラムをデプロイするときに、プレインストールタスクとインストール後タスクを実行できます。 この機能は、パブリック プレビュー更新プログラム マニフェスト v4 スキーマの一部です。
パブリック プレビュー更新リリースの一部として、次の変更を確認する前に、更新マニフェストの ドキュメントを参照してください。
複数ステップの順序付け実行では、次の 2 種類のステップがあります。
- インラインプロセス (デフォルト)
- 参照手順
1 つのインライン ステップを含む更新マニフェストの例:
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"deviceManufacturer": "du-device",
"deviceModel": "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": [
{
"deviceManufacturer": "du-device",
"deviceModel": "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": [ { "deviceManufacturer": "du-device", "deviceModel": "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 文字列を含める必要があります。
親更新と子更新
更新マニフェストが相互に参照されている場合、最上位レベルのマニフェストは 親更新 と呼ばれ、参照手順で指定されたマニフェストは 子更新と呼ばれます。
現時点では、子更新プログラムには参照手順を含めることはできません。 この制限はインポート時に検証され、それに従わない場合、インポートは失敗します。
親の更新におけるインラインステップ
親更新で指定されたインライン ステップがホスト デバイスに適用されます。 ここでは、ステップ ハンドラー (更新コンテンツ ハンドラーとも呼ばれます) に渡されるADUC_WorkflowData オブジェクトには、Selected Components データは含まれません。 この種類のステップのハンドラーは絶対にComponent-Awareハンドラーであってはなりません。
ステップ コンテンツ ハンドラーは、各ステップ IsInstalled 検証ロジックを適用します。 Device Update エージェントのステップ ハンドラーは、IsInstalled() が結果コード "900" (true' を意味する) になったかどうかを確認することで、特定の更新プログラムが既にインストールされているかどうかを確認します。 更新プログラムが既にインストールされている場合、デバイスに既に存在する更新プログラムの再インストールを回避するために、DU エージェントは今後の手順をスキップします。これは、この手順を実行するかどうかを判断するために使用するためです。
更新結果を報告するには、ステップ ハンドラー実行の結果を、--result-file オプションで指定された目的の結果ファイル内のADUC_Result構造体に書き込む必要があります。 その後、実行の結果に基づいて、成功した場合は 0 が返され、致命的なエラーの場合は -1 または0xFFが返されます。
詳細については、ステップ コンテンツ ハンドラー と カスタム コンポーネント対応コンテンツ ハンドラーの実装を参照してください。
親更新における参照手順
親更新で指定された参照ステップは、ホスト デバイス上のコンポーネントまたはホスト デバイスに接続されているコンポーネントに適用されます。 参照ステップ は、子更新と呼ばれる別の更新プログラムの更新識別子を含むステップです。
参照ステップを処理する場合、ステップ ハンドラーは、参照ステップ データで指定されたデタッチされた更新マニフェスト ファイルをダウンロードし、ファイルの整合性を検証します。 次に、ステップ ハンドラーは子更新マニフェストを解析し、子更新マニフェストのデータと親更新マニフェストのファイル URL 情報を組み合わせて、ADUC_Workflow オブジェクト (子ワークフロー データとも呼ばれます) を作成します。 この子ワークフロー データには、'level' プロパティも '1' に設定されています。
注
現時点では、子更新プログラムには参照手順を含めることはできません。
分離された更新マニフェスト
IoT Hub ツインのデータ サイズの制限によるデプロイエラーを回避するために、大きな更新マニフェストは JSON データ ファイルの形式で配信されます。これは、デタッチされた更新マニフェストとも呼ばれます。
大きなコンテンツを含む更新プログラムが Device Update for IoT Hub にインポートされた場合、生成された更新マニフェストには、更新マニフェストの完全なデータを含む Detached Update Manifestという別のペイロード ファイルが含まれます。
デバイスまたはモジュール ツインの UpdateManifest プロパティには、デタッチされた更新マニフェスト ファイル情報が含まれます。
PnP プロパティ変更イベントを処理すると、Device Update エージェントはデタッチされた更新マニフェスト ファイルを自動的にダウンロードし、完全な更新マニフェスト データを含むADUC_WorkflowData オブジェクトを作成します。