Freigeben über

Anforderungen und Format der Zielzone für die offene Spiegelung

In diesem Artikel werden die Anforderungen für die Zielzone und die Tabellen-/Spaltenvorgänge zur offenen Spiegelung in Microsoft Fabric beschrieben.

Nachdem Sie Ihre offen gespiegelte Datenbank über das Fabric-Portal oder die öffentliche API in Ihrem Fabric-Arbeitsbereich erstellt haben, erhalten Sie in OneLake auf der Startseite des gespiegelten Datenbankelements eine Zielzonen-URL. Diese Zielzone ist, wo Ihre Anwendung eine Metadatendatei erstellt und Daten im Parquet- oder durch Trennzeichen getrennten Textformat, einschließlich CSV, ablegt. Dateien können unkomprimiert oder mit Snappy, GZIP oder ZSTD komprimiert werden. Weitere Informationen finden Sie unter unterstützten Datendateien und -formaten.

Screenshot des Fabric-Portals mit der Zielzonen-URL des Speicherorts auf der Startseite des gespiegelten Datenbankelements.

Zielzone

Für jede gespiegelte Datenbank gibt es einen eindeutigen Speicherort in OneLake für Metadaten und Delta-Tabellen. Eine offene Spiegelung stellt einen Zielzonenordner für die Anwendung bereit, um dort eine Metadatendatei zu erstellen und Daten in OneLake zu übertragen. Die Spiegelung überwacht diese Dateien in der Landezone und liest den Ordner auf neue Tabellen und hinzugekommene Daten.

Wenn Sie beispielsweise Tabellen (Table A, Table B, Table C) in der Zielzone erstellen möchten, erstellen Sie Ordner wie die folgenden URLs:

  • https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableA
  • https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableB
  • https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableC

Metadatendatei in der Zielzone

Jeder Tabellenordner muss eine _metadata.json-Datei enthalten.

Diese Tabellenmetadatendatei enthält einen JSON-Eintrag, um gegenwärtig nur die eindeutigen Schlüsselspalten als keyColumns anzugeben.

Hier ein Beispiel, um die Spalten C1 und C2 als zusammengesetzten eindeutigen Schlüssel für die Tabelle zu deklarieren:

{
   "keyColumns" : ["C1", "C2"]
}

Wenn keyColumns oder _metadata.json nicht angegeben wird, sind Aktualisierungen/Löschungen nicht möglich. Diese Datei kann jederzeit hinzugefügt werden, kann aber nach dem Hinzufügen von keyColumns nicht mehr geändert werden.

Es wird erwartet, dass alle Spalten über einen Datentyp in der Datei _metadata.jsonverfügen. Die zurzeit unterstützten Datentypen folgen:

Unterstützter Datentyp BESCHREIBUNG
Doppelt Eine Zahl mit Dezimalstellen, die verwendet wird, wenn eine hohe Genauigkeit erforderlich ist (z. B. 3,14159).
Ledig Eine Zahl mit Dezimalstellen, aber weniger genau als Double (z. B. 3,14).
Int16 Eine kleine ganze Zahl, in der Regel zwischen -32.768 und 32.767.
Int64 Eine sehr große ganze Zahl, die für große Anzahlen oder IDs verwendet wird.
Int32 Eine standardmäßige ganze Zahl, die häufig zum Zählen oder Indizieren verwendet wird.
Datum/Uhrzeit Ein vollständiger Datums- und Uhrzeitwert (z. B. 2025-06-17 14:30:00).
IDate Ein Kalenderdatum ohne Uhrzeit (z. B. 2025-06-17).
ITime Eine Tageszeit ohne Datum (z. B. 14:30:00).
Schnur Textdaten wie Namen, Bezeichnungen oder Beschreibungen.
Boolescher Typ (Boolean) Ein wahrer oder falscher Wert, der häufig zum Umschalten oder Ja/Nein-Auswahl verwendet wird.
ByteArray Unformatierte Binärdaten, z. B. Dateien, Bilder oder codierte Inhalte.

Ereignisdatei in der Zielzone

Wenn Sie ein Partner sind, der eine offene Spiegelungslösung oder einen Kunden implementiert, der uns zusätzliche Details zum Typ der Quelle bereitstellen möchte, die Sie in OneLake spiegeln, haben wir eine neue _partnerEvents.json Datei hinzugefügt. Dies ist nicht erforderlich, sondern wird dringend empfohlen.

Beispiel:

{
  "partnerName": "testPartner",
  "sourceInfo": {
    "sourceType": "SQL",
    "sourceVersion": "2019",
    "additionalInformation": {
      "testKey": "testValue"
    }
  }
}

Anforderungen der _partnerEvents.json Datei:

  • Die _partnerEvents.json Datei sollte auf der Ebene der gespiegelten Datenbank in der Landezone und nicht pro Tabelle platziert werden.
  • Dies sourceType kann eine beliebige beschreibende Zeichenfolge sein, die die Quelle darstellt. Für diesen Wert gibt es keine Einschränkungen, z. B. "SQL", "Oracle", "Salesforce" usw.
  • Dies partnerName kann auf einen beliebigen Namen Ihrer Wahl festgelegt werden und kann repräsentativ für den Namen Ihrer Organisation sein. Halten Sie den Namen für alle Spiegeldatenbanken konsistent.

Datendatei und -format in der Zielzone

Offene Spiegelung unterstützt die Datenaufnahme in Parkett oder durch Trennzeichen getrennten Textformaten. Dateien können unkomprimiert oder mit Snappy, GZIP oder ZSTD komprimiert werden.

Parkettanforderungen

Anforderungen an durch Trennzeichen getrennten Text

  1. Wenn sich die Daten in einem durch Trennzeichen getrennten Textformat befinden, muss die Datei die Kopfzeile in der ersten Zeile haben.

  2. Geben Sie für durch Trennzeichen getrennten Text, zusätzliche Informationen in Ihrer _metadata.json Datei an. Die Eigenschaft FileExtension muss angegeben werden. Durch Trennzeichen getrennte Textdateien weisen die folgenden Eigenschaften und Standardwerte auf:

    Eigentum BESCHREIBUNG Hinweise
    FirstRowAsHeader True/false für die Kopfzeile der ersten Zeile. Erforderlich, um true für durch Trennzeichen abgegrenzte Textdateien zu sein.
    RowSeparator Zeichen, das zum Trennen von Zeilen verwendet wird. Der Standardwert ist \r\n. Unterstützt auch \n und \r.
    ColumnSeparator Zeichen, das zum Trennen von Spalten verwendet wird. Der Standardwert ist ,. Unterstützt auch ;, | und \t.
    QuoteCharacter Zeichen, das verwendet wird, um Werte in Anführungszeichen zu setzen, die Trennzeichen enthalten. Der Standardwert ist ". Kann auch ' oder eine leere Zeichenfolge sein.
    EscapeCharacter Wird verwendet, um Anführungszeichen innerhalb von Anführungszeichen zu maskieren. Der Standardwert ist \. Kann auch /, " sein oder leer sein.
    NullValue Zeichenfolgendarstellung von NULL-Werten. Kann sein "", , "N/A", "null"usw.
    Encoding Zeichencodierung der Datei. Der Standardwert ist UTF-8. Unterstützt eine vielzahl von Codierungen, einschließlich ascii, utf-16, windows-1252, usw.
    SchemaDefinition Definiert Spaltennamen, Typen und Nullwerte. Die Schemaentwicklung wird nicht unterstützt.
    FileFormat Format der Datendatei. Wenn nicht angegeben, wird standardmäßig CSV festgelegt. Muss "DelimitedText" für andere Formate als CSV sein.
    FileExtension Gibt Dateierweiterungen wie .tsv, .psv an. Erforderlich bei Verwendung von DelimitedText.

    Beispielsweise die _metadata.json Datei für eine .tsv Datendatei mit vier Spalten:

    {
"KeyColumns": [ "id" ],
"ConditionalUpdateColumn": "seqNum",
"SchemaDefinition": {
             "Columns": [
                         {
                         "Name": "id",
                         "DataType": "Int32"
                         },
                         {
                         "Name": "name",
                         "DataType": "String",
                         "IsNullable": true
                         },
                         {
                         "Name": "age",
                         "DataType": "Int32",
                         "IsNullable": true
                         },
                         {
                         "Name": "seqNum",
                         "DataType": "Int64",
                         "IsNullable": false
                         }
                        ]
             },
"FileFormat": "DelimitedText",
"FileExtension": "tsv",
"FileFormatTypeProperties": {
                           "FirstRowAsHeader": true,
                           "RowSeparator": "\r\n",
                           "ColumnSeparator": ",",
                           "QuoteCharacter": "'",
                           "EscapeCharacter": "\",
                           "NullValue": "N/A",
                           "Encoding": "UTF-8"
                        }
}

Formatanforderungen

Alle dateien, die in die Zielzone geschrieben wurden, weisen das folgende Format auf:

<rowMarker><DataColumns>

  • rowMarker: Der Spaltenname lautet __rowMarker__ (einschließlich zweier Unterstriche vor und nach rowMarker). __rowMarker__ Werte und Verhaltensweisen:

    __rowMarker__ (Szenario) Wenn keine Zeile mit denselben Schlüsselspalten im Ziel existiert Wenn eine Zeile mit denselben Schlüsselspalten im Ziel existiert
    0 (Einfügen) Zeile in das Ziel einfügen Zeile in das Ziel einfügen, keine Überprüfung auf doppelte Schlüssel in der Spalte.
    1 (Aktualisieren) Zeile in das Ziel einfügen, keine Überprüfung/Ausnahme, um das Vorhandensein einer Zeile mit derselben Schlüsselspalte zu überprüfen. Zeile mit derselben Schlüsselspalte aktualisieren.
    2 (Löschen) Keine Datenänderung, keine Überprüfung/Ausnahme, um das Vorhandensein einer Zeile mit derselben Schlüsselspalte zu überprüfen. Zeile mit derselben Schlüsselspalte löschen.
    4 (Upsert) Zeile in das Ziel einfügen, keine Überprüfung/Ausnahme, um das Vorhandensein einer Zeile mit derselben Schlüsselspalte zu überprüfen. Zeile mit derselben Schlüsselspalte aktualisieren.

  • Zeilenreihenfolge: Alle Protokolle in der Datei sollten in natürlicher Reihenfolge wie bei der Transaktion angewendet werden. Dies ist wichtig für dieselbe Zeile, die mehrmals aktualisiert wird. Die offene Spiegelung wendet die Änderungen unter Verwendung der Reihenfolge in den Dateien an.

  • Dateireihenfolge: Dateien sollten in stetig steigenden Zahlen hinzugefügt werden.

  • Dateiname: Der Dateiname hat 20 Ziffern, z. B. 00000000000000000001.parquet für die erste und 00000000000000000002.parquet für die zweite Datei. Dateinamen sollten aus fortlaufenden Zahlen bestehen. Dateien werden automatisch vom Spiegelungsdienst gelöscht, die letzte Datei bleibt jedoch erhalten, sodass das Herausgebersystem darauf verweisen kann, um die nächste Datei in der Sequenz hinzuzufügen.

Von Bedeutung

Die __rowMarker__ Spalte muss die letzte Spalte in der Liste sein.

Anfängliches Laden

Für das anfängliche Laden von Daten in eine geöffnete gespiegelte Datenbank ist __rowMarker__ in der ursprünglichen Datendatei optional und wird nicht empfohlen. Durch die Spiegelung wird die gesamte Datei als INSERT behandelt, wenn __rowMarker__ nicht vorhanden ist.

Für bessere Leistung und genaue Metriken ist __rowMarker__ nur für schrittweise Änderungen erforderlich, um Update-/Lösch-/Upsert-Vorgänge anzuwenden.

Inkrementelle Änderungen

Beim Öffnen der Spiegelung werden inkrementelle Änderungen nacheinander gelesen und auf die Delta-Zieltabelle angewendet. Die Reihenfolge ist im Änderungsprotokoll und in der Reihenfolge der Dateien implizit.

Datenänderungen werden als inkrementelle Änderungen betrachtet, sobald die spalte __rowMarker__ aus einer beliebigen Zeile/Datei gefunden wird.

Aktualisierte Zeilen müssen die vollständigen Zeilendaten mit allen Spalten enthalten.

Hier sind einige beispielhafte Parquet-Dateien des Zeilenverlaufs, um EmployeeLocation für EmployeeID E0001 von Redmond in Bellevue zu ändern. In diesem Szenario wurde die Spalte EmployeeID in der Metadatendatei in der Zielzone als Schlüsselspalte markiert.

EmployeeID,EmployeeLocation,__rowMarker__
E0001,Redmond,0
E0002,Redmond,0
E0003,Redmond,0
E0001,Bellevue,1

Wenn Schlüsselspalten aktualisiert werden, sollten sie von einem DELETE in vorangehenden Schlüsselspalten und einer INSERT-Zeile mit neuem Schlüssel und Daten übergeben werden. Beispielsweise ändert der Zeilenverlauf den eindeutigen Bezeichner __rowMarker__ für EmployeeID E0001 in E0002. Sie müssen nicht alle Spaltendaten für eine DELETE-Zeile bereitstellen, sondern nur die Schlüsselspalten.

EmployeeID,EmployeeLocation,__rowMarker__
E0001,Bellevue,0
E0001,NULL,2
E0002,Bellevue,0

Tabellenvorgänge

Die offene Spiegelung unterstützt Tabellenvorgänge wie das Hinzufügen, Löschen und Umbenennen von Tabellen.

Tabelle hinzufügen

Die offene Spiegelung nimmt beliebige Tabellen auf, die von der Anwendung zur Zielzone hinzugefügt wird. Die offene Spiegelung sucht bei jeder Iteration nach neuen Tabellen.

Löschen einer Tabelle

Die offene Spiegelung beobachtet den Ordnernamen. Wenn ein Tabellenordner gelöscht wird, löscht die Spiegelung die Tabelle in der gespiegelten Datenbank.

Wenn ein Ordner neu erstellt wird, löscht die offene Spiegelung die Tabelle und erstellt sie mit den neuen Daten im Ordner neu. Dies geschieht durch die Nachverfolgung des ETags für den Ordner.

Wenn Sie versuchen, eine Tabelle zu löschen, können Sie versuchen, den Ordner zu löschen. Es besteht jedoch die Möglichkeit, dass die offene Spiegelung weiterhin die Daten aus dem Ordner verwendet, was für den Herausgeber zu einem Löschfehler führt.

Umbenennen von Tabellen

Um eine Tabelle umzubenennen, löschen Sie den Ordner und erstellen ihn dann mit anfänglichen und inkrementellen Daten neu. Die umbenannte Tabelle muss dann erneut mit den Daten aufgefüllt werden.

Schema

Ein Tabellenpfad kann in einem Schemaordner angegeben werden. Eine Schema-Landingzone sollte einen <schemaname>.schema-Ordnernamen haben. Es können mehrere Schemas und mehrere Tabellen in einem Schema vorhanden sein.

Wenn Sie beispielsweise Schemas (Schema1, Schema2) und Tabellen (Table A, Table B, Table C) in der Zielzone erstellen möchten, erstellen Sie Ordner wie die folgenden Pfade in OneLake:

  • https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema1.schema/TableA
  • https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema1.schema/TableB
  • https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema2.schema/TableC

Tabellenspalten und Spaltenvorgänge

Typen von Spalten

  • Einfache Parquet-Typen werden in der Landezone unterstützt.
  • Komplexe Typen sollten als JSON-Zeichenfolge geschrieben werden.
  • Binäre komplexe Typen wie Geografie, Bilder usw. können als binärer Typ in der Zielzone gespeichert werden.

Spalte hinzufügen

Wenn zu den Parquet- oder CSV-Dateien neue Spalten hinzugefügt werden, fügt die offene Spiegelung die Spalten zu den Delta-Tabellen hinzu.

Spalte löschen

Wenn eine Spalte aus den neuen Protokolldateien gelöscht wird, speichert die offene Spiegelung NULL für diese Spalten in neuen Zeilen, und alte Zeilen weisen die Spalten in den Daten auf. Um die Spalte zu löschen, löschen Sie die Tabelle und erstellen Sie den Tabellenordner in der Zielzone neu. Dies führt zur Neuerstellung der Delta-Tabelle mit neuen Schemas und Daten.

Offene Spiegelungen fügen grundsätzlich alle Spalten aus früheren Versionen hinzugefügter Daten zusammen. Um eine Spalte zu entfernen, erstellen Sie die Tabelle bzw. den Ordner neu.

Spaltentyp ändern

Wenn Sie einen Spaltentyp ändern möchten, löschen Sie den Ordner, und erstellen Sie ihn mit anfänglichen und inkrementellen Daten und dem neuen Spaltentyp neu. Wenn Sie einen neuen Spaltentyp bereitstellen, ohne die Tabelle neu zu erstellen, tritt ein Fehler auf, und die Replikation für diese Tabelle wird beendet. Nachdem der Tabellenordner neu erstellt wurde, wird die Replikation mit neuen Daten und neuem Schema fortgesetzt.

Spalte umbenennen

Um eine Spalte umzubenennen, löschen Sie den Tabellenordner und erstellen ihn mit allen Daten und dem neuen Spaltennamen neu.

Bereinigungsprozess

Ein Bereinigungsprozess der offenen Spiegelung verschiebt alle verarbeiteten Dateien in einen separaten Ordner namens _ProcessedFiles oder _FilesReadyToDelete. Nach sieben Tagen werden die Dateien aus diesem Ordner entfernt.

Nächster Schritt

Tutorial: Konfigurieren von offenen gespiegelten Microsoft Fabric-Datenbanken

Zugehöriger Inhalt