Dela via

Mata in data från Azure Cosmos DB till Azure Data Explorer

  • Artikel

Azure Data Explorer stöder datainmatning från Azure Cosmos DB för NoSQL med hjälp av ett ändringsflöde. Cosmos DB-ändringsflödesanslutningen är en inmatningspipeline som lyssnar på ändringsflödet i Cosmos DB och matar in data i tabellen i Data Explorer. Ändringsflödet lyssnar efter nya och uppdaterade dokument men loggar inte borttagningar. Allmän information om datainmatning i Azure Data Explorer finns i översikt över datainmatning i Azure Data Explorer.

Varje dataanslutning lyssnar på en specifik Cosmos DB-container och matar in data i en angiven tabell (mer än en anslutning kan matas in i en enda tabell). Inmatningsmetoden stöder strömmande inmatning (när den är aktiverad) och köad inmatning.

De två huvudsakliga scenarierna för att använda dataanslutningen för Cosmos DB-ändringsflöde är:

I den här artikeln får du lära dig hur du konfigurerar en dataanslutning för Cosmos DB-ändringsflöde för att mata in data i Azure Data Explorer med systemhanterad identitet. Granska överväganden innan du börjar.

Använd följande steg för att konfigurera en anslutning:

Steg 1: Välj en Azure Data Explorer-tabell och konfigurera dess tabellmappning

Steg 2: Skapa en Cosmos DB-dataanslutning

Steg 3: Testa dataanslutningen

Förutsättningar

Steg 1: Välj en Azure Data Explorer-tabell och konfigurera tabellmappningen

Innan du skapar en dataanslutning skapar du en tabell där du lagrar inmatade data och tillämpar en mappning som matchar schemat i Cosmos DB-källcontainern. Om ditt scenario kräver mer än en enkel mappning av fält kan du använda uppdateringsprinciper för att transformera och mappa data som matas in från ändringsflödet.

Följande visar ett exempelschema för ett objekt i Cosmos DB-containern:

{
    "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
}

Använd följande steg för att skapa en tabell och tillämpa en tabellmappning:

  1. I webbgränssnittet för Azure Data Explorer väljer du Frågai den vänstra navigeringsmenyn och väljer sedan den databas där du vill skapa tabellen.

  2. Kör följande kommando för att skapa en tabell med namnet TestTable.

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

  3. Kör följande kommando för att skapa tabellmappningen.

    Kommandot mappar anpassade egenskaper från ett Cosmos DB JSON-dokument till kolumner i tabellen TestTable enligt följande:

    Cosmos DB-egenskap Tabellkolumn Omvandling
    ID Id Ingen
    namn Namn Ingen
    _ts _Ts Ingen
    _ts _Tidsstämpel Använder DateTimeFromUnixSeconds för att transformera_ts (UNIX-sekunder) till _timestamp (datetime))

    Obs

    Vi rekommenderar att du använder följande tidsstämpelkolumner:

    • _ts: Använd den här kolumnen för att stämma av data med Cosmos DB.
    • _timestamp: Använd den här kolumnen för att köra effektiva tidsfilter i Kusto-frågorna. Mer information finns i Bästa praxis för frågor.
    .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"}
]
```

Transformera och mappa data med uppdateringsprinciper

Om ditt scenario kräver mer än en enkel mappning av fält kan du använda uppdateringsprinciper för att transformera och mappa data som matas in från ändringsflödet.

Uppdateringsprinciper är ett sätt att transformera data när det matas in i din tabell. De är skrivna i Kusto Query Language och körs på inmatningspipelinen. De kan användas för att transformera data från en Cosmos DB-ändringsflödesinmatning, till exempel i följande scenarier:

  • Dokumenten innehåller matriser som skulle vara enklare att fråga om de transformeras i flera rader med operatorn mv-expand.
  • Du vill filtrera bort dokument. Du kan till exempel filtrera bort dokument efter typ med hjälp av operatorn where.
  • Du har komplex logik som inte kan representeras i en tabellmappning.

Information om hur du skapar och hanterar uppdateringsprinciper finns i Översikt över uppdateringsprinciper.

Steg 2: Skapa en Cosmos DB-dataanslutning

Du kan använda följande metoder för att skapa dataanslutningen:

  1. I Azure-portalen går du till översiktssidan för klustret och väljer sedan fliken Komma igång.

  2. På panelen Datainmatning väljer du Skapa dataanslutning>Cosmos DB.

    Skärmbild av fliken Komma igång med alternativet Skapa Cosmos DB-dataanslutning.

  3. I fönstret Cosmos DB Skapa dataanslutning fyller du i formuläret med informationen i tabellen:

    Skärmbild av fönstret för dataanslutning som visar formulärfälten med värden.

    Fält Beskrivning
    Databasnamn Välj den Azure Data Explorer-databas som du vill mata in data i.
    Namn på dataanslutning Ange ett namn för dataanslutningen.
    Prenumeration Välj den prenumeration som innehåller ditt Cosmos DB NoSQL-konto.
    Cosmos DB-konto Välj det Cosmos DB-konto som du vill mata in data från.
    SQL-databas Välj den Cosmos DB-databas som du vill mata in data från.
    SQL-container Välj den Cosmos DB-container som du vill mata in data från.
    Tabellnamn Ange namnet på Azure Datautforskaren-tabellen till vilken du vill mata in data.
    Mappningsnamn Du kan också ange mappningsnamn som ska användas för dataanslutningen.

  4. Du kan också göra följande under avsnittet Avancerade inställningar:

    1. Ange startdatum för händelsehämtning. Det här är den tid då anslutningsappen börjar mata in data. Om du inte anger någon tid börjar anslutningsappen mata in data från det att du skapar dataanslutningen. Det rekommenderade datumformatet är ISO 8601 UTC-standarden, som anges på följande sätt: yyyy-MM-ddTHH:mm:ss.fffffffZ.

    2. Välj Användartilldelad och välj sedan identiteten. Som standard används den systemtilldelade hanterade identiteten av anslutningen. Om det behövs kan du använda en användartilldelad identitet.

      Skärmbild av fönstret för dataanslutning som visar förhandsinställningarna.

  5. Välj Skapa för att skapa dataanslutningen.

Steg 3: Testa dataanslutningen

  1. Infoga följande dokument i Cosmos DB-containern:

    {
    "name":"Cousteau"
}

  2. Kör följande fråga i webbgränssnittet för Azure Data Explorer:

    TestTable

    Resultatuppsättningen bör se ut som i följande bild:

    Skärmbild av resultatfönstret som visar det inmatade dokumentet.

Notera

Azure Data Explorer har en aggregeringsprincip (batchbearbetning) för datainmatning i kö som är utformad för att optimera inmatningsprocessen. Standardprincipen för batchbearbetning är konfigurerad för att försegla en batch när något av följande villkor gäller för batchen: en maximal fördröjningstid på 5 minuter, total storlek på en GB eller 1 000 blobar. Därför kan det uppstå en fördröjning. Mer information finns i batchbearbetningsprincip. Om du vill minska svarstiden konfigurerar du tabellen så att den stöder strömning. Se strömningsprincip.

Överväganden

Följande överväganden gäller för Cosmos DB-ändringsflödet:

  • Ändringsflödet exponerar inte borttagning händelser.

    Cosmos DB-ändringsflödet innehåller endast nya och uppdaterade dokument. Om du behöver veta mer om borttagna dokument kan du konfigurera flödet med en mjuk markör för att markera ett Cosmos DB-dokument som borttaget. En egenskap läggs till för att uppdatera händelser som anger om ett dokument har tagits bort. Du kan sedan använda operatorn where i dina frågor för att filtrera bort dem.

    Om du till exempel mappar den borttagna egenskapen till en tabellkolumn med namnet IsDeletedkan du filtrera bort borttagna dokument med följande fråga:

    TestTable
| where not(IsDeleted)

  • Ändringsflödet exponerar bara senaste uppdatering av ett dokument.

    För att förstå konsekvenserna av det andra övervägandet undersöker du följande scenario:

    En Cosmos DB-container innehåller dokument A och B. Ändringarna av en egenskap som heter foo visas i följande tabell:

    Dokument-ID Egenskap foo Händelse Tidsstämpel för dokument (_ts)
    A Röd Skapelse 10
    B Blå Skapelse 20
    A Apelsin Uppdatera 30
    A Rosa Uppdatera 40
    B Violett Uppdatera 50
    A Carmine Uppdatera 50
    B NeonBlue Uppdatera 70

    API:et för ändringsflöde avsöks av dataanslutningsappen med jämna mellanrum, vanligtvis med några sekunders mellanrum. Varje pollning innehåller ändringar som har inträffat i containern mellan anropen, men bara den senaste ändringen per dokument.

    För att illustrera problemet bör du överväga en sekvens med API-anrop med tidsstämplar 15, 35, 55och 75 enligt följande tabell:

    Tidsstämpel för API-anrop Dokument-ID Egenskap foo Tidsstämpel för dokument (_ts)
    15 A Röd 10
    35 B Blå 20
    35 A Apelsin 30
    55 B Violett 50
    55 A Carmine 60
    75 B NeonBlue 70

    Om du jämför API-resultaten med listan över ändringar som gjorts i Cosmos DB-dokumentet ser du att de inte matchar. Uppdateringshändelsen för att dokumentera A, markerad i ändringstabellen vid tidsstämpel 40, visas inte i resultatet av API-anropet.

    För att förstå varför händelsen inte visas undersöker vi ändringarna i dokumentet A- mellan API-anropen vid tidsstämplarna 35 och 55. Mellan dessa två anrop har dokumentet A ändrats två gånger, enligt följande:

    Dokument-ID Egenskap foo Händelse Tidsstämpel för dokument (_ts)
    A Rosa Uppdatera 40
    A Carmine Uppdatera 50

    När API-anropet vid tidsstämpel 55 görs returnerar API:et för ändringsflöde den senaste versionen av dokumentet. I det här fallet är den senaste versionen av dokumentet A uppdateringen vid tidsstämpel 50, vilket är uppdateringen av egenskapen foo från Pink till Carmine.

    På grund av det här scenariot kan dataanslutningsappen missa vissa mellanliggande dokumentändringar. Vissa händelser kan till exempel missas om dataanslutningstjänsten är nere i några minuter, eller om frekvensen för dokumentändringar är högre än API-avsökningsfrekvensen. Det senaste tillståndet för varje dokument registreras dock.

  • Det går inte att ta bort och återskapa en Cosmos DB-container

    Azure Data Explorer håller reda på ändringsflödet genom att kontrollera den "position" som den befinner sig på i flödet. Detta görs med hjälp av fortsättningstoken på varje fysisk partition i containern. När en container tas bort/återskapas är fortsättningstoken ogiltig och återställs inte. I det här fallet måste du ta bort och återskapa dataanslutningen.

Beräkna kostnad

Hur mycket påverkar användningen av Cosmos DB-dataanslutningen din Cosmos DB-containers begäringsenheters (RUs) användning?

Anslutningsappen anropar Api:et för Cosmos DB-ändringsflöde på varje fysisk partition i containern, upp till en gång i sekunden. Följande kostnader är associerade med dessa anrop:

Kostnad Beskrivning
Fasta kostnader Fasta kostnader är cirka 2 RU:er per fysisk partition varje sekund.
Varierande kostnader Rörliga kostnader är cirka 2% av de RU som används för att skriva dokument, men detta kan variera beroende på ditt scenario. Om du till exempel skriver 100 dokument till en Cosmos DB-container är kostnaden för att skriva dokumenten 1 000 RU:er. Motsvarande kostnad för att använda anslutningsappen för att läsa dokumentet är cirka 2% kostnaden för att skriva dem, cirka 20 RU:er.

Relaterat innehåll