Freigeben über

Erfassen von Daten aus Azure Cosmos DB in Azure Data Explorer

  • Artikel

Azure Data Explorer unterstützt die Datenerfassung aus Azure Cosmos DB for NoSQL mithilfe eines Änderungsfeeds. Die Cosmos DB-Änderungsfeed-Datenverbindung ist eine Erfassungspipeline, die Ihrem Cosmos DB-Änderungsfeed lauscht und die Daten in Ihrer Datenbank erfasst. Der Änderungsfeed lauscht auf neue und aktualisierte Dokumente, protokolliert jedoch keine Löschungen. Allgemeine Informationen zur Datenerfassung in Azure Data Explorer finden Sie unter Übersicht über die Datenerfassung in Azure Data Explorer.

Jede Datenverbindung überwacht einen bestimmten Cosmos DB-Container und erfasst Daten in einer angegebene Tabelle (mehrere Verbindungen können in einer einzelnen Tabelle aufgenommen werden). Die Aufnahmemethode unterstützt Streamingerfassung (wenn aktiviert) und in die Warteschlangenerfassung.

In diesem Artikel erfahren Sie, wie Sie eine Cosmos DB-Änderungsfeeddatenverbindung einrichten, um Daten in Azure Data Explorer mit systemseitig verwalteter Identität aufzunehmen. Überprüfen Sie die Überlegungen, bevor Sie beginnen.

Führen Sie die folgenden Schritte aus, um einen Connector einzurichten:

Schritt 1: Auswählen einer Azure Data Explorer-Tabelle und Konfigurieren ihrer Tabellenzuordnung

Schritt 2: Erstellen einer Cosmos DB-Datenverbindung

Schritt 3: Testen der Datenverbindung

Voraussetzungen

Schritt 1: Auswählen einer Azure Data Explorer-Tabelle und Konfigurieren ihrer Tabellenzuordnung

Erstellen Sie vor dem Erstellen einer Datenverbindung eine Tabelle, in der Sie die aufgenommenen Daten speichern, und wenden Sie eine Zuordnung an, die dem Schema im Cosmos DB-Quellcontainer entspricht. Wenn Ihr Szenario mehr als eine einfache Zuordnung von Feldern erfordert, können Sie Aktualisierungsrichtlinien verwenden, um Daten zu transformieren und zuzuordnen, die aus Ihrem Änderungsfeed aufgenommen wurden.

Im Folgenden sehen Sie ein Beispielschema eines Elements im Cosmos DB-Container:

{
    "id": "17313a67-362b-494f-b948-e2a8e95e237e",
    "name": "Cousteau",
    "_rid": "pL0MAJ0Plo0CAAAAAAAAAA==",
    "_self": "dbs/pL0MAA==/colls/pL0MAJ0Plo0=/docs/pL0MAJ0Plo0CAAAAAAAAAA==/",
    "_etag": "\"000037fc-0000-0700-0000-626a44110000\"",
    "_attachments": "attachments/",
    "_ts": 1651131409
}

Führen Sie die folgenden Schritte aus, um eine Tabelle zu erstellen und eine Tabellenzuordnung anzuwenden:

  1. Wählen Sie in der Azure Data Explorer-Web-UI im linken Navigationsmenü Abfrage aus, und wählen Sie dann die Datenbank aus, in der Sie die Tabelle erstellen möchten.

  2. Führen Sie den folgenden Befehl aus, um eine Tabelle namens TestTable zu erstellen.

    .create table TestTable(Id:string, Name:string, _ts:long, _timestamp:datetime)

  3. Führen Sie den folgenden Befehl aus, um die Tabellenzuordnung zu erstellen:

    Der Befehl ordnet benutzerdefinierte Eigenschaften aus einem Cosmos DB JSON-Dokument zu Spalten in der TestTable-Tabelle wie folgt zu:

    Cosmos DB-Eigenschaft Tabellenspalte Transformation
    id Kennung Keine
    name Name Keine
    _ts _ts Keine
    _ts _timestamp Verwendet DateTimeFromUnixSeconds zum Transformieren von _ts (UNIX-Sekunden) in _timestamp (datetime))

    Hinweis

    Es wird empfohlen, die folgenden Zeitstempelspalten zu verwenden:

    • _ts: Verwenden Sie diese Spalte, um Daten mit Cosmos DB abzugleichen.
    • _timestamp: Verwenden Sie diese Spalte, um effiziente Zeitfilter in Ihren Kusto-Abfragen auszuführen. Weitere Informationen finden Sie unter Bewährte Methoden für Abfragen.
    .create table TestTable ingestion json mapping "DocumentMapping"
```
[
    {"column":"Id","path":"$.id"},
    {"column":"Name","path":"$.name"},
    {"column":"_ts","path":"$._ts"},
    {"column":"_timestamp","path":"$._ts", "transform":"DateTimeFromUnixSeconds"}
]
```

Transformieren und Zuordnen von Daten mit Updaterichtlinien

Wenn Ihr Szenario mehr als eine einfache Zuordnung von Feldern erfordert, können Sie Aktualisierungsrichtlinien verwenden, um Daten, die aus Ihrem Änderungsfeed aufgenommen wurden, zu transformieren und zuzuordnen.

Aktualisierungsrichtlinien sind eine Möglichkeit zum Transformieren von Daten, wenn sie in Ihre Tabelle aufgenommen werden. Sie sind in der Kusto-Abfragesprache geschrieben und werden in der Aufnahmepipeline ausgeführt. Sie können verwendet werden, um Daten aus einer Cosmos DB-Änderungsfeederfassung zu transformieren, z. B. in den folgenden Szenarien:

  • Ihre Dokumente enthalten Arrays, die einfacher abzufragen wären, wenn sie mithilfe des mv-expand-Operators in mehreren Zeilen transformiert werden.
  • Sie möchten Dokumente herausfiltern. Sie können z. B. Dokumente mithilfe des where-Operators herausfiltern.
  • Sie verfügen über komplexe Logik, die nicht in einer Tabellenzuordnung dargestellt werden kann.

Informationen zum Erstellen und Verwalten von Updaterichtlinien finden Sie in der Übersicht über Updaterichtlinien.

Schritt 2: Erstellen einer Cosmos DB-Datenverbindung

Sie können die folgenden Methoden verwenden, um den Datenconnector zu erstellen:

  1. Wechseln Sie im Azure-Portal zu Ihrer Clusterübersichtsseite, und wählen Sie dann die Registerkarte Erste Schritte aus.

  2. Wählen Sie auf der Kachel Datenaufnahme die Option Datenverbindung>Cosmos DB erstellen aus.

    Screenshot der Registerkarte „Erste Schritte“ mit der Option „Cosmos DB-Datenverbindung erstellen“.

  3. Füllen Sie im Bereich „Cosmos DB Datenverbindung erstellen“ das Formular mit den Informationen in der Tabelle aus:

    Screenshot des Datenverbindungsbereichs mit den Formularfeldern mit Werten.

    Feld Beschreibung
    Datenbankname Wählen Sie die Azure Data Explorer-Datenbank aus, in die Sie Daten aufnehmen möchten.
    Name der Datenverbindung Geben Sie einen Namen für die Datenverbindung ein.
    Abonnement Wählen Sie das Abonnement aus, das Ihr Cosmos DB NoSQL-Konto enthält.
    Cosmos DB-Konto Wählen Sie das Cosmos DB-Konto aus, aus dem Sie Daten aufnehmen möchten.
    SQL-Datenbank Wählen Sie die Cosmos DB-Datenbank aus, aus der Sie Daten aufnehmen möchten.
    SQL-Container Wählen Sie den Cosmos DB-Container aus, aus dem Sie Daten aufnehmen möchten.
    Tabellenname Geben Sie den Namen der Azure Data Explorer-Tabelle an, in die Sie Daten aufnehmen möchten.
    Zuordnungsname Geben Sie optional den Zuordnungsnamen, der für die Datenverbindung verwendet werden soll, an.

  4. Führen Sie optional im Abschnitt Erweiterte Einstellungen die folgenden Schritte aus:

    1. Geben Sie Startdatum des Ereignisabrufs an. Dies ist der Zeitpunkt, zu dem der Connector mit dem Erfassen von Daten beginnt. Wenn Sie keine Uhrzeit angeben, beginnt der Connector mit dem Erfassen von Daten ab dem Zeitpunkt, zu dem Sie die Datenverbindung erstellen. Das empfohlene Datumsformat ist der UTC-Standard ISO 8601, der wie folgt angegeben wird: yyyy-MM-ddTHH:mm:ss.fffffffZ.

    2. Wählen Sie benutzerseitig zugewiesenen und dann die Identität aus. Standardmäßig wird die systemseitig zugewiesene verwaltete Identität von der Verbindung verwendet. Bei Bedarf können Sie eine benutzerseitig zugewiesene Identität verwenden.

      Screenshot des Datenverbindungsbereichs mit den Einstellungen „Erweitert“.

  5. Wählen Sie Erstellen aus, um die Datenverbindung zu erstellen.

Schritt 3: Testen der Datenverbindung

  1. Fügen Sie im Cosmos DB-Container das folgende Dokument ein:

    {
    "name":"Cousteau"
}

  2. Führen Sie in der Azure Data Explorer-Web-UI die folgende Abfrage aus:

    TestTable

    Das Resultset sollte wie auf der folgenden Abbildung aussehen:

    Screenshot des Ergebnisbereichs, der das erfasste Dokument zeigt.

Hinweis

Azure Data Explorer verfügt über eine Aggregationsrichtlinie (Batching) für die Datenerfassung in der Warteschlange, die für die Optimierung des Erfassungsprozesses konzipiert ist. Die Standardrichtlinie für die Batchverarbeitung ist so konfiguriert, dass ein Batch versiegelt wird, wenn eine der folgenden Bedingungen für den Batch zutrifft: eine maximale Verzögerungszeit von 5 Minuten, eine Gesamtgröße von 1 G oder 1000 Blobs. Daher kann es zu Wartezeit kommen. Weitere Informationen finden Sie unter Batching-Richtlinie. Um die Latenz zu verringern, konfigurieren Sie Ihre Tabelle so, dass Streaming unterstützt wird. Weitere Informationen finden Sie unter Streaming ingestion policy (Richtlinie für die Streamingerfassung).

Überlegungen

Die folgenden Überlegungen gelten für den Cosmos DB-Änderungsfeed:

  • Der Änderungsfeed macht keine Löschereignisse verfügbar.

    Der Cosmos DB-Änderungsfeed enthält nur neue und aktualisierte Dokumente. Wenn Sie über gelöschte Dokumente Bescheid wissen müssen, können Sie Ihren Feed mithilfe eines Softmarkers konfigurieren, um ein Cosmos DB-Dokument als gelöscht zu markieren. Es wird eine Eigenschaft hinzugefügt, um Ereignisse zu aktualisieren, die angeben, ob ein Dokument gelöscht wurde. Anschließend können Sie den where-Operator in Ihren Abfragen verwenden, um sie herauszufiltern.

    Wenn Sie beispielsweise die gelöschte Eigenschaft einer Tabellenspalte namens IsDeletedzuordnen, können Sie gelöschte Dokumente mit der folgenden Abfrage herausfiltern:

    TestTable
| where not(IsDeleted)

  • Der Änderungsfeed macht nur das neueste Update eines Dokuments verfügbar.

    Um die Auswirkungen der zweiten Überlegung zu verstehen, untersuchen Sie das folgende Szenario:

    Ein Cosmos DB-Container enthält die Dokumente A und B. Die Änderungen an einer Eigenschaft namens foo werden in der folgenden Tabelle angezeigt:

    Dokument-ID Eigenschaft foo Ereignis Dokumentzeitstempel (_ts)
    A Red Erstellung 10
    b Blau Erstellung 20
    A Orange Aktualisieren 30
    A Pink Aktualisieren 40
    b Violet Aktualisieren 50
    A Carmine Aktualisieren 50
    b NeonBlue Aktualisieren 70

    Die Änderungsfeed-API wird vom Datenconnector in regelmäßigen Intervallen abgefragt, in der Regel alle paar Sekunden. Jede Abfrage enthält Änderungen, die im Container zwischen Aufrufen aufgetreten sind, aber nur die neueste Version der Änderung pro Dokument.

    Um das Problem zu veranschaulichen, sollten Sie eine Abfolge von API-Aufrufen mit Zeitstempeln 15, 35, 55 und 75 in Betracht ziehen, wie in der folgenden Tabelle gezeigt:

    API-Aufrufzeitstempel Dokument-ID Eigenschaft foo Dokumentzeitstempel (_ts)
    15 A Red 10
    35 b Blau 20
    35 A Orange 30
    55 b Violet 50
    55 A Carmine 60
    75 b NeonBlue 70

    Wenn Sie die API-Ergebnisse mit der Liste der im Cosmos DB-Dokument vorgenommenen Änderungen vergleichen, werden Sie feststellen, dass sie nicht übereinstimmen. Das Aktualisierungsereignis zum Dokument A, hervorgehoben in der Änderungstabelle zum Zeitstempel „40“, wird nicht in den Ergebnissen des API-Aufrufs angezeigt.

    Um zu verstehen, warum das Ereignis nicht angezeigt wird, untersuchen wir die Änderungen an Dokument A zwischen den API-Aufrufen zu den Zeitstempeln „35“ und „55“. Zwischen diesen beiden Aufrufen wurde Dokument A zweimal geändert, wie folgt:

    Dokument-ID Eigenschaft foo Ereignis Dokumentzeitstempel (_ts)
    A Pink Aktualisieren 40
    A Carmine Aktualisieren 50

    Wenn der API-Aufruf zum Zeitpunkt des Zeitstempels „55“ erfolgt, gibt die Änderungsfeed-API die neueste Version des Dokuments zurück. In diesem Fall ist die neueste Version des Dokuments A das Update zum Zeitstempel „50“, nämlich die Aktualisierung der Eigenschaft foo von Pink auf Carmine.

    Aufgrund dieses Szenarios kann der Datenconnector einige Zwischendokumentänderungen übersehen. Beispielsweise werden einige Ereignisse möglicherweise übersehen, wenn der Datenverbindungsdienst einige Minuten aus ist oder die Häufigkeit der Dokumentänderungen höher ist als die API-Abrufhäufigkeit. Der neueste Status jedes Dokuments wird jedoch erfasst.

  • Das Löschen und erneute Erstellen eines Cosmos DB-Containers wird nicht unterstützt.

    Azure Data Explorer verfolgt den Änderungsfeed durch Prüfpunkte zur „Position”, an der er sich im Feed befindet. Dies erfolgt mithilfe des Fortsetzungstoken auf jeder physischen Partition des Containers. Wenn ein Container gelöscht/neu erstellt wird, sind diese Fortsetzungstoken ungültig und werden nicht zurückgesetzt: Sie müssen die Datenverbindung löschen und neu erstellen.

Schätzen von Kosten

Wie stark wirkt sich die Verwendung der Cosmos DB-Datenverbindung auf die Anforderungseinheiten (RUs) Ihres Cosmos DB-Containers aus?

Der Connector ruft die Cosmos DB-Änderungsfeed-API für jede physische Partition Ihres Containers bis zu einmal pro Sekunde auf. Die folgenden Kosten sind mit diesen Aufrufen verbunden:

Kosten Beschreibung
Fixkosten Fixkosten sind etwa 2 RUs pro physischer Partition pro Sekunde.
Variable Kosten Variable Kosten sind etwa 2 % der zum Schreiben von Dokumenten verwendeten RUs, obwohl dies je nach Szenario variieren kann. Wenn Sie beispielsweise 100 Dokumente in einen Cosmos DB-Container schreiben, kostet das Schreiben dieser Dokumente 1.000 RUs. Die entsprechenden Kosten für die Verwendung des Connectors zum Lesen dieser Dokumente sind etwa 2 % der Kosten für die Schreibvorgänge, etwa 20 RUs.

Zugehöriger Inhalt