Comprendre les schémas de message
Le registre de schémas est une fonctionnalité fournie par le Registre de Dispositifs Azure. 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": {} }
]
}
}
Générer un schéma
Pour générer le schéma à partir d’un exemple de fichier de données, utilisez l’Assistant Génération de schéma.
Pour obtenir un tutoriel basé sur le générateur de schémas, consultez Tutoriel : Envoyer des données d’un serveur OPC UA à Azure Data Lake Storage Gen 2.
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. Actuellement, les flux de données n’effectuent pas la validation du runtime sur les schémas de message source.
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 sont associés aux destinations de flux de données.
Dans le portail d’expérience des opérations, vous pouvez configurer des schémas de sortie pour les points de terminaison de destination suivants qui prennent en charge la sortie Parquet :
- stockage local
- Fabric OneLake
- Stockage Azure (ADLS Gen2)
- Explorateur de données Azure
Remarque : le format de schéma Delta est utilisé pour les sorties Parquet et Delta.
Si vous utilisez Bicep ou Kubernetes, vous pouvez configurer des schémas de sortie utilisant la sortie JSON pour les points de terminaison de destination MQTT et Kafka. Les destinations basées sur MQTT et Kafka ne prennent pas en charge le format 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
Conseil
Si vous ne connaissez pas votre nom de registre, utilisez la commande schema registry list pour le trouver. Par exemple :
az iot ops schema registry list -g myresourcegroup --query "[].{Name:name}" -o tsv
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