Grundlegendes zu Nachrichtenschemas
Die Schemaregistrierung ist ein Feature, das von der Azure Device Registry bereitgestellt wird und ist ein synchronisiertes Repository in der Cloud und am Edge. In der Schemaregistrierung werden die Definitionen von Nachrichten gespeichert, die von Edgeobjekten stammen, und anschließend wird eine API für den Zugriff auf diese Schemas am Edge verfügbar gemacht.
Der Connector für OPC UA kann Nachrichtenschemas erstellen und sie der Schemaregistrierung hinzufügen, oder Kunden können Schemas in die Webbenutzeroberfläche für Vorgänge hochladen oder ARM-/Bicep-Vorlagen verwenden.
Edgedienste verwenden Nachrichtenschemas, um Nachrichten zu filtern und zu transformieren, während sie über Ihr Industrial Edge-Szenario geleitet werden.
Schemas sind Dokumente, die das Format einer Nachricht und deren Inhalt beschreiben, um die Verarbeitung und Kontextualisierung zu ermöglichen.
Nachrichtenschemadefinitionen
Die Schemaregistrierung erwartet die folgenden erforderlichen Felder in einem Nachrichtenschema:
| Pflichtfeld | Definition |
|---|---|
$schema |
Entweder http://json-schema.org/draft-07/schema# oder Delta/1.0. In Datenflüssen werden JSON-Schemas für Quellendpunkte und Delta-Schemas für Zielendpunkte verwendet. |
type |
Object |
properties |
Die Nachrichtendefinition. |
Beispielschemas
Die folgenden Beispielschemas enthalten Beispiele zum Definieren von Nachrichtenschemas in jedem 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": {} }
]
}
}
Generieren eines Schemas
Um das Schema aus einer Beispieldatendatei zu generieren, verwenden Sie das Schema Gen-Hilfsprogramm.
Ein Tutorial, das den Schemagenerator verwendet, finden Sie unter Tutorial: Senden von Daten von einem OPC UA-Server an Azure Data Lake Storage Gen 2.
Verwenden von Nachrichtenschemas für Datenflüsse
Nachrichtenschemas werden in allen drei Phasen eines Datenflusses verwendet: Definieren der Quelleingabe, Anwenden von Datentransformationen und Erstellen der Zielausgabe.
Eingabeschema
Jede Datenquelle kann optional ein Nachrichtenschema angeben. Derzeit führt Dataflows keine Runtime-Prüfung für Quellnachrichtenschemas durch.
Ressourcenquellen verfügen über ein vordefiniertes Nachrichtenschema, das vom Connector für OPC UA erstellt wurde.
Schemas können für MQTT-Quellen hochgeladen werden. Derzeit unterstützt Azure IoT Einsatz JSON für Quellschemas, auch als Eingabeschemas bezeichnet. In der Einsatzumgebung können Sie ein vorhandenes Schema auswählen oder ein Schema hochladen, während Sie eine MQTT-Quelle definieren:
Transformation
Die Einsatz-Benutzeroberfläche verwendet das Eingabeschema als Ausgangspunkt für Ihre Daten und erleichtert die Auswahl von Transformationen basierend auf dem bekannten Eingabemeldungsformat.
Ausgabeschema
Ausgabeschemas sind Datenflusszielen zugeordnet.
Im Betriebserfahrungsportal können Sie Ausgabeschemas für die folgenden Zielendpunkte konfigurieren, welche die Parquet-Ausgabe unterstützen:
- Lokaler Speicher
- Fabric OneLake
- Azure Storage (ADLS Gen2)
- Azure-Daten-Explorer
Hinweis: Das Delta-Schemaformat wird sowohl für die Parquet- als auch für die Delta-Ausgabe verwendet.
Wenn Sie Bicep oder Kubernetes verwenden, können Sie Ausgabeschemas mithilfe der JSON-Ausgabe für MQTT- und Kafka-Zielendpunkte konfigurieren. MQTT- und Kafka-basierte Ziele unterstützen das Delta-Format nicht.
Bei diesen Datenflüssen wendet die Betriebsoberfläche alle Transformationen auf das Eingabeschema an und erstellt dann ein neues Schema im Delta-Format. Wenn die benutzerdefinierte Datenflussressource (Dataflow Custom Resource, CR) erstellt wird, enthält sie einen schemaRef-Wert, der auf das generierte Schema verweist, das in der Schemaregistrierung gespeichert ist.
Informationen zum Hochladen eines Ausgabeschemas finden Sie unter Hochladen eines Schemas.
Schema hochladen
Das Eingabeschema kann im Portal der Einsatz-Benutzeroberfläche hochgeladen werden, wie im Abschnitt Eingabeschemas dieses Artikels beschrieben. Sie können ein Schema auch mithilfe der Azure CLI oder einer Bicep-Vorlage hochladen.
Hochladen des Schemas mit der CLI
Die Befehlsgruppe az iot ops schema enthält Befehle zum Erstellen, Anzeigen und Verwalten von Schemas in Ihrer Schemaregistrierung.
Sie können ein Schema hochladen, indem Sie auf eine JSON-Datei verweisen oder das Schema als Inlineinhalt einschließen.
Im folgenden Beispiel werden minimale Eingaben verwendet, um ein Schema namens myschema aus einer Datei zu erstellen. Wenn keine Versionsnummer angegeben wird, ist die Schemaversion 1.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format json --type message --version-content myschema.json
Im folgenden Beispiel wird ein Schema namens myschema aus Inlineinhalten erstellt, und eine Versionsnummer wird zugewiesen.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format delta --type message --version-content '{\"hello\": \"world\"}' --ver 14
Tipp
Wenn Sie Ihren Registrierungsnamen nicht kennen, verwenden Sie den schema registry list-Befehl, um ihn abzufragen. Zum Beispiel:
az iot ops schema registry list -g myresourcegroup --query "[].{Name:name}" -o tsv
Nachdem der Befehl create abgeschlossen ist, sollte ein BLOB im Container Ihres Speicherkontos mit dem Schemainhalt angezeigt werden. Der Name für das Blob hat das Format schema-namespace/schema/version.
Weitere Optionen erhalten Sie mit dem Hilfsbefehl az iot ops schema -h.
Hochladen eines Schemas mit einer Bicep-Vorlage
Erstellen Sie eine Bicep-Datei (.bicep), und fügen Sie ihr den Schemainhalt am Anfang als Variable hinzu. Dieses Beispiel ist ein Deltaschema, das den OPC UA-Daten aus der Schnellstartanleitung entspricht.
// 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": {}
}
]
}
}
'''
Definieren Sie dann in derselben Datei direkt unter dem Schema die Schemaressource zusammen mit Zeigern auf die vorhandene Schemaregistrierungsressource aus der Bereitstellung von „Azure IoT Einsatz“.
// 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
}
}
Nachdem Sie den Schemainhalt und die Ressourcen definiert haben, können Sie die Bicep-Vorlage bereitstellen, um das Schema in der Schemaregistrierung zu erstellen.
az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep