Delen via

Gegevens uit Azure Cosmos DB opnemen in Azure Data Explorer

  • Artikel

Azure Data Explorer biedt ondersteuning voor gegevensopname uit Azure Cosmos DB voor NoSql met behulp van een wijzigingsfeed. De gegevensverbinding met de Cosmos DB-wijzigingenfeed is een opnamepijplijn die luistert naar uw Cosmos DB-wijzigingenfeed en de gegevens opneemt in uw Data Explorer-tabel. De wijzigingenfeed luistert naar nieuwe en bijgewerkte documenten, maar logt geen verwijderingen. Zie overzicht van gegevensopname in Azure Data Explorer voor algemene informatie over gegevensopname in Azure Data Explorer.

Elke gegevensverbinding luistert naar een specifieke Cosmos DB-container en neemt gegevens op in een opgegeven tabel (meer dan één verbinding kan in één tabel worden opgenomen). De opnamemethode ondersteunt streaming-opname (indien ingeschakeld) en opname in de wachtrij.

De twee belangrijkste scenario's voor het gebruik van de gegevensverbinding met de Cosmos DB-wijzigingenfeed zijn:

In dit artikel leert u hoe u een cosmos DB-gegevensverbinding voor wijzigingenfeeds instelt om gegevens op te nemen in Azure Data Explorer met System Managed Identity. Bekijk de overwegingen voordat u begint.

Gebruik de volgende stappen om een connector in te stellen:

Stap 1: Een Azure Data Explorer-tabel kiezen en de tabeltoewijzing configureren

Stap 2: een Cosmos DB-gegevensverbinding maken

Stap 3: De gegevensverbinding testen

Voorwaarden

Stap 1: Een Azure Data Explorer-tabel kiezen en de tabeltoewijzing configureren

Voordat u een gegevensverbinding maakt, maakt u een tabel waarin u de opgenomen gegevens opslaat en past u een toewijzing toe die overeenkomt met het schema in de Cosmos DB-broncontainer. Als uw scenario meer dan een eenvoudige toewijzing van velden vereist, kunt u update-beleid gebruiken om gegevens te transformeren en toewijzen die uit uw wijzigingsfeed zijn opgenomen.

Hieronder ziet u een voorbeeldschema van een item in de 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
}

