Device Update for IoT Hub への更新プログラムのインポート: スキーマおよびその他の情報

[アーティクル]
01/10/2024

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 オブジェクト

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

プロパティ	タイプ	内容	必須
プロバイダー	`string`	更新プログラムを作成または直接担当するエンティティ。会社名を指定できます。パターン: `^[a-zA-Z0-9.-]+$` 最大文字数: 64 字	はい
name	`string`	更新プログラムのクラスの識別子。デバイスクラスまたはモデルの名前とすることができます。パターン: `^[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 オブジェクトは、この更新プログラムと互換性のあるデバイスのプロパティを記述します。

型: object
最小のプロパティ: 1
最大のプロパティ: 5

各プロパティは、string 型の名前と値のペアです。

プロパティ名の最小長: 1
プロパティ名の最大長: 32
プロパティ値の最小長: 1
プロパティ値の最大長: 64

互換性プロパティの同一のセットは、複数のプロバイダーと名前の組み合わせで使用できません。

次に例を示します。

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

instructions オブジェクト

instructions オブジェクトは、更新プログラムのインストール手順を提供します。 instructions オブジェクトには、実行するステップのリストが含まれています。ステップには、実行するコードまたは別の更新プログラムへのポインターを指定できます。

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

追加のプロパティは許可されません。

次に例を示します。

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

inlineStep オブジェクト

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

プロパティ	タイプ	内容	必須
type	`string`	コード実行を行う命令ステップの種類。 `inline`である必要があります。値が指定されていない場合は既定の `inline` になります。	いいえ
description	`string`	省略可能な命令ステップの説明。最大文字数: 64 字	いいえ
handler	`string`	このステップを実行できるデバイス上のハンドラーの ID。パターン: `^\S+/\S+:\d{1,5}$` 最大文字数: 5 字最大文字数: 32 字例: `microsoft/script:1`、`microsoft/swupdate:1`、`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"
      ]
    }
  ]
}

referenceStep オブジェクト

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

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

追加のプロパティは許可されません。

次に例を示します。

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

file オブジェクト

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

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

追加のプロパティは許可されません。

次に例を示します。

{
  "files": [
    {
      "filename": "configure.sh",
      "sizeInBytes": 7558,
      "hashes": {...}
    }
  ]
}

fileHashes オブジェクト

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

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

追加のプロパティを使用できます。

次に例を示します。

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

relatedFiles オブジェクト

1 つ以上のプライマリペイロードファイルに関連するファイルのコレクション。

プロパティ	タイプ	内容	必須
ファイル名	`string`	プライマリペイロードファイルに関連付けられている関連ファイルの一覧。	はい
sizeInBytes	`number`	ファイルサイズ (バイト数)。最大サイズ: 2147483648 バイト	はい
hashes	`fileHashes`	アルゴリズム名をキーとして使用する Base64 でエンコードされたファイルハッシュ。少なくとも SHA-256 アルゴリズムを指定する必要があり、エージェントでサポートされている場合は追加のアルゴリズムを指定できます。ハッシュの計算方法の詳細については、以下を参照してください。	はい
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 オブジェクト

関連ファイルの処理方法を指定します。

プロパティ	タイプ	内容	必須
id	`string`	downloadHandler の ID。 64 の ASCII 文字の制限。	はい

追加のプロパティは許可されません。

次に例を示します。

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

次のステップ

インポートの概念について詳しく説明します。

準備ができたら、インポートプロセスの詳しい手順が示されているインポート攻略ガイドに進んでください。

次の方法で共有

Device Update for IoT Hub への更新プログラムのインポート: スキーマおよびその他の情報

スキーマ

updateId オブジェクト

compatibility オブジェクト

instructions オブジェクト

inlineStep オブジェクト

referenceStep オブジェクト

file オブジェクト

fileHashes オブジェクト

relatedFiles オブジェクト

downloadHandler オブジェクト

次のステップ

フィードバック

その他のリソース