差分更新 (プレビュー)

差分更新を使用すると、2 つの完全な更新 (ソース イメージとターゲット イメージ) の間の変更のみを表す小規模な更新を生成できます。 このアプローチは、更新をデバイスにダウンロードするために使用される帯域幅を削減するために、特に、ソースとターゲットの更新の間にわずかな変更しかない場合に最適です。

Device Update for IoT Hub で差分更新を使用するための要件

• ソースとターゲットの更新ファイルは、SWUpdate (SWU) 形式である必要があります。
• 各 SWUpdate ファイル内には、Ext2、Ext3、または Ext4 ファイルシステムを使用する生イメージが存在している必要があります。

差分生成プロセスでは、最適な差分を生成するために、gzip 圧縮を使用してターゲット SWU 更新を再圧縮します。 この再圧縮されたターゲット SWU 更新を、生成された差分更新ファイルと共に Device Update サービスにインポートします。

差分プロセッサ コンポーネント用の Device Update エージェント構成

Device Update サービスから差分更新をダウンロードしてインストールするには、デバイスの Device Update エージェントに更新ハンドラーと差分プロセッサ コンポーネントが存在し、構成されている必要があります。

デバイス更新エージェント

デバイス更新エージェントは、ダウンロード、インストール、再起動の操作など、デバイス上の更新プロセスを "調整" します。 Device Update エージェントをデバイスに追加し、それを使用できるように構成するには、Device Update エージェントのプロビジョニングに関するページを参照してください。 エージェント バージョン 1.0 以降を使用します。

更新ハンドラー

更新ハンドラーは、デバイス更新エージェントと統合され、更新の実際のインストールを実行します。 差分更新では、変更したい独自の SWUpdate 更新ハンドラーがまだない場合、microsoft/swupdate:2 更新ハンドラーを使用して作業を開始してください。

差分プロセッサ

Azure/iot-hub-device-update-delta にある差分プロセッサでは、差分ファイルのダウンロードの後にデバイス上に元の SWU イメージ ファイルを再作成するため、更新ハンドラーでは SWU ファイルをインストールできます。 差分プロセッサ コンポーネントをデバイス イメージに追加し、それを使用できるように構成するには、https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0 から Ubuntu 20.04 以降向けの Debian パッケージをダウンロードできます。

別のディストリビューションを使用する場合は、README.md の指示に従って、代わりに CMAKE を使用してソースから差分プロセッサをビルドします。 そこから、次のように、共有オブジェクト libadudiffapi.so を /usr/lib ディレクトリにコピーすることによって直接インストールします。

sudo cp <path to libadudiffapi.so> /usr/lib/libadudiffapi.so
sudo ldconfig

ソース SWU イメージ ファイルをデバイスに追加する

差分更新ファイルをデバイスにダウンロードすると、そのファイルが、前にデバイス上でキャッシュされた有効な <source_archive> と比較されます。 このプロセスにより、差分更新で完全なターゲット イメージを再作成できます。

このキャッシュされたイメージに入力するための最も簡単な方法として、Device Update サービス経由で完全なイメージ更新をインポートし、デバイスにデプロイします。 デバイスに Device Update エージェントのバージョン 1.0 以降と差分プロセッサが構成されている場合、後で差分更新で使用するために、エージェントではインストールされた SWU ファイルを自動的にキャッシュします。

代わりに、デバイス上でソース イメージに事前に直接入力したい場合、そのイメージが予測されるパスは <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH> です。 既定では、<BASE_SOURCE_DOWNLOAD_CACHE_PATH> はパス /var/lib/adu/sdc/<provider> です。 provider 値は、ソース SWU ファイルの updateId の provider の部分です。

ENCODED_HASH は、バイナリの SHA256 の base64 16 進数文字列ですが、base64 16 進数文字列にエンコードした後、文字を次のようにエンコードします。

• + を octets _2B にエンコード
• / を octets _2F にエンコード
• = を octets _3D にエンコード

DiffGen ツールを使用した差分更新の生成

Diff Generation (DiffGen) ツールを使用して差分更新を作成できます。

環境の前提条件

DiffGen で差分を作成する前に、環境マシンにいくつかのものをダウンロードしてインストールする必要があります。 理想的には、Ubuntu 20.04 Linux 環境、または Windows を使用している場合は Linux 用 Windows サブシステムを使用します。

次の表は、必要なコンテンツ、それを入手できる場所、必要に応じて推奨されるインストールを示しています。

DiffGen を使用した差分更新の作成

DiffGen ツールは、次の必須の引数と構文で実行されます。

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive>

前のコマンドは、<recompressed_target_file> を作成する recompress_tool.py スクリプトを実行します。 DiffGen では次に、差分を作成するためのターゲット ファイルとして <target_archive> の代わりに <recompressed_target_file> を使用します。 <recompressed_target_archive> 内のイメージ ファイルは、gzip で圧縮されます。

SWU ファイルが署名されている場合は、DiffGen コマンド内に <signing_command> 引数も必要です。

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive> "<signing_command>"

署名コマンド文字列パラメーターを含む DiffGenTool は、recompress_and_sign_tool.py スクリプトを実行します。 このスクリプトは <recompressed_target_file> を作成します。 さらに、このスクリプトはまた、sw-description.sig ファイルを作成するためにアーカイブ内の sw-description ファイルに署名します。

入力ソース ファイルと再圧縮され、再署名されたターゲット ファイルの間の差分を作成するには、Azure/iot-hub-device-update-delta GitHub リポジトリにあるサンプルの sign_file.sh スクリプトを使用できます。 スクリプトを開き、それを編集して秘密キー ファイルへのパスを追加してから保存します。 使用例については、例のセクションを参照してください。

次の表で、引数について詳しく説明します。

DiffGen の例

次の例は、Linux 用 Windows サブシステムの /mnt/o/temp ディレクトリから動作します。

次のコードでは、入力ソース ファイルと再圧縮されたターゲット ファイルの間の差分を作成します。

sudo ./DiffGenTool  
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu
/mnt/o/temp/<delta file to create>
/mnt/o/temp/logs
/mnt/o/temp/working
/mnt/o/temp/<recompressed target file to create>.swu

署名パラメーター (SWU ファイルが署名されている場合に必要) も使用している場合は、前に説明したサンプルの sign_file.sh スクリプトを使用できます。 スクリプトを開き、それを編集して秘密キー ファイルへのパスを追加し、スクリプトを保存してから、次のように DiffGen を実行します。

次のコードでは、入力ソース ファイルと再圧縮され、再署名されたターゲット ファイルの間の差分を作成します。

sudo ./DiffGenTool  
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu   
/mnt/o/temp/<delta file to create>  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/<recompressed target file to create>.swu  
/mnt/o/temp/<path to script>/<sign_file>.sh

生成された差分更新のインポート

差分更新を Device Update サービスにインポートする基本的なプロセスは、他のすべての更新と同じです。 まだ行っていない場合は、Azure Device Update for IoT Hub にインポートされる更新を準備する方法に関するページを確認してください。

インポート マニフェストを生成する

Device Update サービスに更新をインポートするには、インポート マニフェスト ファイルがあるか、またはそれを作成する必要があります。 詳細については、Device Update への更新のインポートに関するページを参照してください。

差分更新のインポート マニフェスト ファイルでは、DiffGen ツールで作成された次のファイルを参照する必要があります。

• <recompressed_target_file> SWU イメージ
• <delta file>

差分更新機能では、バージョン 5 以降のインポート マニフェストを必要とする、関連ファイルと呼ばれる機能を使用します。 関連ファイル機能を使用するには、インポート マニフェスト内に relatedFiles および downloadHandler オブジェクトを含める必要があります。

relatedFiles オブジェクトは、差分更新ファイルに関する情報 (ファイル名、ファイル サイズ、sha256 ハッシュを含む) を指定するために使用します。 最も重要な点として、差分更新機能に固有の次の 2 つのプロパティも指定する必要があります。

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "<source SWU image file hash>"
}