Gebruik de volgende stappen om een tabel te maken en een tabelmapping toe te passen:

  1. Selecteer in de webgebruikersinterface van Azure Data Explorer in het linkernavigatiemenu Queryen selecteer vervolgens de database waarin u de tabel wilt maken.

  2. Voer de volgende opdracht uit om een tabel met de naam TestTablete maken.

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

  3. Voer de volgende opdracht uit om de tabeltoewijzing te maken.

    Met de opdracht worden aangepaste eigenschappen van een Cosmos DB JSON-document als volgt toegewezen aan kolommen in de tabel TestTable:

    Cosmos DB-eigenschap Tabelkolom Transformatie
    id Identificatie Geen
    naam Naam Geen
    _ts _Ts Geen
    _ts _tijdstempel Gebruikt om_ts (UNIX-seconden) te transformeren naar _timestamp ())

    Notitie

    U wordt aangeraden de volgende tijdstempelkolommen te gebruiken:

    • _ts: gebruik deze kolom om gegevens af te stemmen met Cosmos DB.
    • _timestamp: gebruik deze kolom om efficiënte tijdfilters uit te voeren in uw Kusto-query's. Zie Best practice voor query'svoor meer informatie.
    .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"}
]
```

Gegevens transformeren en in kaart brengen met updatebeleidsregels

Als uw scenario meer dan een eenvoudige toewijzing van velden vereist, kunt u updatebeleid(en) gebruiken om gegevens die zijn opgenomen in uw wijzigingsfeed te transformeren en toe te wijzen.

Updatebeleid zijn een manier om gegevens te transformeren terwijl deze worden opgenomen in uw tabel. Ze worden geschreven in Kusto Query Language en worden uitgevoerd op de opnamepijplijn. Ze kunnen worden toegepast om gegevens te transformeren die worden binnengehaald uit een Cosmos DB-wijzigingenfeed, zoals in de volgende scenario's:

  • Uw documenten bevatten matrices die gemakkelijker kunnen worden opgevraagd als ze in meerdere rijen worden getransformeerd met behulp van de operator mv-expand.
  • U wilt de documenten filteren. U kunt bijvoorbeeld documenten filteren op type met behulp van de operator where.
  • U hebt complexe logica die niet kan worden weergegeven in een tabel.

Zie Overzicht van updatebeleidvoor meer informatie over het maken en beheren van updatebeleid.

Stap 2: Een Cosmos DB-gegevensverbinding maken

U kunt de volgende methoden gebruiken om de gegevensconnector te maken:

  1. Ga in Azure Portal naar de overzichtspagina van uw cluster en selecteer vervolgens het tabblad Aan de slag.

  2. Selecteer op de tegel Gegevensopname de optie Data verbinding maken>Cosmos DB.

    Schermopname van het tabblad Aan de slag met de optie Cosmos DB-gegevensverbinding maken.

  3. In het deelvenster Cosmos DB Data verbinding maken vult u het formulier in met de informatie in de tabel:

    Schermopname van het deelvenster gegevensverbinding, waarin de formuliervelden met waarden worden weergegeven.

    Veld Beschrijving
    databasenaam Kies de Azure Data Explorer-database waarin u gegevens wilt opnemen.
    naam van gegevensverbinding Geef een naam op voor de gegevensverbinding.
    abonnement Selecteer het abonnement dat uw Cosmos DB NoSQL-account bevat.
    Cosmos DB-account Kies het Cosmos DB-account waaruit u gegevens wilt opnemen.
    SQL-database Kies de Cosmos DB-database waaruit u gegevens wilt opnemen.
    SQL-container Kies de Cosmos DB-container waaruit u gegevens wilt opnemen.
    Tabelnaam Geef de naam van de Azure Data Explorer tabel op waarnaar u gegevens wilt opnemen.
    koppelingsnaam Gebruik desgewenst de toewijzingsnaam voor de gegevensverbinding.

  4. Ga desgewenst als volgt te werk in het gedeelte Geavanceerde instellingen:

    1. Geef de begindatum voor het ophalen van gebeurtenissen op . Dit is het tijdstip waarop de connector gegevens gaat opnemen. Als u geen tijd opgeeft, neemt de connector gegevens op vanaf het moment dat u de gegevensverbinding maakt. De aanbevolen datumnotatie is de ISO 8601 UTC-standaard, die als volgt is opgegeven: yyyy-MM-ddTHH:mm:ss.fffffffZ.

    2. Selecteer door de gebruiker toegewezen en selecteer vervolgens de identiteit. De door het systeem toegewezen beheerde identiteit wordt standaard gebruikt voor de verbinding. Indien nodig kunt u een door de gebruiker toegewezen identiteit gebruiken.

      Schermopname van het deelvenster Gegevensverbinding, met de geavanceerde instellingen.

  5. Selecteer maken om de gegevensverbinding te kratten.

Stap 3: De gegevensverbinding testen

  1. Voeg in de Cosmos DB-container het volgende document in:

    {
    "name":"Cousteau"
}

  2. Voer in de webgebruikersinterface van Azure Data Explorer de volgende query uit:

    TestTable

    De resultatenset moet eruitzien als in de volgende afbeelding:

    Schermopname van het resultatenvenster met het opgenomen document.

Notitie

Azure Data Explorer heeft een aggregatiebeleid (batchverwerking) voor gegevensopname in de wachtrij die is ontworpen om het opnameproces te optimaliseren. Het standaardbeleid voor batchverwerking is geconfigureerd om een batch te verzegelen zodra aan een van de volgende voorwaarden is voldaan voor de batch: een maximale vertragingstijd van 5 minuten, de totale grootte van één GB of 1000 blobs. Daarom kan er sprake zijn van een latentie. Zie batchverwerkingsbeleidvoor meer informatie. Als u de latentie wilt verminderen, configureert u uw tabel ter ondersteuning van streaming. Zie streamingbeleid.

Overwegingen

De volgende overwegingen zijn van toepassing op de Cosmos DB-wijzigingenfeed:

  • In de wijzigingenfeed worden verwijdering gebeurtenissen niet weergegeven.

    De Cosmos DB-wijzigingenfeed bevat alleen nieuwe en bijgewerkte documenten. Als u meer wilt weten over verwijderde documenten, kunt u uw feed configureren met een zachte markering om een Cosmos DB-document te markeren als verwijderd. Er wordt een eigenschap toegevoegd om gebeurtenissen bij te werken die aangeven of een document is verwijderd. Vervolgens kunt u de operator where in uw query's gebruiken om ze uit te filteren.

    Als u bijvoorbeeld de verwijderde eigenschap toe wijst aan een tabelkolom met de naam IsDeleted, kunt u verwijderde documenten filteren met de volgende query:

    TestTable
| where not(IsDeleted)

  • De wijzigingenfeed bevat alleen de meest recente update van een document.

    Bekijk het volgende scenario om inzicht te hebben in de gevolgen van de tweede overweging:

    Een Cosmos DB-container bevat documenten A en B. De wijzigingen in een eigenschap met de naam foo- worden weergegeven in de volgende tabel:

    Document-ID Eigenschap foo Gebeurtenis Tijdstempel van document (_ts)
    Een Rood Creatie 10
    B Blauw Creatie 20
    Een Oranje Bijwerken 30
    A Roze bijwerken 40
    B Violet Bijwerken 50
    Een Karmijn Bijwerken 50
    B NeonBlue Bijwerken 70

    De wijzigingenfeed-API wordt op regelmatige intervallen gepolled door de gegevensconnector, meestal om de paar seconden. Iedere poll bevat wijzigingen die zijn opgetreden in de container tussen oproepen, maar alleen de meest recente versie van een wijziging per document.

    Om het probleem te illustreren, overweeg een reeks API-aanroepen met tijdstempels 15, 35, 55en 75, zoals weergegeven in de volgende tabel:

    Tijdstempel van API-aanroep Document-ID Eigenschap foo Tijdstempel van document (_ts)
    15 Een Rood 10
    35 B Blauw 20
    35 Een Oranje 30
    55 B Violet 50
    55 Een Karmijn 60
    75 B NeonBlue 70

    Als u de API-resultaten vergelijkt met de lijst met wijzigingen die zijn aangebracht in het Cosmos DB-document, ziet u dat deze niet overeenkomen. De bijwerkgebeurtenis voor document A, gemarkeerd in de wijzigingstabel bij tijdstempel 40, verschijnt niet in de resultaten van de API-oproep.

    Om te begrijpen waarom de gebeurtenis niet wordt weergegeven, bekijken we de wijzigingen in het document A- tussen de API-aanroepen bij tijdstempels 35 en 55. Tussen deze twee oproepen is document A tweemaal gewijzigd, als volgt:

    Document-ID Eigenschap foo Gebeurtenis Tijdstempel van document (_ts)
    Een Roze Bijwerken 40
    Een Karmijn Bijwerken 50

    Wanneer de API-aanroep van tijdstempel 55 wordt gemaakt, retourneert de wijzigingenfeed-API de nieuwste versie van het document. In dit geval is de nieuwste versie van document A de update op tijdstip 50, wat de aanpassing van eigenschap foo van Pink naar Carminebetreft.

    Vanwege dit scenario kan de gegevensconnector enkele tussenliggende documentwijzigingen missen. Sommige gebeurtenissen kunnen bijvoorbeeld worden gemist als de gegevensverbindingsservice een paar minuten offline is of als de frequentie van documentwijzigingen hoger is dan de frequentie van de API-polling. De meest recente status van elk document wordt echter vastgelegd.

  • Het verwijderen en opnieuw maken van een Cosmos DB-container wordt niet ondersteund

    Azure Data Explorer houdt de wijzigingenfeed bij door het bijhouden van controlepunten van de positie waar het zich in de feed bevindt. Dit wordt gedaan met behulp van een continuatietoken op elke van de fysieke partities van de container. Wanneer een container wordt verwijderd/opnieuw gemaakt, is het vervolgtoken ongeldig en wordt het niet opnieuw ingesteld. In dit geval moet u de gegevensverbinding verwijderen en opnieuw maken.

Kosten schatten

Hoeveel invloed heeft het gebruik van de Cosmos DB-gegevensverbinding op het gebruik van uw Cosmos DB-container's aanvraageenheden (RU's)?

De connector roept de API voor de wijzigingenfeed van Cosmos DB aan op elke fysieke partitie van uw container, tot eenmaal per seconde. De volgende kosten zijn gekoppeld aan deze aanroepen:

Kosten Beschrijving
Vaste kosten Vaste kosten zijn ongeveer 2 RU's per fysieke partitie elke seconde.
Variabele kosten Variabele kosten zijn ongeveer 2% van de RU's die worden gebruikt voor het schrijven van documenten, maar dit kan variëren afhankelijk van uw scenario. Als u bijvoorbeeld 100 documenten naar een Cosmos DB-container schrijft, zijn de kosten voor het schrijven van deze documenten 1000 RU's. De bijbehorende kosten voor het gebruik van de connector om die documenten te lezen, zijn ongeveer 2% keer de kosten voor het schrijven ervan, namelijk ongeveer 20 RUs.

Verwante inhoud