Lire en anglais

Partager via

Comprendre les schémas de message

  • Article

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 :

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 :

JSON 
{
  "$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 messages sources.

Les sources de ressources ont un schéma de message prédéfini qui a été créé par le Connecteur OPC UA.

Il est possible de charger des schémas pour les sources de répartiteur de messages. 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 de répartiteur de messages :

Capture d’écran montrant le chargement d’un schéma de message dans le portail d’expérience des opérations.

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.

Azure CLI 
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.

Azure CLI 
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 :

Azure CLI 
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.

Bicep 
// 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.

Bicep 
// 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.

Azure CLI 
az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Étapes suivantes