Share via

Ingestování dat z Azure Cosmos DB do Azure Data Explorer

  • Článek

Azure Data Explorer podporuje příjem dat ze služby Azure Cosmos DB for NoSql pomocí kanálu změn. Datové připojení kanálu změn Cosmos DB je kanál příjmu dat, který naslouchá vašemu kanálu změn Cosmos DB a ingestuje data do tabulky Data Explorer. Kanál změn naslouchá novým a aktualizovaným dokumentům, ale protokoluje odstranění. Obecné informace o příjmu dat v Azure Data Explorer najdete v tématu Přehled příjmu dat v Azure Data Explorer.

Každé datové připojení naslouchá určitému kontejneru Cosmos DB a ingestuje data do zadané tabulky (v jedné tabulce může ingestovat více než jedno připojení). Metoda příjmu dat podporuje příjem dat streamování (pokud je povolený) a příjem dat ve frontě.

V tomto článku se dozvíte, jak nastavit datové připojení kanálu změn Cosmos DB pro ingestování dat do Azure Data Explorer se systémem spravovanou identitou. Než začnete, projděte si důležité informace .

K nastavení konektoru použijte následující postup:

Krok 1: Výběr tabulky Azure Data Explorer a konfigurace jejího mapování

Krok 2: Vytvoření datového připojení služby Cosmos DB

Krok 3: Testování datového připojení

Požadavky

Krok 1: Výběr tabulky Azure Data Explorer a konfigurace jejího mapování

Před vytvořením datového připojení vytvořte tabulku, do které uložíte ingestované data, a použijte mapování, které odpovídá schématu ve zdrojovém kontejneru Cosmos DB. Pokud váš scénář vyžaduje víc než jednoduché mapování polí, můžete pomocí zásad aktualizace transformovat a mapovat data ingestována z kanálu změn.

Následující příklad ukazuje ukázkové schéma položky v kontejneru Cosmos DB:

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

Pomocí následujících kroků vytvořte tabulku a použijte mapování tabulky:

  1. V webovém uživatelském rozhraní Azure Data Explorer v levé navigační nabídce vyberte Dotaz a pak vyberte databázi, ve které chcete tabulku vytvořit.

  2. Spuštěním následujícího příkazu vytvořte tabulku s názvem TestTable.

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

  3. Spuštěním následujícího příkazu vytvořte mapování tabulky.

    Příkaz mapuje vlastní vlastnosti z dokumentu JSON služby Cosmos DB na sloupce v tabulce TestTable následujícím způsobem:

    Vlastnost Cosmos DB Sloupec tabulky Transformace
    id Id Žádné
    Jméno Name Žádné
    _Ts _ts Žádné
    _Ts _Časové razítko Používá DateTimeFromUnixSeconds k transformaci_ts (v sekundách UNIXu) na _timestamp (datetime))

    Poznámka

    Doporučujeme použít následující sloupce časového razítka:

    • _ts: Tento sloupec použijte k odsouhlasení dat se službou Cosmos DB.
    • _timestamp: Tento sloupec použijte ke spouštění efektivních časových filtrů v dotazech Kusto. Další informace najdete v tématu Osvědčené postupy pro dotazy.
    .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"}
]
```

Transformace a mapování dat pomocí zásad aktualizací

Pokud váš scénář vyžaduje víc než jednoduché mapování polí, můžete pomocí zásad aktualizace transformovat a mapovat data ingestována z kanálu změn.

Zásady aktualizací představují způsob, jak transformovat data při jejich ingestu do tabulky. Jsou napsané v dotazovací jazyk Kusto a spouští se v kanálu příjmu dat. Je možné je použít k transformaci dat z příjmu dat kanálu změn Cosmos DB, například v následujících scénářích:

  • Vaše dokumenty obsahují pole, která by se snadněji dotazovala, pokud se transformují ve více řádcích pomocí operátoru mv-expand .
  • Chcete odfiltrovat dokumenty. Dokumenty můžete odfiltrovat například zadáním pomocí operátoru where .
  • Máte složitou logiku, kterou nelze reprezentovat v mapování tabulky.

Informace o tom, jak vytvářet a spravovat zásady aktualizací, najdete v tématu Přehled zásad aktualizace.

Krok 2: Vytvoření datového připojení služby Cosmos DB

K vytvoření datového konektoru můžete použít následující metody:

  1. V Azure Portal přejděte na stránku přehledu clusteru a vyberte kartu Začínáme.

  2. Na dlaždici Příjem dat vyberte Vytvořit datové připojení>Cosmos DB.

    Snímek obrazovky s kartou Začínáme s možností Vytvořit datové připojení služby Cosmos DB

  3. V podokně Vytvořit datové připojení služby Cosmos DB vyplňte formulář informacemi v tabulce:

    Snímek obrazovky s podoknem datového připojení zobrazující pole formuláře s hodnotami

    Pole Description
    Název databáze Zvolte databázi Azure Data Explorer, do které chcete ingestovat data.
    Název datového připojení Zadejte název datového připojení.
    Předplatné Vyberte předplatné, které obsahuje váš účet NoSQL služby Cosmos DB.
    Účet Cosmos DB Zvolte účet Cosmos DB, ze kterého chcete ingestovat data.
    Databáze SQL Zvolte databázi Cosmos DB, ze které chcete ingestovat data.
    Kontejner SQL Zvolte kontejner Cosmos DB, ze kterého chcete ingestovat data.
    Název tabulky Zadejte název tabulky Azure Data Explorer, do které chcete ingestovat data.
    Název mapování Volitelně můžete zadat název mapování , který se má použít pro datové připojení.

  4. Volitelně můžete v části Upřesnit nastavení provést toto:

    1. Zadejte počáteční datum načtení události. Toto je čas, od kterého konektor začne ingestovat data. Pokud nezadáte čas, konektor začne ingestovat data od okamžiku vytvoření datového připojení. Doporučený formát data je standard STANDARD UTC ISO 8601, který je zadaný takto: yyyy-MM-ddTHH:mm:ss.fffffffZ.

    2. Vyberte Přiřazené uživatelem a pak vyberte identitu. Ve výchozím nastavení připojení používá spravovanou identitu přiřazenou systémem . V případě potřeby můžete použít identitu přiřazenou uživatelem .

      Snímek obrazovky s podoknem datového připojení s nastavením Upřesnit

  5. Výběrem možnosti Vytvořit datové připojení přeložíte.

Krok 3: Testování datového připojení

  1. Do kontejneru Cosmos DB vložte následující dokument:

    {
    "name":"Cousteau"
}

  2. Ve webovém uživatelském rozhraní Azure Data Explorer spusťte následující dotaz:

    TestTable

    Sada výsledků by měla vypadat jako na následujícím obrázku:

    Snímek obrazovky s podoknem výsledků zobrazující ingestované dokumenty

Poznámka

Azure Data Explorer má zásadu agregace (dávkování) pro příjem dat ve frontě určenou k optimalizaci procesu příjmu dat. Výchozí zásady dávkování jsou nakonfigurované tak, aby zapečetily dávku, jakmile pro dávku platí jedna z následujících podmínek: maximální doba zpoždění 5 minut, celková velikost 1 GB nebo 1 000 objektů blob. Proto může docházet k latenci. Další informace najdete v tématu Zásady dávkování. Pokud chcete snížit latenci, nakonfigurujte tabulku tak, aby podporovala streamování. Viz zásady streamování.

Požadavky

Pro kanál změn služby Cosmos DB platí následující aspekty:

  • Kanál změn nezpřístupňuje události odstranění .

    Kanál změn Cosmos DB obsahuje jenom nové a aktualizované dokumenty. Pokud potřebujete vědět o odstraněných dokumentech, můžete nakonfigurovat informační kanál pomocí měkké značky a označit dokument Cosmos DB jako odstraněný. Je přidána vlastnost pro události aktualizace, které označují, zda byl dokument odstraněn. Pak je můžete pomocí operátoru where v dotazech vyfiltrovat.

    Pokud například namapujete odstraněnou vlastnost na sloupec tabulky s názvem IsDeleted, můžete odstraněné dokumenty filtrovat pomocí následujícího dotazu:

    TestTable
| where not(IsDeleted)

  • Kanál změn zveřejňuje jenom nejnovější aktualizaci dokumentu.

    Pokud chcete pochopit důsledky druhé úvahy, projděte si následující scénář:

    Kontejner Cosmos DB obsahuje dokumenty A a B. Změny vlastnosti s názvem foo jsou uvedeny v následující tabulce:

    ID dokumentu Vlastnost foo Událost Časové razítko dokumentu (_ts)
    A Červený Vytvoření 10
    B Blue Vytvoření 20
    A Oranžový Aktualizace 30
    A Růžové Aktualizace 40
    B Fialová Aktualizace 50
    A Carmine Aktualizace 50
    B NeonBlue Aktualizace 70

    Rozhraní API kanálu změn se datovým konektorem dotazuje v pravidelných intervalech, obvykle každých několik sekund. Každé hlasování obsahuje změny, ke kterým došlo v kontejneru mezi voláními, ale pouze nejnovější verzi změn na dokument.

    Pro ilustraci problému zvažte posloupnost volání rozhraní API s časovými razítky 15, 35, 55 a 75 , jak je znázorněno v následující tabulce:

    Časové razítko volání rozhraní API ID dokumentu Vlastnost foo Časové razítko dokumentu (_ts)
    15 A Červený 10
    35 B Blue 20
    35 A Oranžový 30
    55 B Fialová 50
    55 A Carmine 60
    75 B NeonBlue 70

    Při porovnání výsledků rozhraní API se seznamem změn provedených v dokumentu Služby Cosmos DB si všimnete, že se neshodují. Událost aktualizace dokumentu A zvýrazněná v tabulce změn v časovém razítku 40 se ve výsledcích volání rozhraní API nezobrazí.

    Abychom pochopili, proč se událost nezobrazuje, prozkoumáme změny dokumentu A mezi voláními rozhraní API v časových razítek 35 a 55. Mezi těmito dvěma voláními se dokument A změnil dvakrát následujícím způsobem:

    ID dokumentu Vlastnost foo Událost Časové razítko dokumentu (_ts)
    A Růžové Aktualizace 40
    A Carmine Aktualizace 50

    Při volání rozhraní API v časovém razítku 55 vrátí rozhraní API kanálu změn nejnovější verzi dokumentu. V tomto případě je nejnovější verzí dokumentu A aktualizace v časovém razítku 50, což je aktualizace vlastnosti foo z Růžové na Carmine.

    Kvůli tomuto scénáři můžou datovému konektoru chybět některé přechodné změny dokumentu. Některé události můžou například zmeškat, pokud je služba datového připojení několik minut mimo provoz nebo pokud je frekvence změn dokumentů vyšší než frekvence dotazování rozhraní API. Je však zaznamenán nejnovější stav každého dokumentu.

  • Odstranění a opětovné vytvoření kontejneru Cosmos DB se nepodporuje.

    Azure Data Explorer udržuje přehled o kanálu změn tak, že do informačního kanálu umístí kontrolní bod na jeho pozici. K tomu se používá token pro pokračování v každém fyzickém oddílu kontejneru. Při odstranění nebo opětovném vytvoření kontejneru jsou tyto tokeny pro pokračování neplatné a nejsou resetovány: musíte odstranit a znovu vytvořit datové připojení.

Odhad nákladů

Jaký vliv má použití datového připojení Ke službě Cosmos DB využití jednotek žádostí (RU) kontejneru Cosmos DB?

Konektor vyvolá rozhraní API kanálu změn služby Cosmos DB na každém fyzickém oddílu kontejneru, a to až jednou za sekundu. S těmito voláními jsou spojené následující náklady:

Náklady Description
Pevné náklady Pevné náklady jsou přibližně 2 RU na fyzický oddíl každou sekundu.
Proměnlivé náklady Proměnlivé náklady představují přibližně 2 % jednotek RU používaných k psaní dokumentů, i když se to může lišit v závislosti na vašem scénáři. Pokud například do kontejneru Cosmos DB zapíšete 100 dokumentů, náklady na zápis těchto dokumentů jsou 1 000 RU. Odpovídající náklady na použití konektoru ke čtení těchto dokumentů jsou přibližně 2 % nákladů na jejich zápis, přibližně 20 RU.

Související obsah