Azure Device Update for IoT Hub インポートマニフェストスキーマ

[アーティクル]
01/11/2025

Azure Device Update for Iot Hub に更新プログラムをインポートする場合は、更新プログラムに関する重要な情報を定義する関連する JSON インポートマニフェストファイルも送信します。この記事では、JSON インポートマニフェストファイルの作成に使用されるスキーマについて説明します。

インポートマニフェストの概念とファイル構造の詳細については、「Azure Device Update for IoT Hub のインポートマニフェスト」を参照してください。ファイルを作成する方法については、「更新プログラムを準備して Device Update for IoT Hub にインポートする」を参照してください。

[スキーマ]

インポートマニフェスト JSON スキーマは、 SchemaStore.org でホストされ、次のプロパティで構成されます。その他のプロパティは使用できません。

プロパティ	タイプ	内容	必須
$schema	`string`	JSON スキーマ参照。	いいえ
updateId	`updateId`	一意の更新プログラム識別子。	はい
description	`string`	省略可能な更新プログラムの説明。最大長: 512 文字。	いいえ
compatibility	`compatibility`	この更新プログラムと互換性のあるデバイスプロパティセットの一覧。	はい
instructions	`instructions`	更新プログラムのインストール手順。	はい
files	`file` `[0-10]`	更新プログラムのペイロードファイルの一覧。すべてのファイルサイズの合計が 2 GB を超えることはできません。すべての命令ステップが参照ステップである場合は、空または null を指定できます。	いいえ
manifestVersion	`string`	マニフェストスキーマのバージョンをインポートします。 5.0 である必要があります。	はい
createdDateTime	`string`	マニフェストの作成日時を ISO 8601 形式でインポートします (例: `"2020-10-02T22:18:04.9446744Z"`)。	はい

オブジェクトの更新

updateID オブジェクトは、更新ごとに一意の識別子です。

プロパティ	タイプ	内容	必須
プロバイダー	`string`	更新プログラムを作成または直接担当するエンティティ。 provider には会社名を指定できます。パターン: `^[a-zA-Z0-9.-]+$` 最大文字数: 64 字	はい
name	`string`	更新プログラムのクラスの識別子。 name は、デバイスクラスまたはモデル名にすることができます。パターン: `^[a-zA-Z0-9.-]+$` 最大文字数: 64 字	はい
version	`string`	2 つから 4 つの部分からなるドット区切りの数値バージョン番号。各部分は 0 から 2147483647 の間の数値である必要があり、先頭のゼロは削除されます。パターン: `^\d+(?:\.\d+)+$` 例: `"1.0"`、`"2021.11.8"`	はい

その他のプロパティは使用できません。

次に例を示します。

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

compatibility オブジェクト

compatibility オブジェクトは、この更新プログラムと互換性のあるデバイスの 1 から 5 個のプロパティを記述します。各プロパティは、string 型の名前と値のペアです。名前の長さは 1 ~ 32 文字で、値の長さは 1 ~ 64 文字にする必要があります。互換性プロパティの同一のセットは、複数のプロバイダーと名前の組み合わせで使用できません。

次に例を示します。

{
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "Toaster"
    }
  ]
}

instructions オブジェクト

instructions オブジェクトは、更新プログラムのインストール手順を提供します。 instructions オブジェクトには、実行する steps のリストが含まれています。その他のプロパティは使用できません。

ステップには、実行するコードまたは他の更新プログラムへのポインターを指定できます。 type 値が指定されていない場合、ステップオブジェクトは既定で inline になります。

プロパティ	タイプ	内容	必須
steps	`array[1-10]`	`steps` 配列内の各要素は、inlineStep オブジェクトまたは referenceStep オブジェクトである必要があります。	はい

次に例を示します。

{
  "instructions": {
    "steps": [
      {
        "type": "inline",
        ...
      },
      {
        "type": "reference",
        ...
      }
    ]
  }
}

インラインステップオブジェクト

inline ステップオブジェクトは、コード実行を行うインストール命令ステップです。

プロパティ	タイプ	内容	必須
type	`string`	コード実行を行う命令ステップの種類。 `inline`である必要があります。値が指定されていない場合は既定の `inline` になります。	いいえ
description	`string`	省略可能な命令ステップの説明。最大長: 64 文字。	いいえ
handler	`string`	このステップを実行できるデバイス上のハンドラーの ID。パターン: `^\S+/\S+:\d{1,5}$` 最小長: 5 文字最大文字数: 32 字例: `microsoft/script:1`、`microsoft/swupdate:2`、`microsoft/apt:1`	はい
files	`string` `[1-10]`	エージェントがハンドラーに渡す file オブジェクトとして定義された更新プログラムファイルの名前。各要素の長さは 1 ~ 255 文字にする必要があります。	はい
handlerProperties	`inlineStepHandlerProperties`	エージェントが引数としてハンドラーに渡す JSON オブジェクト。	いいえ

その他のプロパティは使用できません。

次に例を示します。

{
  "steps": [
    {
      "description": "pre-install script",
      "handler": "microsoft/script:1",
      "handlerProperties": {
        "arguments": "--pre-install"
      },
      "files": [
        "configure.sh"
      ]
    }
  ]
}

参照ステップオブジェクト

reference ステップオブジェクトは、別の更新プログラムをインストールするためのインストール手順です。

プロパティ	タイプ	内容	必須
type	`referenceStepType`	別の更新プログラムをインストールする命令ステップの種類。 `reference`である必要があります。	はい
description	`stepDescription`	省略可能な命令ステップの説明。最大長: 64 文字。	いいえ
updateId	`updateId`	一意の更新プログラム識別子。	はい

その他のプロパティは使用できません。

次に例を示します。

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

Files オブジェクト

各 files オブジェクトは、バイナリ、ファームウェア、スクリプトファイルなどの更新ペイロードファイルであり、更新プログラム内で一意である必要があります。

プロパティ	タイプ	内容	必須
ファイル名	`string`	更新プログラムのペイロードファイル名。最大文字数: 255 字	はい
sizeInBytes	`number`	ファイルサイズ (バイト数)。最大サイズ: 2147483648 バイト	はい
hashes	`fileHashes`	アルゴリズム名をキーとして使用する Base64 でエンコードされたファイルハッシュ。少なくとも SHA-256 アルゴリズムを指定する必要があり、エージェントでサポートされている場合は追加のアルゴリズムを指定できます。ハッシュの計算方法の詳細については、Hashes オブジェクトを参照してください。	はい
relatedFiles	`relatedFile[0-4]`	1 つ以上のプライマリペイロードファイルに関連するファイルのコレクションです。詳細については、relatedFiles オブジェクトを参照してください。	いいえ
downloadHandler	`downloadHandler`	関連ファイルの処理方法を指定します。	はい (`relatedFiles` を使用している場合)。詳細については、downloadHandler オブジェクトを参照してください。

その他のプロパティは使用できません。

次に例を示します。

{
  "files": [
    {  
      "fileName": "full-image-file-name",
      "sizeInBytes": 12345,
      "hashes": {...},
      "relatedFiles": [
        {
          "fileName": "delta-from-v1-file-name",
          "sizeInBytes": 1234,
          "hashes": {
            "SHA256": "delta-from-v1-file-hash"
          },
          "properties": {...}
        }  
      ],
      "downloadHandler": {
        "id": "microsoft/delta:1"
        }
    }
  ]
}

Hashes オブジェクト

hashes オブジェクトには、キーとしてアルゴリズム名を持つ base64 でエンコードされたファイルハッシュが含まれています。少なくとも SHA-256 アルゴリズムを指定する必要があり、エージェントでサポートされている場合は他のアルゴリズムを指定できます。ハッシュを正しく計算する方法の例については、AduUpdate.psm1 スクリプト内の Get-AduFileHashes 関数を参照してください。

プロパティ	タイプ	内容	必須
sha256	`string`	SHA-256 アルゴリズムを使用する Base64 でエンコードされたファイルハッシュ値。	はい

その他のプロパティを使用できます。

次に例を示します。

{
  "hashes": {
    "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
  }
}

relatedFiles オブジェクト

relatedFiles オブジェクトには、1 つ以上のプライマリペイロードファイルに関連するファイルのコレクションが含まれています。詳細については、「関連ファイル機能を使用して複数の更新ファイルを参照する」を参照してください。

プロパティ	タイプ	内容	必須
ファイル名	`string`	プライマリペイロードファイルに関連付けられている関連ファイルの一覧。	はい
sizeInBytes	`number`	ファイルサイズ (バイト数)。最大サイズ: 2147483648 バイト。	はい
hashes	`fileHashes`	アルゴリズム名をキーとして使用する Base64 でエンコードされたファイルハッシュ。詳細については、Hashes オブジェクトを参照してください。	はい
properties	`relatedFilesProperties` `[0-5]`	最大 5 ペアです。なお、キーは 64 の ASCII 文字に制限され、値は JObject (最大 256 ASCII 文字) です。	いいえ

その他のプロパティを使用できます。

次に例を示します。

"relatedFiles": [
  {
    "filename": "in1_in2_deltaupdate.dat",
    "sizeInBytes": 102910752,
    "hashes": {
      "sha256": "2MIldV8LkdKenjJasgTHuYi+apgtNQ9FeL2xsV3ikHY="
    },
    "properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "YmFYwnEUddq2nZsBAn5v7gCRKdHx+TUntMz5tLwU+24="
    }
  }
],

downloadHandler オブジェクト

downloadHandler オブジェクトは、関連ファイルの処理方法を指定します。

プロパティ	タイプ	内容	必須
id	`string`	`downloadHandler` の識別子です。 64 の ASCII 文字の制限。	はい (`relatedFiles` を使用している場合)

その他のプロパティは使用できません。

次に例を示します。

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

次の方法で共有

Azure Device Update for IoT Hub インポートマニフェストスキーマ

[スキーマ]

オブジェクトの更新

compatibility オブジェクト

instructions オブジェクト

インラインステップオブジェクト

参照ステップオブジェクト

Files オブジェクト

Hashes オブジェクト

relatedFiles オブジェクト

downloadHandler オブジェクト

フィードバック

その他のリソース

次の方法で共有

Azure Device Update for IoT Hub インポート マニフェスト スキーマ

[スキーマ]

オブジェクトの更新

compatibility オブジェクト

instructions オブジェクト

インライン ステップ オブジェクト

参照ステップ オブジェクト

Files オブジェクト

Hashes オブジェクト

relatedFiles オブジェクト

downloadHandler オブジェクト

関連するコンテンツ

フィードバック

その他のリソース

Azure Device Update for IoT Hub インポートマニフェストスキーマ

インラインステップオブジェクト

参照ステップオブジェクト