Principy schémat zpráv

Článek
11/20/2024

Registr schématu, funkce poskytovaná službou Azure Device Registry, je synchronizované úložiště v cloudu a na hraničních zařízeních. Registr schématu ukládá definice zpráv pocházejících z hraničních prostředků a pak zveřejňuje rozhraní API pro přístup k těmto schématům na hraničních zařízeních.

Konektor pro OPC UA může vytvářet schémata zpráv a přidávat je do registru schémat nebo zákazníci můžou nahrávat schémata do webového uživatelského rozhraní provozního prostředí nebo pomocí šablon ARM/Bicep.

Služby Edge používají schémata zpráv k filtrování a transformaci zpráv při jejich směrování napříč scénářem průmyslových hraničních zařízení.

Schémata jsou dokumenty, které popisují formát zprávy a jeho obsah, aby bylo možné zpracování a kontextování.

Definice schématu zpráv

Registr schématu očekává následující povinná pole ve schématu zpráv:

Povinné pole	Definice
`$schema`	Buďto `http://json-schema.org/draft-07/schema#` nebo `Delta/1.0`. V tocích dat se schémata JSON používají pro zdrojové koncové body a schémata Delta se používají pro cílové koncové body.
`type`	`Object`
`properties`	Definice zprávy.

Ukázková schémata

Následující ukázková schémata poskytují příklady pro definování schémat zpráv v jednotlivých formátech.

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

Generování schématu

K vygenerování schématu z ukázkového datového souboru použijte pomocníka Schema Gen.

Kurz, který používá generátor schématu, najdete v kurzu : Odesílání dat ze serveru OPC UA do Azure Data Lake Storage Gen2.

Jak toky dat používají schémata zpráv

Schémata zpráv se používají ve všech třech fázích toku dat: definování zdrojového vstupu, použití transformací dat a vytvoření cílového výstupu.

Vstupní schéma

Každý zdroj toku dat může volitelně zadat schéma zpráv. Toky dat v současné době neprovádějí ověřování za běhu schématu zdrojových zpráv.

Zdroje prostředků mají předdefinované schéma zpráv vytvořené konektorem pro OPC UA.

Schémata lze nahrát pro zdroje zprostředkovatele zpráv. Operace Azure IoT v současné době podporují JSON pro zdrojová schémata, označovaná také jako vstupní schémata. V provozním prostředí můžete vybrat existující schéma nebo ho nahrát při definování zdroje zprostředkovatele zpráv:

Snímek obrazovky znázorňující nahrání schématu zprávy na portálu provozního prostředí

Transformace

Provozní prostředí používá vstupní schéma jako výchozí bod pro vaše data, což usnadňuje výběr transformací na základě známého formátu vstupní zprávy.

Výstupní schéma

Výstupní schémata jsou přidružená k cílům toku dat.

Na portálu provozního prostředí můžete nakonfigurovat výstupní schémata pro následující cílové koncové body, které podporují výstup Parquet:

místní úložiště
Fabric OneLake
Azure Storage (ADLS Gen2)
Průzkumník dat Azure

Poznámka: Formát schématu Delta se používá pro výstup Parquet i Delta.

Pokud používáte Bicep nebo Kubernetes, můžete nakonfigurovat výstupní schémata pomocí výstupu JSON pro cílové koncové body MQTT a Kafka. Cíle založené na MQTT a Kafka nepodporují formát Delta.

U těchto toků dat provozní prostředí použije všechny transformace na vstupní schéma a pak vytvoří nové schéma ve formátu Delta. Při vytvoření vlastního prostředku toku dat (CR) obsahuje schemaRef hodnotu, která odkazuje na vygenerované schéma uložené v registru schématu.

Pokud chcete nahrát výstupní schéma, přečtěte si téma Nahrání schématu.

Nahrání schématu

Vstupní schéma lze nahrát na portálu provozního prostředí, jak je popsáno v části Vstupní schéma tohoto článku. Schéma můžete nahrát také pomocí Azure CLI nebo šablony Bicep.

Nahrání schématu pomocí rozhraní příkazového řádku

Skupina příkazů az iot ops schema obsahuje příkazy pro vytvoření, zobrazení a správu schémat v registru schématu.

Schéma můžete nahrát odkazováním na soubor JSON nebo zahrnutím schématu jako vloženého obsahu.

Následující příklad používá minimální vstupy k vytvoření schématu volaný myschema ze souboru. Pokud není zadáno číslo verze, verze schématu je 1.

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

Následující příklad vytvoří schéma volané myschema z vloženého obsahu a přiřadí číslo verze.

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

Tip

Pokud název registru neznáte, použijte k schema registry list dotazování příkaz. Příklad:

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

create Po dokončení příkazu by se měl v kontejneru účtu úložiště zobrazit objekt blob s obsahem schématu. Název objektu blob je ve formátu schema-namespace/schema/version.

Další možnosti můžete zobrazit pomocí pomocného příkazu az iot ops schema -h.

Nahrání schématu pomocí šablony Bicep

Vytvořte soubor Bicep .bicep a přidejte do něj obsah schématu v horní části jako proměnnou. Tento příklad je schéma Delta, které odpovídá datům OPC UA z rychlého startu.

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

Ve stejném souboru přímo pod schématem pak definujte prostředek schématu spolu s ukazateli na existující prostředek registru schématu, který máte z nasazení operací Azure IoT.

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

Po definování obsahu a prostředků schématu můžete šablonu Bicep nasadit a vytvořit schéma v registru schématu.

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

Další kroky

Vytvoření toku dat

Sdílet prostřednictvím