Förstå meddelandescheman

Artikel
11/20/2024

Schemaregistret, en funktion som tillhandahålls av Azure Device Registry, är en synkroniserad lagringsplats i molnet och vid gränsen. Schemaregistret lagrar definitionerna av meddelanden som kommer från gränstillgångar och exponerar sedan ett API för åtkomst till dessa scheman vid gränsen.

Anslutningsappen för OPC UA kan skapa meddelandescheman och lägga till dem i schemaregistret, eller så kan kunder ladda upp scheman till webbgränssnittet för driftupplevelsen eller använda ARM/Bicep-mallar.

Edge-tjänster använder meddelandescheman för att filtrera och transformera meddelanden när de dirigeras över ditt industriella gränsscenario.

Scheman är dokument som beskriver formatet på ett meddelande och dess innehåll för att möjliggöra bearbetning och kontextualisering.

Definitioner av meddelandeschema

Schemaregistret förväntar sig följande obligatoriska fält i ett meddelandeschema:

Obligatoriskt fält	Definition
`$schema`	Antingen `http://json-schema.org/draft-07/schema#` eller `Delta/1.0`. I dataflöden används JSON-scheman för källslutpunkter och Delta-scheman används för målslutpunkter.
`type`	`Object`
`properties`	Meddelandedefinitionen.

Exempelscheman

Följande exempelscheman innehåller exempel på hur du definierar meddelandescheman i varje 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": {} }
    ]
  }
}

Generera ett schema

Om du vill generera schemat från en exempeldatafil använder du schemagenhjälpen.

En självstudiekurs som använder schemageneratorn finns i Självstudie: Skicka data från en OPC UA-server till Azure Data Lake Storage Gen 2.

Så här använder dataflöden meddelandescheman

Meddelandescheman används i alla tre faserna i ett dataflöde: definiera källindata, tillämpa datatransformeringar och skapa målutdata.

Indataschema

Varje dataflödeskälla kan också ange ett meddelandeschema. För närvarande utför dataflöden inte körningsverifiering i källmeddelandescheman.

Tillgångskällor har ett fördefinierat meddelandeschema som skapades av anslutningsappen för OPC UA.

Scheman kan laddas upp för MQTT-källor. För närvarande stöder Azure IoT Operations JSON för källscheman, även kallat indatascheman. I driftupplevelsen kan du välja ett befintligt schema eller ladda upp ett när du definierar en MQTT-källa:

Skärmbild som visar hur du laddar upp ett meddelandeschema i portalen för driftupplevelse.

Transformering

Driftupplevelsen använder indataschemat som en startpunkt för dina data, vilket gör det enklare att välja transformeringar baserat på det kända indatameddelandeformatet.

Utdataschema

Utdatascheman är associerade med dataflödesmål.

I portalen för driftupplevelse kan du konfigurera utdatascheman för följande målslutpunkter som stöder Parquet-utdata:

lokal lagring
Fabric OneLake
Azure Storage (ADLS Gen2)
Öppna Azure-datautforskaren

Obs! Delta-schemaformatet används för både Parquet- och Delta-utdata.

Om du använder Bicep eller Kubernetes kan du konfigurera utdatascheman med JSON-utdata för MQTT- och Kafka-målslutpunkter. MQTT- och Kafka-baserade mål stöder inte Delta-format.

För dessa dataflöden tillämpar driftupplevelsen alla transformeringar på indataschemat och skapar sedan ett nytt schema i Delta-format. När den anpassade dataflödesresursen (CR) skapas innehåller den ett schemaRef värde som pekar på det genererade schemat som lagras i schemaregistret.

Information om hur du laddar upp ett utdataschema finns i Ladda upp schema.

Ladda upp schema

Indataschema kan laddas upp i operations experience-portalen enligt beskrivningen i avsnittet Indataschema i den här artikeln. Du kan också ladda upp ett schema med hjälp av Azure CLI eller en Bicep-mall.

Ladda upp schema med CLI

Kommandogruppen az iot ops-schema innehåller kommandon för att skapa, visa och hantera scheman i schemaregistret.

Du kan ladda upp ett schema genom att referera till en JSON-fil eller genom att inkludera schemat som infogat innehåll.

I följande exempel används minimala indata för att skapa ett schema som heter myschema från en fil. När inget versionsnummer har angetts är schemaversionen 1.

az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format json --type message --version-content myschema.json

I följande exempel skapas ett schema som heter myschema från infogat innehåll och tilldelar ett versionsnummer.

az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format delta --type message --version-content '{\"hello\": \"world\"}' --ver 14

Dricks

Om du inte känner till ditt registernamn använder du schema registry list kommandot för att fråga efter det. Till exempel:

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

create När kommandot har slutförts bör du se en blob i lagringskontocontainern med schemainnehållet. Namnet på bloben är i formatet schema-namespace/schema/version.

Du kan se fler alternativ med hjälpkommandot az iot ops schema -h.

Ladda upp schema med en Bicep-mall

Skapa en Bicep-fil .bicep och lägg till schemainnehållet längst upp som en variabel. Det här exemplet är ett Delta-schema som motsvarar OPC UA-data från snabbstarten.

// 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": {}
      }
    ]
  }
}
'''

I samma fil, precis under schemat, definierar du sedan schemaresursen tillsammans med pekare till den befintliga schemaregisterresursen som du har från distributionen av Azure IoT Operations.

// 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
  }
}

När du har definierat schemainnehållet och resurserna kan du distribuera Bicep-mallen för att skapa schemat i schemaregistret.

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

Nästa steg

Skapa ett dataflöde

Dela via