Device Update for IoT Hub への更新プログラムのインポート

[アーティクル]
06/27/2022

Device Update for IoT Hub からデバイスに更新プログラムを展開するには、まず、その更新プログラムをデバイス更新サービスに "インポート" する必要があります。この記事は、更新プログラムをインポートするときに理解しておくべき重要な概念の概要を示します。

インポートマニフェスト

インポートマニフェストは、インポートする更新プログラムに関する重要な情報を定義する JSON ファイルです。インポート処理の一環として、インポートマニフェストと関連付けられている更新プログラムファイル (ファームウェア更新パッケージなど) の両方を送信します。インポートマニフェストで定義されているメタデータは、更新プログラムの取り込みに使用されます。一部のメタデータは展開時にも使用されます。たとえば、更新プログラムが正しくインストールされたかどうかを検証するときなどです。

次に例を示します。

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  },
  "isDeployable": false,
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ],
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "firmware.swu"
        ],
        "handlerProperties": {
          "installedCriteria": "1.0"
        }
      }
    ]
  },
  "files": [
    {
      "filename": "firmware.swu",
      "sizeInBytes": 7558,
      "hashes": {
        "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
      }
    }
  ],
  "createdDateTime": "2022-01-19T06:23:52.6996916Z",
  "manifestVersion": "4.0"
}

インポートマニフェストには、Device Update for IoT Hub の重要な概念を表すいくつかの項目が含まれています。このセクションでは、それらの項目の概要を説明します。完全なインポートスキーマの詳細については、マニフェスト JSON スキーマのインポートに関するページを参照してください。

更新プログラム ID

更新プログラム ID (updateId) は、Device Update for IoT Hub での更新プログラムの一意の識別子です。これは、次の 3 つの部分で構成されます。

プロバイダー: 更新プログラムを作成または直接担当するエンティティ。多くの場合、会社名になります。
名前: 更新プログラムのクラスの識別子。多くの場合、デバイスクラスまたはモデルの名前になります。
バージョン: 同じプロバイダーと名前を持つ他の更新プログラムとこの更新プログラムを区別するためのバージョン番号。

次に例を示します。

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  }
}

Note

UpdateId は Device Update サービスでのみ使用され、デバイス上の実際のソフトウェアコンポーネントの ID とは異なる場合があります。

互換性

"互換性 (compatibility)" は、更新プログラムをインストールできるデバイスの条件を定義します。これにはデバイスのプロパティ (デバイスから報告される任意のキーと値のペアのセット) が含まれます。一致するプロパティを持つデバイスだけがデプロイの対象になります。更新プログラムは、複数のデバイスプロパティセットを持つことで、複数のデバイスクラスとの互換性がある場合があります。

次に示す更新プログラムの例は、デバイスの製造元とモデルとして Contoso と Toaster を報告するデバイスにのみデプロイできます。

{
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ]
}

Instructions

"命令 (instructions)" の部分には、デバイスエージェントが更新プログラムをインストールするために必要な情報または "手順" が含まれます。最も単純な更新プログラムには、1 つの "インライン" ステップが含まれています。この手順では、デバイスエージェントに登録されている "ハンドラー" を使用して、含まれるペイロードファイルを実行します。

{
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

ヒント

handler は、インポートマニフェストバージョン 3.0 以前の updateType と同じです。

更新プログラムには、複数のステップが含まれる場合があります。

{
  "instructions": {
    "steps": [
      {
        "description": "pre-install script",
        "handler": "microsoft/script:1",
        "handlerProperties": {
          "arguments": "--pre-install"
        },
        "files": [
          "configure.sh"
        ]
      },
      {
        "description": "firmware package",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

更新プログラムには、独自のインポートマニフェストを使用して別の更新プログラムをインストールするようにデバイスエージェントに指示する "参照" ステップが含まれている場合があり、このとき更新プログラムの親と子の関係が確立されます。たとえば、Toaster の更新プログラムには、2 つの子の更新プログラムが含まれている場合があります。

{
  "instructions": {
    "steps": [
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.HeatingElement",
          "version": "1.0"
        }
      },
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.Sensors",
          "version": "1.0"
        }
      }
    ]
  }
}

Note

1 つの更新プログラムに、"インライン" ステップと "参照" ステップがいくつも含まれる場合があります。

ファイル

"ファイル (files)" の部分には、名前、サイズ、ハッシュなど、更新ペイロードファイルのメタデータが含まれています。 Device Update for IoT Hub では、インポートプロセス中の整合性の検証に、このメタデータが使用されます。その後、同じ情報がデバイスエージェントに転送され、インストール前に整合性の検証が繰り返されます。

Note

参照ステップのみを含む更新プログラムには、親の更新プログラムに更新ペイロードファイルがありません。

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

任意のテキストエディターを使用して、インポートマニフェスト JSON ファイルを作成できます。また、GitHub の Azure/iot-hub-device-update には、インポートマニフェストをプログラムで作成するためのサンプルスクリプトもあります。

重要

Azure portal を使用してインポートする場合、インポートマニフェスト JSON ファイル名の末尾は .importmanifest.json にする必要があります。

ヒント

インポートマニフェストを作成するときにオートコンプリートと JSON スキーマの検証を有効にするには、Visual Studio Code を使用します。

更新プログラムのインポートの制限

各 Device Update for IoT Hub インスタンスには、一定の制約が適用されます。まだ確認していない場合は、Device Update の制約に関するページを参照してください。

次のステップ

インポートプロセスの詳細については、インポートする更新の準備に関するページを参照してください。
インポートマニフェストスキーマについて確認します。

次の方法で共有

Device Update for IoT Hub への更新プログラムのインポート

インポートマニフェスト

更新プログラム ID

互換性

Instructions

ファイル

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

更新プログラムのインポートの制限

次のステップ

その他のリソース

次の方法で共有

Device Update for IoT Hub への更新プログラムのインポート

インポート マニフェスト

更新プログラム ID

互換性

Instructions

ファイル

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

更新プログラムのインポートの制限

次のステップ

その他のリソース

インポートマニフェスト

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