Gegevens uit Azure Cosmos DB opnemen in Azure Data Explorer

  • Artikel

Azure Data Explorer biedt ondersteuning voor gegevensopname vanuit Azure Cosmos DB for NoSql met behulp van een wijzigingenfeed. De gegevensverbinding van 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 legt geen verwijderingen vast. 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 (meerdere verbindingen kunnen in één tabel worden opgenomen). De opnamemethode ondersteunt streamingopname (indien ingeschakeld) en opname in de wachtrij.

In dit artikel leert u hoe u een cosmos DB-gegevensverbinding voor wijzigingenfeeds instelt om gegevens op te nemen in Azure Data Explorer met door het systeem beheerde identiteit. 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 bijbehorende tabeltoewijzing configureren

Stap 2: Een Cosmos DB-gegevensverbinding maken

Stap 3: De gegevensverbinding testen

Vereisten

Stap 1: Een Azure Data Explorer-tabel kiezen en de bijbehorende 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 updatebeleidsregels gebruiken om gegevens die zijn opgenomen uit uw wijzigingenfeed , te transformeren en toe te wijzen .

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 tabeltoewijzing toe te passen:

  1. Selecteer in de webinterface van Azure Data Explorer in het linkernavigatiemenu Query en selecteer vervolgens de database waarin u de tabel wilt maken.

  2. Voer de volgende opdracht uit om een tabel met de naam TestTable te 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 Id Geen
    name Name Geen
    _Ts _ts Geen
    _Ts _Tijdstempel Wordt gebruikt DateTimeFromUnixSeconds om te transformeren_ts (UNIX-seconden) naar _timestamp (datetime))

    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's voor 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 toewijzen met updatebeleid

Als uw scenario meer dan een eenvoudige toewijzing van velden vereist, kunt u updatebeleidsregels gebruiken om gegevens die zijn opgenomen uit uw wijzigingenfeed, te transformeren en toe te wijzen.

Updatebeleid is een manier om gegevens te transformeren wanneer deze in uw tabel worden opgenomen. Ze zijn geschreven in Kusto-querytaal en worden uitgevoerd op de opnamepijplijn. Ze kunnen worden gebruikt voor het transformeren van gegevens uit de opname van 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 mv-expand operator.
  • U wilt documenten eruit filteren. U kunt bijvoorbeeld documenten filteren op type met behulp van de where operator.
  • U hebt complexe logica die niet kan worden weergegeven in een tabeltoewijzing.

Zie Updatebeleidsoverzicht voor 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 de Azure Portal naar de overzichtspagina van uw cluster en selecteer vervolgens het tabblad Aan de slag.

  2. Selecteer op de tegel Gegevensopnamede optie Gegevensverbinding maken>Cosmos DB.

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

  3. Vul in het deelvenster Gegevensverbinding maken van Cosmos DB het formulier in met de gegevens in de tabel:

    Schermopname van het deelvenster gegevensverbinding, met de formuliervelden met waarden.

    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 van 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 waarin u gegevens wilt opnemen.
    Toewijzingsnaam Geef desgewenst de toewijzingsnaam op die moet worden gebruikt voor de gegevensverbinding.

  4. Ga desgewenst als volgt te werk in de sectie Geavanceerde instellingen :

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

    2. Selecteer Door de gebruiker toegewezen en selecteer vervolgens de identiteit. Standaard wordt de door het systeem toegewezen beheerde identiteit gebruikt door 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 samen te kopiëren.

Stap 3: De gegevensverbinding testen

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

    {
    "name":"Cousteau"
}

  2. Voer in de webinterface 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 dat 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 voor de batch wordt voldaan: een maximale vertragingstijd van 5 minuten, de totale grootte van één GB of 1000 blobs. Daarom kan er een latentie optreden. Zie batchbeleid voor meer informatie. Als u de latentie wilt verminderen, configureert u de tabel om streaming te ondersteunen. Zie Streamingbeleid.

Overwegingen

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

  • De wijzigingenfeed maakt geen verwijderingsevenementen beschikbaar.

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

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

    TestTable
| where not(IsDeleted)

  • In de wijzigingenfeed wordt alleen de meest recente update van een document weergegeven.

    Bekijk het volgende scenario om de gevolgen van de tweede overweging te begrijpen:

    Een Cosmos DB-container bevat de 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)
    A Rood Maken 10
    B Blue Maken 20
    A Oranje Bijwerken 30
    A Roze Bijwerken 40
    B Violet Bijwerken 50
    A Carmine Bijwerken 50
    B NeonBlue Bijwerken 70

    De wijzigingenfeed-API wordt regelmatig, meestal om de paar seconden, door de gegevensconnector gepeild. Elke poll bevat wijzigingen die zijn opgetreden in de container tussen aanroepen, maar alleen de meest recente versie van de wijziging per document.

    Ter illustratie van het probleem kunt u een reeks API-aanroepen met tijdstempels 15, 35, 55 en 75 overwegen, zoals wordt weergegeven in de volgende tabel:

    Tijdstempel van API-aanroep Document-id Eigenschap foo Tijdstempel van document (_ts)
    15 A Rood 10
    35 B Blue 20
    35 A Oranje 30
    55 B Violet 50
    55 A Carmine 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 ze niet overeenkomen. De update-gebeurtenis voor document A, gemarkeerd in de wijzigingstabel met tijdstempel 40, wordt niet weergegeven in de resultaten van de API-aanroep.

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

    Document-id Eigenschap foo Gebeurtenis Tijdstempel van document (_ts)
    A Roze Bijwerken 40
    A Carmine Bijwerken 50

    Wanneer de API-aanroep met tijdstempel 55 wordt uitgevoerd, retourneert de wijzigingenfeed-API de nieuwste versie van het document. In dit geval is de nieuwste versie van document A de update met tijdstempel 50. Dit is de update voor eigenschap foo van Roze naar Karmijn.

    Vanwege dit scenario mist de gegevensconnector mogelijk enkele tussenliggende documentwijzigingen. Sommige gebeurtenissen kunnen bijvoorbeeld worden gemist als de gegevensverbindingsservice een paar minuten niet beschikbaar is of als de frequentie van documentwijzigingen hoger is dan de API-pollingfrequentie. 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 de 'positie' in de feed te controleren. Dit wordt gedaan met behulp van het voortzettingstoken op elke fysieke partitie van de container. Wanneer een container wordt verwijderd/opnieuw wordt gemaakt, zijn deze voortzettingstokens ongeldig en worden ze niet opnieuw ingesteld: u moet de gegevensverbinding verwijderen en opnieuw maken.

Kosten schatten

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

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

Kosten Description
Vaste kosten Vaste kosten zijn ongeveer 2 RU's per fysieke partitie per seconde.
Variabele kosten Variabele kosten zijn ongeveer 2% van de RU's die worden gebruikt voor het schrijven van documenten, hoewel dit afhankelijk van uw scenario kan variëren. 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 dit document te lezen, bedragen ongeveer 2% van de kosten om ze te schrijven, ongeveer 20 RU's.

Gerelateerde inhoud