Importation de mises à jour dans Device Update pour IoT Hub : schéma et autres informations

Article
03/22/2023

Si vous souhaitez importer une mise à jour dans Device Update pour IoT Hub, veillez à consulter d’abord les concepts et le guide pratique. Si vous vous intéressez aux détails du schéma du manifeste d’importation lui-même, consultez ce qui suit.

Le schéma JSON du manifeste d’importation est hébergé sur SchemaStore.org.

schéma

Propriété	Type	Description	Obligatoire
$schema	`string`	Informations de référence sur le schéma JSON.	Non
updateId	`updateId`	Identificateur de mise à jour unique.	Oui
description	`string`	Description facultative de la mise à jour. Longueur maximale : 512 caractères	Non
compatibilité	`compatibility`	Liste des jeux de propriétés d’appareil avec lesquels cette mise à jour est compatible.	Oui
instructions	`instructions`	Instructions d’installation de la mise à jour.	Oui
fichiers	`file` `[0-10]`	Liste des fichiers de charge utile de mise à jour. La somme de toutes les tailles de fichier ne doit pas dépasser 2 Go. Peut être vide ou null si toutes les étapes d’instructions sont des étapes de référence.	Non
manifestVersion	`string`	Version du schéma du manifeste d’importation. Doit être 5.0.	Oui
createdDateTime	`string`	Le manifeste d’importation de date et d’heure a été créé au format ISO 8601. Exemple : `"2020-10-02T22:18:04.9446744Z"`	Oui

Aucune propriété supplémentaire n’est autorisée.

Objet updateId

L’objet updateID est un identificateur unique pour chaque mise à jour.

Propriété	Type	Description	Obligatoire
provider	`string`	Entité qui crée ou qui est directement responsable de la mise à jour. Il peut s’agir d’un nom de société. Modèle : `^[a-zA-Z0-9.-]+$` Longueur maximale : 64 caractères	Oui
name	`string`	Identificateur d’une classe de mise à jour. Il peut s’agir d’un nom de classe ou de modèle d’appareil. Modèle : `^[a-zA-Z0-9.-]+$` Longueur maximale : 64 caractères	Oui
version	`string`	Numéros de version séparés par des points et composés de deux à quatre parties. Chaque partie doit être un nombre compris entre 0 et 2147483647 et les zéros non significatifs seront supprimés. Modèle : `^\d+(?:\.\d+)+$` Exemples : `"1.0"`, `"2021.11.8"`	Oui

Aucune propriété supplémentaire n’est autorisée.

Par exemple :

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

objet compatibilité

L’objet compatibilité décrit les propriétés d’un appareil avec lequel cette mise à jour est compatible.

Type : object
Nombre minimal de propriétés : 1
Nombre maximal de propriétés : 5

Chaque propriété est une paire nom-valeur de type chaîne.

Longueur minimale du nom de propriété : 1
Longueur maximale du nom de propriété : 32
Longueur minimale de la valeur de propriété : 1
Longueur maximale de la valeur de propriété : 64

Le même ensemble de propriétés de compatibilité ne peut pas être utilisé avec plus d’une combinaison de fournisseur de mise à jour et de nom.

Par exemple :

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

Objet instructions

L’objet instructions fournit les instructions d’installation de mise à jour. L’objet instructions contient une liste d’étapes à suivre. Ces étapes peuvent être du code à exécuter ou un pointeur vers une autre mise à jour.

Propriété	Type	Description	Obligatoire
steps	`array[1-10]`	Chaque élément du tableau doit être un objet inlineStep ou un objet referenceStep.	Oui

Aucune propriété supplémentaire n’est autorisée.

Par exemple :

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

Objet inlineStep

Un objet étape inline est une étape d’instruction d’installation qui exécute du code.

Propriété	Type	Description	Obligatoire
type	`string`	Type d’étape d’instructions qui effectue l’exécution du code. Doit être `inline`. La valeur par défaut est `inline` si aucune valeur n’est fournie.	Non
description	`string`	Description facultative de l’étape d’instructions. Longueur maximale : 64 caractères	Non
handler	`string`	Identité du gestionnaire sur l’appareil, qui peut exécuter cette étape. Modèle : `^\S+/\S+:\d{1,5}$` Longueur minimale : 5 caractères Longueur maximale : 32 caractères Exemples : `microsoft/script:1`, `microsoft/swupdate:1`, `microsoft/apt:1`	Oui
files	`string` `[1-10]`	Noms des fichiers de mise à jour définis en tant qu’objets fichier que l’agent passe au gestionnaire. Chaque élément du tableau doit avoir une longueur comprise entre 1 et 255 caractères.	Oui
handlerProperties	`inlineStepHandlerProperties`	Objet JSON que l’agent passera au gestionnaire en tant qu’arguments.	Non

Aucune propriété supplémentaire n’est autorisée.

Par exemple :

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

Objet referenceStep

Un objet étape reference est une étape d’instruction d’installation qui installe une autre mise à jour.

Propriété	Type	Description	Obligatoire
type	`referenceStepType`	Type d’étape d’instructions qui installe une autre mise à jour. Doit être `reference`.	Oui
description	`stepDescription`	Description facultative de l’étape d’instructions. Longueur maximale : 64 caractères	Non
updateId	`updateId`	Identificateur de mise à jour unique.	Oui

Aucune propriété supplémentaire n’est autorisée.

Par exemple :

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

Objet file

Un objet fichier est un fichier de charge utile de mise à jour, par exemple, binaire, microprogramme, script, etc. Chaque objet fichier doit être unique au sein d’une mise à jour.

Propriété	Type	Description	Obligatoire
filename	`string`	Nom du fichier de charge utile de mise à jour. Longueur maximale : 255 caractères	Oui
sizeInBytes	`number`	Taille du fichier, en nombre d’octets. Taille maximale : 2147483648 octets	Oui
hashes	`fileHashes`	Hachages de fichier encodés en base64 avec le nom d’algorithme comme clé. Au moins l’algorithme SHA-256 doit être spécifié, et un algorithme supplémentaire peut être spécifié s’il est pris en charge par l’agent. Consultez ce qui suit pour plus d’informations sur la façon de calculer le hachage.	Oui
relatedFiles	`relatedFile[0-4]`	Collection de fichiers associés à un ou plusieurs de vos fichiers de charge utile principaux.	Non
downloadHandler	`downloadHandler`	Spécifie comment traiter les fichiers associés.	Oui uniquement si vous utilisez relatedFiles

Aucune propriété supplémentaire n’est autorisée.

Par exemple :

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

Objet fileHashes

Hachages de fichier encodés en base64 avec le nom d’algorithme en tant que clé. L’algorithme SHA-256 doit être impérativement spécifié. D’autres algorithmes peuvent également être spécifiés si l’agent les prend en charge. Pour un exemple de calcul correct du hachage, voir la fonction Get-AduFileHashes dans le script AduUpdate.psm1.

Propriété	Type	Description	Obligatoire
sha256	`string`	Valeur de hachage de fichier encodée en base64 à l’aide de l’algorithme SHA-256.	Oui

Des propriétés supplémentaires sont autorisées.

Par exemple :

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

Objet relatedFiles

Collection de fichiers associés à un ou plusieurs de vos fichiers de charge utile principaux.

Propriété	Type	Description	Obligatoire
filename	`string`	Liste des fichiers associés associés à un fichier de charge utile principal.	Oui
sizeInBytes	`number`	Taille du fichier, en nombre d’octets. Taille maximale : 2147483648 octets	Oui
hashes	`fileHashes`	Hachages de fichier encodés en base64 avec le nom d’algorithme comme clé. Au moins l’algorithme SHA-256 doit être spécifié, et un algorithme supplémentaire peut être spécifié s’il est pris en charge par l’agent. Consultez ce qui suit pour plus d’informations sur la façon de calculer le hachage.	Oui
properties	`relatedFilesProperties` `[0-5]`	Limite de 5 paires clé-valeur, où la clé est limitée à 64 caractères ASCII et la valeur est JObject (avec jusqu’à 256 caractères ASCII).	Non

Des propriétés supplémentaires sont autorisées.

Par exemple :

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

Pour plus d’informations, consultez Utiliser la fonctionnalité de fichiers associés pour référencer plusieurs fichiers de mise à jour.

Objet downloadHandler

Spécifie comment traiter les fichiers associés.

Propriété	Type	Description	Obligatoire
id	`string`	Identificateur pour downloadHandler. Limite de 64 caractères ASCII.	Oui

Aucune propriété supplémentaire n’est autorisée.

Par exemple :

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

Étapes suivantes

En savoir plus sur les concepts d’importation.

Si vous êtes prêt, suivez le Guide pratique d’importation, qui vous guidera pas à pas tout au long du processus d’importation.

Importation de mises à jour dans Device Update pour IoT Hub : schéma et autres informations

schéma

Objet updateId

objet compatibilité

Objet instructions

Objet inlineStep

Objet referenceStep

Objet file

Objet fileHashes

Objet relatedFiles

Objet downloadHandler

Étapes suivantes

Ressources supplémentaires