Share via

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-Änderungsfeeddatenverbindung ist eine Erfassungspipeline, die auf Ihren Cosmos DB-Änderungsfeed lauscht und die Daten in Ihrer Data Explorer Tabelle erfasst. Der Änderungsfeed lauscht auf neue und aktualisierte Dokumente, protokolliert jedoch keine Löschvorgänge. Allgemeine Informationen zur Datenerfassung in Azure Data Explorer finden Sie unter Übersicht über die Datenerfassung in Azure Data Explorer.

Jede Datenverbindung lauscht auf einen bestimmten Cosmos DB-Container und erfasst Daten in einer angegebenen Tabelle (mehrere Verbindungen können in einer einzelnen Tabelle erfasst werden). Die Erfassungsmethode unterstützt die Streamingerfassung (sofern aktiviert) und die Erfassung in die Warteschlange.

In diesem Artikel erfahren Sie, wie Sie eine Cosmos DB-Änderungsfeeddatenverbindung einrichten, um Daten in Azure Data Explorer mit systemverwalteter Identität zu erfassen. Ü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 der zugehörigen 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 der zugehörigen Tabellenzuordnung

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

Im Folgenden finden 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 auf der Azure Data Explorer-Weboberfläche 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 mit dem Namen 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 spalten in der TestTable-Tabelle wie folgt zu:

    Cosmos DB-Eigenschaft Tabellenspalte Transformation
    id Id Keine
    name Name Keine
    _Ts _ts Keine
    _Ts _Timestamp Verwendet DateTimeFromUnixSeconds zum Transformieren_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 Methode 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 Updaterichtlinien verwenden, um daten, die aus Ihrem Änderungsfeed erfasst wurden, zu transformieren und zuzuordnen.

Updaterichtlinien sind eine Möglichkeit, Daten zu transformieren, wenn sie in Ihrer Tabelle erfasst werden. Sie sind in Kusto-Abfragesprache geschrieben und werden in der Erfassungspipeline 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 mit dem mv-expand Operator in mehrere Zeilen transformiert werden.
  • Sie möchten Dokumente herausfiltern. Beispielsweise können Sie Dokumente mithilfe des where Operators nach Typ herausfiltern.
  • Sie verfügen über eine komplexe Logik, die nicht in einer Tabellenzuordnung dargestellt werden kann.

Informationen zum Erstellen und Verwalten von Updaterichtlinien finden Sie unter Ü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 zur Übersichtsseite Ihres Clusters, und wählen Sie dann die Registerkarte Erste Schritte aus.

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

    Screenshot der Registerkarte

  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 der Sie Daten erfassen möchten.
    Name der Datenverbindung Geben Sie einen Namen für die Datenverbindung an.
    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 erfassen möchten.
    SQL-Datenbank Wählen Sie die Cosmos DB-Datenbank aus, aus der Sie Daten erfassen möchten.
    SQL-Container Wählen Sie den Cosmos DB-Container aus, aus dem Sie Daten erfassen möchten.
    Tabellenname Geben Sie den Namen der Azure Data Explorer-Tabelle an, für die Sie Daten erfassen möchten.
    Zuordnungsname Geben Sie optional den Zuordnungsnamen an, der für die Datenverbindung verwendet werden soll.

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

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

    2. Wählen Sie Benutzerseitig zugewiesen und dann die Identität aus. Standardmäßig wird die vom System zugewiesene verwaltete Identität von der Verbindung verwendet. Bei Bedarf können Sie eine vom Benutzer zugewiesene Identität verwenden.

      Screenshot des Datenverbindungsbereichs mit den Erweiterten Einstellungen.

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

Schritt 3: Testen der Datenverbindung

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

    {
    "name":"Cousteau"
}

  2. Führen Sie auf der Azure Data Explorer-Weboberfläche die folgende Abfrage aus:

    TestTable

    Das Resultset sollte wie auf der folgenden Abbildung aussehen:

    Screenshot des Ergebnisbereichs mit dem erfassten Dokument

Hinweis

Azure Data Explorer verfügt über eine Aggregationsrichtlinie (Batching) für die Datenerfassung in der Warteschlange, die zur Optimierung des Erfassungsprozesses entwickelt wurde. Die Standardbatchverarbeitungsrichtlinie ist so konfiguriert, dass ein Batch versiegelt wird, sobald eine der folgenden Bedingungen für den Batch zutrifft: eine maximale Verzögerungszeit von 5 Minuten, eine Gesamtgröße von einem GB oder 1.000 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 sie Streaming unterstützt. 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. Eine Eigenschaft wird 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 die deleted-Eigenschaft beispielsweise einer Tabellenspalte namens IsDeleted zuordnen, 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.

    Untersuchen Sie das folgende Szenario, um die Auswirkungen der zweiten Überlegung zu verstehen:

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

    Dokument-ID Eigenschaft foo Ereignis Dokumentzeitstempel (_ts)
    A Rot Erstellung 10
    B Blau Erstellung 20
    Ein Orange Aktualisieren 30
    A Pink Aktualisieren 40
    B Violett Aktualisieren 50
    Ein Carmine Aktualisieren 50
    B NeonBlue Aktualisieren 70

    Die Änderungsfeed-API wird vom Datenconnector in regelmäßigen Abständen 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 Sequenz von API-Aufrufen mit Den Zeitstempeln 15, 35, 55 und 75 in Betracht ziehen, wie in der folgenden Tabelle dargestellt:

    API-Aufrufzeitstempel Dokument-ID Eigenschaft foo Dokumentzeitstempel (_ts)
    15 A Rot 10
    35 B Blau 20
    35 Ein Orange 30
    55 B Violett 50
    55 Ein Carmine 60
    75 B NeonBlue 70

    Wenn Sie die API-Ergebnisse mit der Liste der Änderungen im Cosmos DB-Dokument vergleichen, werden Sie feststellen, dass sie nicht übereinstimmen. Das Updateereignis für Dokument A, das in der Änderungstabelle beim Zeitstempel 40 hervorgehoben ist, wird in den Ergebnissen des API-Aufrufs nicht angezeigt.

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

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

    Wenn der API-Aufruf zum Zeitstempel 55 erfolgt, gibt die Änderungsfeed-API die neueste Version des Dokuments zurück. In diesem Fall ist die neueste Version von Dokument A das Update zum Zeitstempel 50, d. h. das Update der Eigenschaft foo von Pink auf Carmine.

    Aufgrund dieses Szenarios können beim Datenconnector einige zwischene Dokumentänderungen fehlen. Beispielsweise werden einige Ereignisse möglicherweise übersehen, wenn der Datenverbindungsdienst für einige Minuten ausgefallen ist oder wenn die Häufigkeit von Dokumentänderungen höher als die API-Abrufhäufigkeit ist. Der aktuelle Zustand 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 Nutzung von Anforderungseinheiten (Request Units, RUs) Ihres Cosmos DB-Containers aus?

Der Connector ruft die Cosmos DB-Änderungsfeed-API auf jeder physischen Partition Ihres Containers auf bis zu einmal pro Sekunde auf. Diese Aufrufe sind mit den folgenden Kosten verbunden:

Kosten BESCHREIBUNG
Fixkosten Die Fixkosten betragen etwa 2 RUs pro physischer Partition jede Sekunde.
Variable Kosten Variable Kosten betragen etwa 2 % der RUs, die zum Schreiben von Dokumenten verwendet werden, obwohl dies je nach Szenario variieren kann. Wenn Sie beispielsweise 100 Dokumente in einen Cosmos DB-Container schreiben, betragen die Kosten für das Schreiben dieser Dokumente 1.000 RUs. Die entsprechenden Kosten für die Verwendung des Connectors zum Lesen dieses Dokuments betragen etwa 2 % der Kosten für das Schreiben, etwa 20 RUs.

Verwandte Inhalte