Entenda os esquemas de mensagens

Artigo
11/21/2024

O registro de esquema, um recurso fornecido pela Versão Prévia do 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 mensagens e adicioná-los ao registro de esquema, ou os clientes podem fazer upload de esquemas pela interface de usuário da Web da experiência de operações ou usar modelos do ARM/Bicep.

Os serviços de borda usam esses esquemas de mensagens para filtrar e transformar mensagens à medida que são roteadas em seu cenário industrial de borda.

Esquemas são documentos que descrevem o formato de uma mensagem e seu conteúdo, permitindo o processamento e a contextualização.

Definições de esquemas de mensagem

O registro de esquema exige que os seguintes campos obrigatórios estejam presentes 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, esquemas JSON são usados para pontos de extremidade de origem, enquanto 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 mostram como 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 de um arquivo de dados de exemplo, use o Auxiliar de Geração de Esquema.

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 utilizam 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 de saída de destino.

Esquema de entrada

Cada origem de fluxo de dados pode, opcionalmente, definir um esquema de mensagem. Atualmente, os fluxos de dados não executam a validação de runtime em esquemas de mensagem de origem.

As origens de ativos possuem um esquema de mensagem predefinido, criado pelo conector para OPC UA.

No caso de origens MQTT, esquemas podem ser carregados manualmente. 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, é possível selecionar um esquema existente ou fazer upload de um novo ao configurar uma origem MQTT:

Captura de tela mostrando o upload de um esquema de mensagem no portal da experiência de operações.

Transformação

A experiência de operações usa o esquema de entrada como ponto de partida para os dados, facilitando a seleção de transformações com base no formato de mensagem 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 dão suporte à saída parquet:

Armazenamento local*
Fabric OneLake
Armazenamento de blobs/ADLS Gen2
Azure Data Explorer

Observação: o formato de esquema Delta é usado tanto para saída Parquet quanto para saída 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. Os destinos baseados em MQTT e Kafka não dão suporte ao formato Delta.

Nesses fluxos de dados, a experiência de operações aplica as transformações ao esquema de entrada e, em seguida, cria um novo esquema no formato Delta. Quando o CR (recurso personalizado) do fluxo de dados é criado, ele inclui um schemaRef valor que aponta para o esquema gerado armazenado no registro de esquema.

Para carregar um esquema de saída, veja 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 e um modelo Bicep.

Carregar esquema com a CLI

O grupo de comandos esquema az iot ops contém comandos para criar, exibir e gerenciar esquemas no 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 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 do 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

Dica

Se você não souber o nome do registro, use o comando schema registry list para consultá-lo. Por exemplo:

az iot ops schema registry list -g myresourcegroup --query "[].{Name:name}" -o tsv

Depois que o comando create for concluído, você deverá 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 auxiliar az iot ops schema -h.

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. Esse exemplo é um esquema Delta que corresponde aos dados OPC UA de 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 juntamente com ponteiros para o recurso de registro de esquema existente que você tem da implantação das Operações de 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 de esquema.

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

Próximas etapas

Criação de um fluxo de dados

Compartilhar via