Azure Device Update for IoT Hub APT マニフェスト
この記事では、APT 更新ハンドラーに必要な更新の詳細を記述した JSON ファイルである APT マニフェストについて説明します。 このファイルは、他の更新プログラムと同様に、Device Update にインポートできます。 詳細については、「Device Update に更新プログラムをインポートする」を参照してください。
APT マニフェストを更新プログラムとして Device Update エージェントに配信すると、そのエージェントはマニフェストを処理し、必要な操作を実行します。 必要な操作には、APT マニフェスト ファイルに指定されているパッケージとその依存関係を指定リポジトリからダウンロードし、インストールする作業が含まれます。
Device Update は、APT 更新の種類と APT 更新ハンドラーをサポートしています。 このサポートによりデバイス更新エージェントは、インストールされている Debian パッケージを評価し、必要なパッケージを更新することができます。
APT マニフェストを使用して、Device Update エージェント自身とその依存関係を更新できます。 他のパッケージと同様に、APT マニフェストで Device Update エージェンの名前と必要なバージョンをリストします。 その後、この APT マニフェストをインポートし、Device Update パイプラインを通じて展開できます。
[スキーマ]
APT マニフェスト ファイルは、バージョン管理されたスキーマを含む JSON ファイルです。
{
"name": "<name>",
"version": "<version>",
"packages": [
{
"name": "<package name>",
"version": "<version specifier>"
}
]
}
次に例を示します。
{
"name": "contoso-iot-edge",
"version": "1.0.0.0",
"packages": [
{
"name" : "thermocontrol",
"version" : "1.0.1"
},
{
"name" : "tempreport",
"version" : "2.0.0"
}
]
}
各 APT マニフェストには次のプロパティが含まれています。
-
Name: この APT マニフェストの名前。シナリオに合ったわかりやすい名前または ID を指定できます。 たとえば、
contoso-iot-edgeのようにします。 -
Version: この APT マニフェストのバージョン番号 (例:
1.0.0.0)。 -
Packages: パッケージ固有のプロパティを含むオブジェクトの一覧。
-
Name: パッケージの名前または ID (例:
iotedge)。 -
Version: 必要なパッケージ バージョンの基準 (例:
1.0.8-2)。
-
Name: パッケージの名前または ID (例:
バージョン管理
APT マニフェストでは、正確なバージョン番号のみがサポートされます。 バージョン番号は、<epoch>:<upstream_version>-<debian_revision> 形式の、必要な Debian パッケージ バージョンです。epoch は unsigned int で、upstream_version は数字で始まり、英数字と、.、,、+、-、~ などの文字を含めることができます。 バージョン値に等号を含めることはできません。
たとえば、"name":"iotedge" および "version":"1.0.8-2" は、コマンド apt-get install iotedge=1.0.8-2 を使用してパッケージをインストールすることと同じです。 バージョン 1.0.8 は、1.0.8-0 と同じです。
バージョンを省略した場合、Device Update は指定したパッケージの使用可能な最新バージョンをインストールします。 Debian パッケージのバージョン管理方法の詳細については、「Debian ポリシー マニュアル」を参照してください。
Note
インストールする依存パッケージが自動的に解決されると、APT パッケージ マネージャーは、パッケージによって指定されたバージョン管理の要件を無視します。 依存パッケージの明示的なバージョンを指定しない限り、特定のバージョンに対する厳格な要件 (=) がパッケージ自体により指定されている場合でも、最新のバージョンが使用されます。 このように自動で解決されると、条件が満たされない依存関係に関するエラーが発生する可能性があります。
したがって、特定のバージョンのパッケージをインストールする場合は、インストールする依存パッケージの明示的なバージョンも含めることをお勧めします。 詳細については、「apt-get が Debian/Ubuntu パッケージの固定バージョンに対する依存関係を正しく解決しない」を参照してください。
特定のバージョンの Azure IoT Edge セキュリティ デーモンを更新する場合は、必要なバージョンの aziot-edge パッケージと、それに依存する aziot-identity-service パッケージを APT マニフェストに含める必要があります。 詳しくは、IoT Edge を更新する方法に関する記事を参照してください。
インストール基準
APT マニフェストの推奨インストール基準値は <name>-<version> です。ここで、<name> は APT マニフェストの名前、<version> はそのバージョンです。 たとえば、contoso-iot-edge-1.0.0.0 のようにします。
パッケージの削除
APT マニフェストを使用して、インストールされているパッケージをデバイスから削除することもできます。 1 つの APT マニフェストで、複数のパッケージの削除、追加、更新を行うことができます。
パッケージを削除するには、パッケージ名の後にマイナス記号 - を追加します。 削除しようとしているパッケージのバージョン番号は含めないでください。 APT マニフェストを使用してパッケージを削除しても、その依存関係と構成は削除されません。
たとえば、次の APT マニフェストは、パッケージ contoso1 を、それが展開されているすべてのデバイスから削除します。
{
"name": "contoso-video",
"version": "2.0.0.1",
"packages": [
{
"name" : "contoso1-"
}
]
}
APT マニフェスト作成ガイドライン
APT マニフェストを作成するときは、次のガイドラインに留意してください。
APT マニフェストは必ず、整形式の JSON ファイルにします。
各 APT マニフェストに一意のバージョンを指定します。 実際のシナリオで合理的であり、簡単に理解できるように、標準化された方法を使用して、APT マニフェストのバージョンをインクリメントするようにします。
個々のパッケージの必要な状態に関しては、デバイスにインストールするパッケージの正確な名前とバージョンを指定します。 必ずソース パッケージ リポジトリの内容に対して値を検証します。
APT マニフェスト内のパッケージを、インストールまたは削除する順序でリストします。
必要な結果が得られるように、必ずテスト デバイスでパッケージのインストールを検証します。
特定のバージョンのパッケージをインストールする場合 (例:
iotedge 1.0.9-1) は、インストールする依存パッケージの明示的なバージョンも含めます (例:libiothsm 1.0.9-1)。必須ではありませんが、APT マニフェストを常に累積的にすることで、デバイスが不明な状態になることを回避できます。 累積的な更新プログラムを使用すると、インストールの失敗やオフラインが原因でデバイスが更新をスキップした場合でも、デバイスにすべての関連パッケージの必要なバージョンが確実にインストールされます。
たとえば、次の基本 APT マニフェストがあるとします。
{ "name": "contoso-iot-edge", "version": "1.0", "packages": [ { "name": "contoso1", "version": "1.0.1" } ] }次のバージョン 2.0 更新プログラムには
contoso2パッケージが含まれますが、contoso1パッケージは含まれません。 2.0 更新プログラムを受信するすべてのデバイスにcontoso1パッケージがインストールされているとは限りません。{ "name": "contoso-iot-edge", "version": "2.0", "packages": [ { "name": "contoso2", "version": "3.0.2" } ] }次のバージョン 2.0 の累積的な更新プログラムには、
contoso1パッケージとcontoso2パッケージの両方が含まれています。{ "name": "contoso-iot-edge", "version": "2.0", "packages": [ { "name": "contoso1", "version": "1.0.1" }, { "name": "contoso2", "version": "3.0.2" } ] }