どちらのプロパティも、差分更新を作成するときに DiffGen ツールへの入力として使用した <source image file> に固有です。 実際にはソース イメージをインポートしない場合でも、インポート マニフェストにはソース SWU イメージに関する情報が必要です。 デバイス上の差分コンポーネントでは、差分更新をダウンロードした後に、ソース イメージに関するこのメタデータを使用してデバイス上のそのイメージを見つけます。

downloadHandler オブジェクトは、Device Update エージェントで関連ファイル機能を使用して差分更新を調整する方法を指定するために使用します。 差分機能のために独自のバージョンの Device Update エージェントをカスタマイズしない限り、次の downloadHandler を使用します。

"downloadHandler": {
  "id": "microsoft/delta:1"
}

Azure CLI az iot du update init v5 コマンドを使用すると、差分更新のためのインポート マニフェストを生成できます。 詳細については、基本的なインポート マニフェストの作成に関するページを参照してください。

--update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version> --compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report> --step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'> --file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1 --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>"}' 

生成されたインポート マニフェスト JSON をファイル拡張子 .importmanifest.json を付けて保存します。

Azure Portal を使用したインポート

インポート マニフェストを作成したら、Device Update for IoT Hub への更新の追加に関するページの手順に従って、差分更新をインポートします。 インポートには、次の項目を含める必要があります。

• 前の手順で作成した *importmanifest.json ファイル
• DiffGen ツールで作成された <recompressed_target_file> SWU イメージ
• DiffGen ツールで作成された <delta file>

デバイスへの差分更新のデプロイ

Azure portal での差分更新のデプロイ エクスペリエンスは、通常のイメージ更新のデプロイと同じです。 詳細については、Device Update を使用した更新のデプロイに関するページを参照してください。

差分更新のためのデプロイを作成すると、Device Update サービスおよびクライアントでは、デプロイ先のデバイスごとの有効な差分更新が存在するかどうかを自動的に判定します。 有効な差分が見つかると、差分更新をダウンロードしてそのデバイスにインストールします。

有効な差分更新が見つからない場合は、フォールバックとして、代わりに完全なイメージ更新 (再圧縮されたターゲット SWU イメージ) がダウンロードされます。 この方法により、更新のデプロイ先のすべてのデバイスが適切なバージョンになります。

差分更新のデプロイの結果として、次の 3 つが考えられます。

• 差分更新が正常にインストールされ、デバイスは新しいバージョンで動作しています。
• 差分更新は使用不可であったか、またはインストールできなかったが、完全なイメージのフォールバック インストールが成功し、デバイスは新しいバージョンで動作しています。
• 差分とフォールバック インストールの両方が失敗し、デバイスは引き続き古いバージョンで動作しています。

どのエラーの結果が発生したかを判定するには、エラー状態にある任意のデバイスを選択することによって、エラー コードと拡張エラー コードを含むインストール結果を表示できます。 また、必要に応じて、複数の失敗したデバイスからログを収集することもできます。

• 差分更新が成功した場合は、デバイスに [成功] 状態が表示されます。

• 差分更新は失敗したが、完全なイメージへのフォールバックが成功した場合は、デバイスに次のエラー状態が表示されます。

  • resultCode: <0 より大きい値>
  • extendedResultCode: <0 以外の値>

失敗した更新をトラブルシューティングする

失敗した更新では、次の手順を使用して解釈できるエラー状態が表示されます。 まず、result.h 内の Device Update エージェントのエラーから始めます。

差分更新ダウンロード ハンドラー機能に固有の Device Update エージェントのエラーは 0x9 で始まります。

result.h 内にエラー コードが存在しない場合は、おそらく、Device Update エージェントとは別の差分プロセッサ コンポーネントのエラーです。 その場合、extendedResultCode は、16 進形式 0x90AXXXXX の負の 10 進数値です。

• 9 は "差分機能"
• 0A は "差分プロセッサ コンポーネント" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
• XXXXX は Field Installation Tool (FIT) 差分プロセッサからの 20 ビットのエラー コード

エラー コード情報に基づいて問題を解決できない場合は、さらにサポートを受けるために GitHub の問題を提出してください。

関連するコンテンツ

• Azure Device Update for IoT Hub インポート マニフェスト スキーマ
• 一般的な問題のトラブルシューティング