Compreender esquemas de mensagens
O Registro de Esquema, um recurso fornecido pelo Registro de Dispositivo do Azure, é um repositório sincronizado na nuvem e na borda. O registro de esquema armazena as definições de mensagens provenientes de ativos de borda e, em seguida, expõe uma API para acessar esses esquemas na borda.
O conector para OPC UA pode criar esquemas de mensagem e adicioná-los ao registro de esquema ou os clientes podem carregar esquemas para a interface do usuário da Web da experiência de operações ou usando modelos ARM/Bicep.
Os serviços de borda usam esquemas de mensagens para filtrar e transformar mensagens à medida que são roteadas em seu cenário de borda industrial.
Esquemas são documentos que descrevem o formato de uma mensagem e seu conteúdo para permitir o processamento e a contextualização.
Definições de esquema de mensagem
O registro de esquema espera os seguintes campos obrigatórios em um esquema de mensagem:
| Campo obrigatório | Definição |
|---|---|
$schema |
http://json-schema.org/draft-07/schema# ou Delta/1.0. Em fluxos de dados, os esquemas JSON são usados para pontos de extremidade de origem e os esquemas Delta são usados para pontos de extremidade de destino. |
type |
Object |
properties |
A definição da mensagem. |
Esquemas de exemplo
Os esquemas de exemplo a seguir fornecem exemplos para definir esquemas de mensagem em 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": {} }
]
}
}
Gerar um esquema
Para gerar o esquema a partir de um arquivo de dados de exemplo, use o Schema Gen Helper.
Para obter um tutorial que usa o gerador de esquema, consulte Tutorial: Enviar dados de um servidor OPC UA para o Azure Data Lake Storage Gen 2.
Como os fluxos de dados usam esquemas de mensagem
Os esquemas de mensagem são usados em todas as três fases de um fluxo de dados: definição da entrada de origem, aplicação de transformações de dados e criação da saída de destino.
Esquema de entrada
Cada fonte de fluxo de dados pode, opcionalmente, especificar um esquema de mensagem. Atualmente, os fluxos de dados não executam a validação de tempo de execução em esquemas de mensagens de origem.
As fontes de ativos têm um esquema de mensagem predefinido que foi criado pelo conector para OPC UA.
Os esquemas podem ser carregados para fontes MQTT. Atualmente, o Azure IoT Operations dá suporte a JSON para esquemas de origem, também conhecidos como esquemas de entrada. Na experiência de operações, você pode selecionar um esquema existente ou carregar um enquanto define uma fonte MQTT:
Transformação
A experiência de operações usa o esquema de entrada como ponto de partida para seus dados, facilitando a seleção de transformações com base no formato de mensagem de entrada conhecido.
Esquema de saída
Os esquemas de saída estão associados a destinos de fluxo de dados.
No portal de experiência de operações, você pode configurar esquemas de saída para os seguintes pontos de extremidade de destino que suportam a saída do Parquet:
- armazenamento local
- Tecido OneLake
- Armazenamento do Azure (ADLS Gen2)
- Azure Data Explorer
Nota: O formato de esquema Delta é usado para saída Parquet e Delta.
Se você usar Bicep ou Kubernetes, poderá configurar esquemas de saída usando a saída JSON para pontos de extremidade de destino MQTT e Kafka. Destinos baseados em MQTT e Kafka não suportam o formato Delta.
Para esses fluxos de dados, a experiência de operações aplica quaisquer transformações ao esquema de entrada e, em seguida, cria um novo esquema no formato Delta. Quando o recurso personalizado de fluxo de dados (CR) é criado, ele inclui um schemaRef valor que aponta para o esquema gerado armazenado no registro do esquema.
Para carregar um esquema de saída, consulte Carregar esquema.
Carregar esquema
O esquema de entrada pode ser carregado no portal de experiência de operações, conforme descrito na seção Esquema de entrada deste artigo. Você também pode carregar um esquema usando a CLI do Azure ou um modelo Bicep.
Carregar esquema com a CLI
O grupo de comandos az iot ops schema contém comandos para criar, visualizar e gerenciar esquemas em seu registro de esquema.
Você pode carregar um esquema fazendo referência a um arquivo JSON ou incluindo o esquema como conteúdo embutido.
O exemplo a seguir usa entradas mínimas para criar um esquema chamado myschema a partir de um arquivo. Quando nenhum número de versão é especificado, a versão do esquema é 1.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format json --type message --version-content myschema.json
O exemplo a seguir cria um esquema chamado myschema a partir de conteúdo embutido e atribui um número de versão.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format delta --type message --version-content '{\"hello\": \"world\"}' --ver 14
Gorjeta
Se você não souber seu nome do Registro, use o schema registry list comando para consultá-lo. Por exemplo:
az iot ops schema registry list -g myresourcegroup --query "[].{Name:name}" -o tsv
Quando o create comando for concluído, você verá um blob no contêiner da conta de armazenamento com o conteúdo do esquema. O nome do blob está no formato schema-namespace/schema/version.
Você pode ver mais opções com o comando az iot ops schema -hhelper .
Carregar esquema com um modelo Bicep
Crie um arquivo Bicep .bicep e adicione o conteúdo do esquema a ele na parte superior como uma variável. Este exemplo é um esquema Delta que corresponde aos dados OPC UA do início 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": {}
}
]
}
}
'''
Em seguida, no mesmo arquivo, logo abaixo do esquema, defina o recurso de esquema junto com ponteiros para o recurso de registro de esquema existente que você tem da implantação das Operações IoT do 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
}
}
Depois de definir o conteúdo e os recursos do esquema, você pode implantar o modelo Bicep para criar o esquema no registro do esquema.
az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep