複数ステップの順序指定実行
Azure Device Update for IoT Hub の複数ステップの順序指定実行により、無線更新を展開するときに、インストール前タスクとインストール後タスクを実行できます。 この機能は、Device Update の更新マニフェスト スキーマ バージョン 4 の一部です。 詳細については、「Device Update の更新リソース」を参照してください。
複数ステップの順序指定実行には、インライン ステップと参照ステップの 2 種類のステップを含めることができます。 インライン ステップは、コードを実行する命令であり、既定の種類です。 参照ステップは、別の更新プログラムの識別子を含むステップです。
親更新と子更新
更新マニフェストが別の更新マニフェストを参照する場合、最上位のマニフェストは親更新と呼ばれ、参照ステップで指定されたマニフェストは子更新と呼ばれます。 子更新には参照ステップを含めず、インライン ステップのみを含めることができます。 Device Update では、インポート時にこの制限が検証され、満たされていない場合は更新が失敗します。
親更新のインライン ステップ
Device Update エージェントは、親更新で指定されたインライン ステップをホスト デバイスに適用します。 ステップ ハンドラー (更新コンテンツ ハンドラーとも呼ばれます) に渡す ADUC_WorkflowData オブジェクトには、 Selected Components データは含まれません。 この種類のステップのハンドラーは Component-Aware ハンドラーにすることはできません。
Device Update エージェントのステップ コンテンツ ハンドラーは、各ステップに IsInstalled 検証ロジックを適用します。 ステップ ハンドラーは、IsInstalled() が結果コード 900 または true を返すかどうかを確認して、更新プログラムが既にインストールされているかどうかを確認し、この結果を使用してステップを実行するかどうかを判断します。 デバイスに既にインストールされている更新プログラムの再インストールを回避するために、更新プログラムが既にインストールされている場合、Device Update エージェントは今後のステップをスキップします。
更新結果を報告するには、--result-file オプションで指定されている目的の結果ファイル内の ADUC_Result 構造体にステップ ハンドラー実行の結果を書き込みます。 実行結果に基づいて、成功した場合は 0 を返し、致命的なエラーの場合は -1 または 0xFF を返します。
詳細については、「ステップ ハンドラー」と「カスタム コンポーネント対応コンテンツ ハンドラーを実装する方法」を参照してください。
親更新の参照ステップ
Device Update エージェントは、親更新で指定された参照ステップを、ホスト デバイス上またはホスト デバイスに接続されているコンポーネントに適用します。 参照ステップを処理すると、ステップ ハンドラーは、ステップで指定されたデタッチされた更新マニフェスト ファイルをダウンロードし、ファイルの整合性を検証します。
次に、ステップ ハンドラーは子更新マニフェストを解析し、子更新マニフェストのデータと親更新マニフェストのファイル URL 情報を組み合わせて、子ワークフロー データとも呼ばれる ADUC_Workflow オブジェクトを作成します。 この子ワークフロー データの level プロパティは 1 に設定されています。
例
次の更新マニフェストの例には、1 つのインライン ステップがあります。
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "e2e-test"
}
],
"instructions": {
"steps": [
{
"description": "Example APT update that installs 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 - preinstall 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 - postinstall 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-step-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\""
}
Note
installedCriteria を使用してステップを実行するかどうかを判断する場合は、更新マニフェストで各ステップに異なる installedCriteria 値を指定する必要があります。
デタッチされた更新マニフェスト
Azure IoT Hub ツインのデータ サイズ制限によるデプロイの失敗を回避するために、Device Update は、デタッチされた更新マニフェストと呼ばれる JSON データ ファイルとして、大きな更新マニフェストデバイスに配信します。 Device Update に大きなコンテンツ更新プログラムをインポートすると、生成された更新マニフェストには、完全な更新マニフェスト データを含む Detached Update Manifest という別のペイロード ファイルが含まれます。
デバイスまたはモジュール ツインの UpdateManifest プロパティには、デタッチされた更新マニフェスト ファイルの情報が含まれます。 PnP PropertyChanged イベントを処理すると、Device Update エージェントはデタッチされた更新マニフェスト ファイルを自動的にダウンロードし、完全な更新マニフェスト データを含む ADUC_WorkflowData オブジェクトを作成します。