Auf Englisch lesen

Freigeben über

Grundlegendes zu Nachrichtenschemas

  • Artikel

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:

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:

JSON 
{
  "$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 Datenflussquelle kann optional ein Nachrichtenschema angeben. Derzeit führt Datenflüsse keine Runtime-Überprü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 Nachrichtenbrokerquellen 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 Nachrichtenbrokerquelle definieren:

Screenshot, der das Hochladen eines Nachrichtenschemas im Einsatz-Benutzeroberfläche-Portal zeigt.

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 Einsatz-Benutzeroberflä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.

Azure CLI 
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.

Azure CLI 
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:

Azure CLI 
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.

Bicep 
// 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“.

Bicep 
// 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.

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

Nächste Schritte