Comprendre les schémas de message
Le registre de schémas est une fonctionnalité fournie par le Registre de Dispositifs Azure (préversion). Il s’agit d’un référentiel synchronisé dans le cloud et à la périphérie. Le registre de schémas stocke les définitions des messages provenant des ressources de périphérie, puis expose une API pour accéder à ces schémas à la périphérie.
Le Connecteur OPC UA peut créer des schémas de message et les ajouter au registre de schémas. Les clients peuvent également charger des schémas dans l’interface utilisateur web de l’expérience des opérations ou à l’aide de modèles ARM/Bicep.
Les services de périphérie utilisent des schémas de message pour filtrer et transformer les messages à mesure qu’ils sont acheminés dans votre scénario de périphérie industriel.
Les schémas sont des documents qui décrivent le format d’un message et son contenu pour permettre le traitement et la contextualisation.
Définitions de schémas de message
Le registre de schémas attend les champs obligatoires suivants dans un schéma de message :
| Champ obligatoire | Définition |
|---|---|
$schema |
http://json-schema.org/draft-07/schema# ou Delta/1.0. Dans les flux de données, les schémas JSON sont utilisés pour les points de terminaison sources tandis que les schémas Delta sont utilisés pour les points de terminaison de destination. |
type |
Object |
properties |
Définition du message. |
Exemples de schémas
Les exemples de schémas suivants illustrent la définition de schémas de message dans chaque format.
JSON :
{
"$schema": "http://json-schema.org/draft-07/schema#",
"name": "foobarbaz",
"description": "A representation of an event",
"type": "object",
"required": [ "dtstart", "summary" ],
"properties": {
"summary": {
"type": "string"
},
"location": {
"type": "string"
},
"url": {
"type": "string"
},
"duration": {
"type": "string",
"description": "Event duration"
}
}
}
Delta :
{
"$schema": "Delta/1.0",
"type": "object",
"properties": {
"type": "struct",
"fields": [
{ "name": "asset_id", "type": "string", "nullable": false, "metadata": {} },
{ "name": "asset_name", "type": "string", "nullable": false, "metadata": {} },
{ "name": "location", "type": "string", "nullable": false, "metadata": {} },
{ "name": "manufacturer", "type": "string", "nullable": false, "metadata": {} },
{ "name": "production_date", "type": "string", "nullable": false, "metadata": {} },
{ "name": "serial_number", "type": "string", "nullable": false, "metadata": {} },
{ "name": "temperature", "type": "double", "nullable": false, "metadata": {} }
]
}
}
Comment les flux de données utilisent-ils les schémas de message ?
Les schémas de message sont utilisés dans les trois phases d’un flux de données : définition de l’entrée source, application des transformations de données et création de la sortie de destination.
Schéma d’entrée
Chaque source de flux de données peut éventuellement spécifier un schéma de message. Si un schéma est défini pour une source de flux de données, tous les messages entrants qui ne correspondent pas au schéma sont supprimés.
Les sources de ressources ont un schéma de message prédéfini qui a été créé par le Connecteur OPC UA.
Les schémas peuvent être chargés pour les sources MQTT. Actuellement, Opérations Azure IoT prend en charge JSON pour les schémas sources (également appelés schémas d’entrée). Dans l’expérience des opérations, vous pouvez sélectionner un schéma existant ou en charger un lors de la définition d’une source MQTT :
Transformation
L’expérience des opérations utilise le schéma d’entrée comme point de départ pour vos données, ce qui facilite la sélection de transformations en fonction du format de message d’entrée connu.
Schéma de sortie
Les schémas de sortie associés à des destinations de flux de données ne sont utilisés que pour les flux de données qui sélectionnent le stockage local, Fabric, Stockage Azure (ADLS Gen2) ou Azure Data Explorer comme point de terminaison de destination. Actuellement, l’expérience Opérations Azure IoT ne prend en charge que la sortie Parquet pour les schémas de sortie.
Remarque : le format de schéma Delta est utilisé pour les sorties Parquet et Delta.
Pour ces flux de données, l’expérience des opérations applique toutes les transformations au schéma d’entrée, puis crée un schéma au format Delta. Lorsque la ressource personnalisée (CR) du flux de données est créée, elle inclut une valeur schemaRef qui pointe vers le schéma généré stocké dans le registre de schémas.
Pour charger un schéma de sortie, consultez Charger le schéma.
Charger un schéma
Le schéma d’entrée peut être chargé dans le portail d’expérience des opérations, comme décrit dans la section schéma d’entrée de cet article. Vous pouvez également charger un schéma à l’aide d’Azure CLI ou d’un modèle Bicep.
Charger le schéma avec l’interface CLI
Le groupe de commandes az iot ops schema contient des commandes pour créer, afficher et gérer des schémas dans votre registre de schémas.
Vous pouvez charger un schéma en référençant un fichier JSON ou en incluant le schéma en tant que contenu inline.
L’exemple suivant utilise des entrées minimales pour créer un schéma appelé myschema à partir d’un fichier. Quand aucun numéro de version n’est spécifié, la version du schéma est 1.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format json --type message --version-content myschema.json
L’exemple suivant crée un schéma appelé myschema à partir du contenu inline et attribue un numéro de version.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format delta --type message --version-content '{\"hello\": \"world\"}' --ver 14
Une fois la commande create terminée, vous devriez voir un objet blob dans votre conteneur de compte de stockage avec le contenu du schéma. Le nom de l’objet blob est au format schema-namespace/schema/version.
Vous pouvez voir d’autres options avec la commande d’assistance az iot ops schema -h.
Charger un schéma avec un modèle Bicep
Créez un fichier Bicep .bicep et ajoutez-y le contenu du schéma en haut sous la forme d’une variable. Cet exemple est un schéma Delta qui correspond aux données OPC UA du guide de démarrage rapide.
// Delta schema content matching OPC UA data from quickstart
// For ADLS Gen2, ADX, and Fabric destinations
var opcuaSchemaContent = '''
{
"$schema": "Delta/1.0",
"type": "object",
"properties": {
"type": "struct",
"fields": [
{
"name": "temperature",
"type": {
"type": "struct",
"fields": [
{
"name": "SourceTimestamp",
"type": "string",
"nullable": true,
"metadata": {}
},
{
"name": "Value",
"type": "integer",
"nullable": true,
"metadata": {}
},
{
"name": "StatusCode",
"type": {
"type": "struct",
"fields": [
{
"name": "Code",
"type": "integer",
"nullable": true,
"metadata": {}
},
{
"name": "Symbol",
"type": "string",
"nullable": true,
"metadata": {}
}
]
},
"nullable": true,
"metadata": {}
}
]
},
"nullable": true,
"metadata": {}
},
{
"name": "Tag 10",
"type": {
"type": "struct",
"fields": [
{
"name": "SourceTimestamp",
"type": "string",
"nullable": true,
"metadata": {}
},
{
"name": "Value",
"type": "integer",
"nullable": true,
"metadata": {}
},
{
"name": "StatusCode",
"type": {
"type": "struct",
"fields": [
{
"name": "Code",
"type": "integer",
"nullable": true,
"metadata": {}
},
{
"name": "Symbol",
"type": "string",
"nullable": true,
"metadata": {}
}
]
},
"nullable": true,
"metadata": {}
}
]
},
"nullable": true,
"metadata": {}
}
]
}
}
'''
Ensuite, dans le même fichier, juste sous le schéma, définissez pour la ressource de schéma des pointeurs vers la ressource de registre de schémas existante dont vous disposez suite au déploiement d’Opérations Azure IoT.
// Replace placeholder values with your actual resource names
param schemaRegistryName string = '<SCHEMA_REGISTRY_NAME>'
// Pointers to existing resources from AIO deployment
resource schemaRegistry 'Microsoft.DeviceRegistry/schemaRegistries@2024-09-01-preview' existing = {
name: schemaRegistryName
}
// Name and version of the schema
param opcuaSchemaName string = 'opcua-output-delta'
param opcuaSchemaVer string = '1'
// Define the schema resource to be created and instantiate a version
resource opcSchema 'Microsoft.DeviceRegistry/schemaRegistries/schemas@2024-09-01-preview' = {
parent: schemaRegistry
name: opcuaSchemaName
properties: {
displayName: 'OPC UA Delta Schema'
description: 'This is a OPC UA delta Schema'
format: 'Delta/1.0'
schemaType: 'MessageSchema'
}
}
resource opcuaSchemaVersion 'Microsoft.DeviceRegistry/schemaRegistries/schemas/schemaVersions@2024-09-01-preview' = {
parent: opcSchema
name: opcuaSchemaVer
properties: {
description: 'Schema version'
schemaContent: opcuaSchemaContent
}
}
Une fois que vous avez défini le contenu et les ressources de schéma, vous pouvez déployer le modèle Bicep pour créer le schéma dans le registre de schémas.
az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep