Berichtschema's begrijpen
Schemaregister, een functie van Azure Device Registry, is een gesynchroniseerde opslagplaats in de cloud en aan de rand. In het schemaregister worden de definities opgeslagen van berichten die afkomstig zijn van edge-assets en wordt vervolgens een API beschikbaar gemaakt voor toegang tot deze schema's aan de rand.
De connector voor OPC UA kan berichtschema's maken en deze toevoegen aan het schemaregister of klanten kunnen schema's uploaden naar de webgebruikersinterface van operations experience of met ARM/Bicep-sjablonen.
Edge-services gebruiken berichtschema's om berichten te filteren en te transformeren wanneer ze worden gerouteerd in uw scenario voor industriële rand.
Schema's zijn documenten die de indeling van een bericht en de inhoud ervan beschrijven om verwerking en contextualisatie mogelijk te maken.
Berichtschemadefinities
In het schemaregister worden de volgende vereiste velden in een berichtschema verwacht:
| Vereist veld | Definitie |
|---|---|
$schema |
http://json-schema.org/draft-07/schema# of Delta/1.0. In gegevensstromen worden JSON-schema's gebruikt voor broneindpunten en Delta-schema's worden gebruikt voor doeleindpunten. |
type |
Object |
properties |
De berichtdefinitie. |
Voorbeeldschema's
De volgende voorbeeldschema's bevatten voorbeelden voor het definiëren van berichtschema's in elke indeling.
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": {} }
]
}
}
Een schema genereren
Als u het schema wilt genereren op basis van een voorbeeldgegevensbestand, gebruikt u de Helper voor Schema Gen.
Zie Zelfstudie: Gegevens verzenden van een OPC UA-server naar Azure Data Lake Storage Gen 2 voor een zelfstudie die gebruikmaakt van de schemagenerator.
Hoe gegevensstromen berichtschema's gebruiken
Berichtschema's worden gebruikt in alle drie de fasen van een gegevensstroom: het definiëren van de broninvoer, het toepassen van gegevenstransformaties en het maken van de doeluitvoer.
Invoerschema
Elke gegevensstroombron kan eventueel een berichtschema opgeven. Gegevensstromen voeren momenteel geen runtimevalidatie uit voor bronberichtschema's.
Assetbronnen hebben een vooraf gedefinieerd berichtschema dat is gemaakt door de connector voor OPC UA.
Schema's kunnen worden geüpload voor MQTT-bronnen. Momenteel ondersteunt Azure IoT Operations JSON voor bronschema's, ook wel invoerschema's genoemd. In de bewerkingservaring kunt u een bestaand schema selecteren of er een uploaden tijdens het definiëren van een MQTT-bron:
Transformatie
De bewerkingservaring maakt gebruik van het invoerschema als uitgangspunt voor uw gegevens, zodat u eenvoudiger transformaties kunt selecteren op basis van de bekende indeling voor invoerberichten.
Uitvoerschema
Uitvoerschema's zijn gekoppeld aan gegevensstroombestemmingen.
In de operations experience-portal kunt u uitvoerschema's configureren voor de volgende doeleindpunten die ondersteuning bieden voor Parquet-uitvoer:
- lokale opslag
- Fabric OneLake
- Azure Storage (ADLS Gen2)
- Azure Data Explorer
Opmerking: de Delta-schema-indeling wordt gebruikt voor zowel Parquet- als Delta-uitvoer.
Als u Bicep of Kubernetes gebruikt, kunt u uitvoerschema's configureren met behulp van JSON-uitvoer voor MQTT- en Kafka-doeleindpunten. Op MQTT- en Kafka gebaseerde bestemmingen bieden geen ondersteuning voor Delta-indeling.
Voor deze gegevensstromen past de bewerkingservaring transformaties toe op het invoerschema en maakt vervolgens een nieuw schema in Delta-indeling. Wanneer de aangepaste resource voor de gegevensstroom (CR) wordt gemaakt, bevat deze een schemaRef waarde die verwijst naar het gegenereerde schema dat is opgeslagen in het schemaregister.
Zie Schema uploaden als u een uitvoerschema wilt uploaden.
Schema uploaden
Invoerschema kan worden geüpload in de bewerkingservaringsportal, zoals beschreven in de sectie Invoerschema van dit artikel. U kunt ook een schema uploaden met behulp van de Azure CLI of een Bicep-sjabloon.
Schema uploaden met de CLI
De opdrachtgroep az iot ops schema bevat opdrachten voor het maken, weergeven en beheren van schema's in uw schemaregister.
U kunt een schema uploaden door te verwijzen naar een JSON-bestand of door het schema op te slaan als inline-inhoud.
In het volgende voorbeeld worden minimale invoer gebruikt om een schema te maken dat wordt aangeroepen myschema op basis van een bestand. Wanneer er geen versienummer is opgegeven, is de schemaversie 1.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format json --type message --version-content myschema.json
In het volgende voorbeeld wordt een schema gemaakt dat wordt aangeroepen myschema op basis van inline-inhoud en wordt een versienummer toegewezen.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format delta --type message --version-content '{\"hello\": \"world\"}' --ver 14
Tip
Als u de registernaam niet weet, gebruikt u de schema registry list opdracht om er een query op uit te voeren. Voorbeeld:
az iot ops schema registry list -g myresourcegroup --query "[].{Name:name}" -o tsv
Zodra de create opdracht is voltooid, ziet u een blob in uw opslagaccountcontainer met de schema-inhoud. De naam voor de blob heeft de indeling schema-namespace/schema/version.
U kunt meer opties zien met de helper-opdracht az iot ops schema -h.
Schema uploaden met een Bicep-sjabloon
Maak een Bicep-bestand .bicep en voeg de schema-inhoud bovenaan toe als een variabele. Dit voorbeeld is een Delta-schema dat overeenkomt met de OPC UA-gegevens uit de quickstart.
// 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": {}
}
]
}
}
'''
Vervolgens definieert u in hetzelfde bestand, net onder het schema, de schemaresource, samen met de aanwijzers naar de bestaande schemaregisterresource die u hebt van het implementeren van Azure IoT-bewerkingen.
// 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
}
}
Nadat u de schema-inhoud en -resources hebt gedefinieerd, kunt u de Bicep-sjabloon implementeren om het schema in het schemaregister te maken.
az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep