Grundlegendes zu Nachrichtenschemas

Die Schemaregistrierung, ein Feature der Azure Device Registry, ist ein synchronisiertes Repository in der Cloud und am Edge. Es speichert Definitionen von Nachrichten, die von Edgeobjekten stammen, und macht eine API verfügbar, um auf diese Schemas am Edge zuzugreifen.

Datenflüsse verwenden Schemas an drei Stellen:

• Quelle: Geben Sie optional ein Schema zur Beschreibung eingehender Nachrichten an. Die Betriebsoberfläche verwendet sie zum Anzeigen verfügbarer Felder.
• Transformation: Die Betriebsoberfläche verwendet das Quellschema als Ausgangspunkt, wenn Sie Transformationen erstellen.
• Ziel: Geben Sie beim Senden von Daten an Speicherendpunkte ein Ausgabeschema und serialisierungsformat an.

Schemaformate

Die Schemaregistrierung unterstützt zwei Formate:

Beide Formate erfordern type: "object" und ein properties Feld, das die Nachrichtenstruktur definiert.

JSON-Schemabeispiel

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "temperature": { "type": "number" },
    "humidity": { "type": "number" },
    "deviceId": { "type": "string" },
    "timestamp": { "type": "string" }
  }
}

Beispiel für ein Delta-Schema

{
  "$schema": "Delta/1.0",
  "type": "object",
  "properties": {
    "type": "struct",
    "fields": [
      { "name": "asset_id", "type": "string", "nullable": true, "metadata": {} },
      { "name": "temperature", "type": "double", "nullable": true, "metadata": {} },
      { "name": "timestamp", "type": "string", "nullable": true, "metadata": {} }
    ]
  }
}

Dieses Beispiel markiert jedes Feld als nullable: true. Markieren Sie ein Feld als nullable: false nur, wenn Ihre Zuordnung immer einen Wert dafür erzeugt. Bei Parquet und Delta schlägt der gesamte Batch fehl und wird verworfen, wenn in einem Datensatz ein Feld nullable: false fehlt. Weitere Informationen finden Sie unter Speicher serialisierungsverhalten.

Generieren eines Schemas

Um ein Schema aus einer Beispieldatendatei zu generieren, verwenden Sie den Schema-Gen-Assistenten.

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.

Konfigurieren eines Quellschemas

Jede Datenflussquelle kann optional ein Nachrichtenschema angeben. Derzeit führen Datenflüsse keine Laufzeitnutzlastüberprüfung für Quellschemas durch. Die Betriebsoberfläche verwendet das Schema zum Anzeigen verfügbarer Felder beim Erstellen von Transformationen.

Zwei verwandte Verhaltensweisen lassen sich leicht übersehen:

• Ein Verweis auf ein Schema in der Nachricht kann den Datensatz steuern. Wenn eine Quellnachricht einen Schemaverweis (die MQTT-Eigenschaft dataschema ) enthält und Sie die Quelle mit Schemainformationen konfigurieren, vergleicht der Datenfluss die beiden. Wenn sie in Konflikt stehen, wird die Nachricht bestätigt und ohne Ausgabe verworfen, und die Laufzeit als conflicting schema protokolliert. Diese Überprüfung unterscheidet sich von der Payloadüberprüfung: Der Nachrichteninhalt wird nicht anhand des Schemas überprüft, aber ein nicht übereinstimmender Verweis beendet den Datensatz weiterhin.
• Konfigurierte JSON-Schemas sind keine Laufzeit-Validatoren. Für die JSON-Ausgabe wird während der Serialisierung kein konfiguriertes Schema erzwungen. Der Datenfluss serialisiert die Form des Laufzeitwerts direkt mit abgeleiteten Typen. Verwenden Sie JSON-Schemas als Entwurfszeitdokumentation, nicht als Garantie, dass die Ausgabe dem Schema entspricht.

Ressourcenquellen verfügen über ein vordefiniertes Schema, das vom Connector für OPC UA erstellt wurde. Für Nachrichtenbrokerquellen können Sie ein JSON-Schema in der Betriebsumgebung hochladen oder in Ihrer Konfiguration auf eins verweisen.

Verwenden Sie das schemaRef Feld, um in ihrer Datenquellenkonfiguration auf ein Schema zu verweisen. Weitere Informationen finden Sie unter Konfigurieren einer Datenquelle.

Konfigurieren eines Ausgabeschemas

Ausgabeschemas steuern, wie Daten serialisiert werden, bevor sie das Ziel erreicht. Speicherendpunkte (ADLS Gen2, Fabric OneLake, Azure Data Explorer, lokaler Speicher) erfordern ein Schema und unterstützen die Serialisierungsformate Parquet und Delta. MQTT- und Kafka-Ziele verwenden standardmäßig JSON.

Wenn Sie ein Speicherziel auswählen, wendet die Benutzeroberfläche in der Betriebsumgebung alle Transformationen auf das Quellschema an und generiert automatisch ein Delta-Schema. Das generierte Schema wird in der Schemaregistrierung gespeichert und vom Datenfluss referenziert.

Geben Sie für Bicep- oder Kubernetes-Bereitstellungen das Schema- und Serialisierungsformat in den Transformationseinstellungen an. Weitere Informationen finden Sie unter Konfigurieren eines Datenflussziels.

Verhalten der Speicher serialisierung

Wenn ein Datenfluss unter Verwendung der Parquet- oder Delta-Serialisierung in einen Speicherendpunkt (ADLS Gen2, Fabric OneLake, Azure Data Explorer oder lokalen Speicher) schreibt, steuert das Ausgabeschema, wie Datensätze geschrieben werden. Die folgenden Verhaltensweisen können dazu führen, dass Datensätze gelöscht oder mit unerwarteten Werten geschrieben werden. Überprüfen Sie diese, bevor Sie ein Schema oder eine Zuordnung entwerfen.

Nicht nullwerte Felder können einen ganzen Batch ablegen. Zur Schreibzeit überprüft der Encoder jedes Feld im Ausgabeschema. Wenn ein Feld nullable: false ist und ein Datensatz keinen Wert dafür hat (weil das Feld nicht zugeordnet wurde, falsch geschrieben war oder in der Quelle fehlte), schlägt der Commit fehl, und der Datenfluss verwirft den gesamten ausstehenden Batch, nicht nur den einen Datensatz. Die Laufzeit protokolliert einen Fehler ähnlich ParquetEncoding found missing property that is not Nullable: <field>, gefolgt von failed to commit record into a batch, dropping it. Der Datenfluss läuft weiter, sodass der Verlust unbemerkt bleibt, wenn Sie nicht die Protokolle prüfen. Um dieses Problem zu vermeiden, markieren Sie ein Feld nullable: false nur, wenn ihre Zuordnung immer einen Wert dafür erzeugt. Verwenden Sie andernfalls nullable: true. Ein expliziter null-Wert, der in ein nullable: false-Feld gemappt wird, schlägt auf die gleiche Weise fehl, mit dem Fehler Cannot set null value. Reason: field '<field>' is not nullable.

Ordnen Sie jedem Blattfeld, nicht einem ganzen Objekt zu. Für Parkett und Delta können Sie einen Wert nur auf einem blattfeld festlegen, das im Schema deklariert ist. Das Zuordnen einer gesamten Struktur oder eines Objekts zu einem übergeordneten Pfad schreibt nicht die geschachtelten Werte und legt den Datensatz mit einem ParquetEncoding could not set a field <path>, it does not exist by the schema ähnlichen Fehler ab. Ordnen Sie jedes Ausgabeblatt zu, das vom Schema deklariert wird.

Wildcards setzen voraus, dass das Schema jedes erweiterte Feld deklariert. Eine * -> * Zuordnung (oder ein beliebiger Wildcard, einschließlich flacher und umstrukturierter Muster), wird auf jedes Blatt in der Laufzeit-Payload erweitert. Für Parquet und Delta muss das Ausgabeschema jedes dieser Blätter deklarieren. Wenn die Nutzlast ein Blatt enthält, das vom Schema nicht deklariert wird, wird der Datensatz gelöscht. Generieren Sie das Schema aus repräsentativen Beispieldaten, sodass es jedes Feld enthält, das der Datenfluss erzeugt.

Ein Schema allein füllt keine Werte auf. Ein Schema beschreibt die Ausgabeform, aber es verschiebt keine Daten. Ohne Zuordnung schreibt der Datenfluss Datensätze, die nur NULL-Werte enthalten (für Felder, die NULL-Werte zulassen), oder verwirft sie (für Felder, die keine NULL-Werte zulassen). Zum Befüllen von Werten fügen Sie eine Zuordnung hinzu, in der Regel * -> *, und stellen Sie sicher, dass Felder nullable: true sind, wenn ein Wert fehlen könnte.

Numerische Konvertierungen erfolgen implizit und können an Genauigkeit verlieren. Wenn der Typ eines zugeordneten Werts nicht mit dem Typ der Schemaspalte übereinstimmt, konvertieren Parquet und Delta ihn ohne einen Fehler auszugeben. Float-to-Integer-Konvertierungen schneiden den Nachkommateil ab, und einschränkende Konvertierungen können zu Präzisionsverlust führen oder einen Überlauf verursachen. Wenn Sie eine Rundung benötigen, runden Sie in der Zuordnung explizit. Informationen zu den verfügbaren Funktionen finden Sie unter Skalierungs- und Rundungsfunktionen.

Fehlende und NULL sind nicht identisch. Ein Feld, das in einem Datensatz fehlt (missing), wird während der Serialisierung übersprungen, während ein Feld, das explizit auf null gesetzt ist, geschrieben wird, wenn das Format dies zulässt. Bei Parquet und Delta wird ein fehlender Wert in einem nullable: true-Feld als null geschrieben, ein fehlender Wert in einem nullable: false-Feld verwirft den Batch, und ein explizites null in einem nullable: false-Feld führt ebenfalls zu einem Fehler. Entwerfen Sie Ihre Zuordnungen und Nullierbarkeit unter Berücksichtigung dieser Abweichung.

Komplexe Typen werden je nach Format unterschiedlich konvertiert. Objekte, Karten, Bytewerte und Arrays serialisieren nicht auf die gleiche Weise in verschiedenen Formaten:

• Maps (Objekte mit Nicht-String-Schlüsseln): Parquet und Delta lehnen Maps mit der Fehlermeldung Currently maps are not supported ab. JSON unterstützt Zuordnungen nur, wenn die Schlüssel Zeichenfolgen sind. Avro konvertiert Zuordnungsschlüssel in Zeichenfolgen, und wenn zwei Schlüssel nach der Konvertierung kollidieren, gewinnt der letzte Wert.
• Bytewerte: JSON codiert Bytes als base64-Zeichenfolge. Parkett und Delta können Bytes je nach Schemaspaltentyp als binär, eine Base64-Zeichenfolge oder eine Liste schreiben.
• Arrays: Parkett und Delta schreiben Arrays je nach Spaltentyp als Liste oder binär. Eine binäre Spalte mit fester Größe schlägt fehl, wenn die Arraylänge nicht übereinstimmt.

Wenn Sie eine vorhersagbare Form für einen komplexen Wert benötigen, ordnen Sie die einzelnen Blattfelder explizit zu, anstatt die Passthrough für das gesamte Objekt zu verwenden.

Hochladen eines Schemas

Sie können Schemas über die Betriebsoberfläche, die Azure CLI oder eine Bicep-Bereitstellung hochladen.

Hochladen mit der Azure CLI

Verwenden Sie die Schemabefehlsgruppe "az iot ops ", um Schemas zu erstellen und zu verwalten.

Erstellen eines Schemas aus einer Datei:

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

Erstellen eines Schemas von Inline-Inhalten mit der bestimmten Version:

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

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

Nach Abschluss des Befehls wird ein Blob im Container Ihres Speicherkontos mit dem Schemainhalt angezeigt. Der Blobname folgt dem Format schema-namespace/schema/version.

Hochladen mit Bicep

Definieren Sie den Schemainhalt als Variable, und erstellen Sie die Schemaressource:

param schemaRegistryName string = '<SCHEMA_REGISTRY_NAME>'
param schemaName string = 'sensor-data-delta'
param schemaVersion string = '1'

var schemaContent = '''
{
  "$schema": "Delta/1.0",
  "type": "object",
  "properties": {
    "type": "struct",
    "fields": [
      { "name": "temperature", "type": "double", "nullable": true, "metadata": {} },
      { "name": "humidity", "type": "double", "nullable": true, "metadata": {} },
      { "name": "deviceId", "type": "string", "nullable": true, "metadata": {} }
    ]
  }
}
'''

resource schemaRegistry 'Microsoft.DeviceRegistry/schemaRegistries@2026-04-01' existing = {
  name: schemaRegistryName
}

resource schema 'Microsoft.DeviceRegistry/schemaRegistries/schemas@2026-04-01' = {
  parent: schemaRegistry
  name: schemaName
  properties: {
    displayName: 'Sensor Data Delta Schema'
    description: 'Delta schema for sensor telemetry'
    format: 'Delta/1.0'
    schemaType: 'MessageSchema'
  }
}

resource version 'Microsoft.DeviceRegistry/schemaRegistries/schemas/schemaVersions@2026-04-01' = {
  parent: schema
  name: schemaVersion
  properties: {
    description: 'Initial version'
    schemaContent: schemaContent
  }
}

Stellen Sie die Bicep-Datei bereit. Setze die RESOURCE_GROUP Umgebungsvariable auf den Namen deiner Ressourcengruppe und führe dann aus:

az deployment group create --resource-group $RESOURCE_GROUP --template-file schema.bicep

Verwandte Inhalte

• Schemata auf Knotenverbindungen konfigurieren
• Konfigurieren einer Datenflussquelle
• Konfigurieren eines Datenflussziels
• Erstellen eines Datenflusses