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

2022-06-27

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

輸入明細書

インポートマニフェストは、インポートする更新プログラムに関する重要な情報を定義する 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 または updateId は、Device Update for IoT Hub の更新プログラムの一意の識別子です。これは、次の 3 つの部分で構成されます。

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

例えば次が挙げられます。

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

注

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

互換性

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

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

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

インストラクション

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"
        ]
      }
    ]
  }
}

更新プログラムには、独自のインポートマニフェストを使用して別の更新プログラムをインストールし、親子の更新関係を確立するようにデバイスエージェントに指示する参照手順が含まれている場合があります。たとえば、トースターの更新プログラムには、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"
        }
      }
    ]
  }
}

注

更新プログラムには、インラインステップと参照ステップの任意の組み合わせが含まれる場合があります。

ファイル

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

注

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

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

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

重要

インポートマニフェストの JSON ファイル名は、Azure portal からインポートするときに .importmanifest.json で終わる必要があります。

ヒント

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

更新プログラムのインポートに関する制限

各 Device Update for IoT Hub インスタンスには、一定の制約が適用されます。まだ確認していない場合は、「デバイスの更新の制限」を参照してください。

次のステップ

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