Descripción de los esquemas de mensaje
El registro de esquema, una característica proporcionada por Registro de dispositivos de Azure, es un repositorio sincronizado en la nube y en el borde. El registro de esquema almacena las definiciones de mensajes procedentes de recursos perimetrales y, a continuación, expone una API para acceder a esos esquemas en el perímetro.
El conector para OPC UA puede crear esquemas de mensaje y agregarlos al registro de esquema, o bien los clientes pueden cargar esquemas en la interfaz web de la experiencia de operaciones o mediante plantillas de ARM o Bicep.
Los servicios perimetrales usan esquemas de mensaje para filtrar y transformar mensajes a medida que se enrutan a través del escenario perimetral industrial.
Los esquemas son documentos que describen el formato de un mensaje y su contenido para habilitar el procesamiento y la contextualización.
Definiciones de esquema de mensaje
El registro de esquema espera los siguientes campos obligatorios en un esquema de mensaje:
| Campo obligatorio | Definición |
|---|---|
$schema |
http://json-schema.org/draft-07/schema# o Delta/1.0. En los flujos de datos, los esquemas JSON se usan para los puntos de conexión de origen y los esquemas Delta se usan para los puntos de conexión de destino. |
type |
Object |
properties |
Definición del mensaje. |
Esquemas de ejemplo
Los siguientes esquemas de ejemplo proporcionan ejemplos para definir esquemas de mensaje en cada formato.
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": {} }
]
}
}
Generación de un esquema
Para generar el esquema a partir de un archivo de datos de ejemplo, use el asistente de generación de esquemas.
Para ver un tutorial que usa el generador de esquemas, consulte Tutorial: Envío de datos desde un servidor de OPC UA a Azure Data Lake Storage Gen 2.
Cómo usan los flujos de datos los esquemas de mensaje
Los esquemas de mensaje se usan en las tres fases de un flujo de datos: definición de la entrada de origen, aplicación de transformaciones de datos y creación de la salida de destino.
Esquema de entrada
Cada origen de flujo de datos puede especificar opcionalmente un esquema de mensaje. Actualmente, los flujos de datos no realizan la validación en tiempo de ejecución en esquemas de mensajes de origen.
Los orígenes de recursos tienen un esquema de mensaje predefinido creado por el conector para OPC UA.
Los esquemas se pueden cargar para orígenes MQTT. Actualmente, Operaciones de IoT de Azure admite JSON para esquemas de origen, también conocidos como esquemas de entrada. En la experiencia de operaciones, puede seleccionar un esquema existente o cargar uno al definir un origen MQTT:
Transformación
La experiencia de operaciones usa el esquema de entrada como punto de partida para los datos, lo que facilita la selección de transformaciones en función del formato de mensaje de entrada conocido.
Esquema de salida
Los esquemas de salida están asociados a destinos de flujo de datos.
En el portal de experiencia de operaciones, puede configurar esquemas de salida para los siguientes puntos de conexión de destino que admiten la salida de Parquet:
- almacenamiento local
- Fabric OneLake
- Azure Storage (ADLS Gen2)
- Explorador de datos de Azure
Nota: El formato de esquema Delta se usa para la salida Parquet y Delta.
Si usa Bicep o Kubernetes, puede configurar esquemas de salida mediante la salida JSON para los puntos de conexión de destino MQTT y Kafka. Los destinos basados en MQTT y Kafka no admiten el formato Delta.
Para estos flujos de datos, la experiencia de operaciones aplica las transformaciones al esquema de entrada y, a continuación, crea un nuevo esquema en formato Delta. Cuando se crea el recurso personalizado de flujo de datos, incluye un valor de schemaRef que apunta al esquema generado almacenado en el registro de esquema.
Para cargar un esquema de salida, consulte Cargar esquema.
Cargar esquema
El esquema de entrada se puede cargar en el portal de experiencia de operaciones, tal como se describe en la sección Esquema de entrada de este artículo. También puede cargar un esquema mediante la CLI de Azure o una plantilla de Bicep.
Carga del esquema con la CLI
El grupo de comandosaz iot ops schema contiene comandos para crear, ver y administrar esquemas en el registro de esquemas.
Puede cargar un esquema haciendo referencia a un archivo JSON o incluyendo el esquema como contenido insertado.
En el ejemplo siguiente se usan entradas mínimas para crear un esquema denominado myschema a partir de un archivo. Cuando no se especifica ningún número de versión, la versión del esquema es 1.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format json --type message --version-content myschema.json
En el siguiente ejemplo se crea un esquema llamado myschema a partir del contenido insertado y se asigna un número de versión.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format delta --type message --version-content '{\"hello\": \"world\"}' --ver 14
Sugerencia
Si no conoce el nombre del registro, use el comando schema registry list para consultarlo. Por ejemplo:
az iot ops schema registry list -g myresourcegroup --query "[].{Name:name}" -o tsv
Una vez completado el create comando, debería ver un blob en el contenedor de la cuenta de almacenamiento con el contenido del esquema. El nombre del blob tiene el formato schema-namespace/schema/version.
Puede consultar más opciones con el comando auxiliaraz iot ops schema -h.
Carga del esquema con una plantilla de Bicep
Cree un archivo .bicep de Bicep y agregue el contenido del esquema a él en la parte superior como una variable. Este ejemplo es un esquema Delta que corresponde a los datos de OPC UA de inicio rápido.
// 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": {}
}
]
}
}
'''
A continuación, en el mismo archivo, justo debajo del esquema, defina el recurso de esquema junto con punteros al recurso del registro de esquema existente que tiene para implementar Operaciones de IoT de Azure.
// 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
}
}
Después de definir el contenido y los recursos del esquema, puede implementar la plantilla de Bicep para crear el esquema en el registro de esquemas.
az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep