Příjem dat ze služby Azure Cosmos DB do Azure Data Exploreru

  • Č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 služby Cosmos DB je kanál příjmu dat, který naslouchá kanálu změn Cosmos DB a ingestuje data do tabulky Průzkumníka dat. Kanál změn naslouchá novým a aktualizovaným dokumentům, ale neodstraní se. Obecné informace o příjmu dat v Azure Data Exploreru najdete v přehledu příjmu dat v Azure Data Exploreru.

Každé datové připojení naslouchá určitému kontejneru Cosmos DB a ingestuje data do zadané tabulky (více než jedno připojení může ingestovat v jedné tabulce). 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 k ingestování dat do Azure Data Exploreru pomocí systémové spravované identity. Než začnete, projděte si důležité informace.

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

Krok 1: Volba tabulky Azure Data Exploreru a konfigurace mapování tabulek

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

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

Požadavky

Krok 1: Volba tabulky Azure Data Exploreru a konfigurace mapování tabulek

Než vytvoříte datové připojení, vytvořte tabulku, do které uložíte ingestované data a použijete mapování, které odpovídá schématu ve zdrojovém kontejneru Cosmos DB. Pokud váš scénář vyžaduje více než jednoduché mapování polí, můžete pomocí zásad aktualizací 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. Ve webovém uživatelském rozhraní Azure Data Exploreru 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 Nic
    Jméno Název Nic
    _Ts _ts Nic
    _Ts _časová značka Používá DateTimeFromUnixSeconds se k transformaci _ts (v sekundách UNIX) na _timestamp (datetime)).

    Poznámka:

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

    • _ts: Pomocí tohoto sloupce můžete sloučit data se službou Cosmos DB.
    • _timestamp: Pomocí tohoto sloupce můžete spouštět efektivní časové filtry 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íce než jednoduché mapování polí, můžete pomocí zásad aktualizací transformovat a mapovat data ingestována z kanálu změn.

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

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

Informace o vytváření a správě zásad aktualizací najdete v tématu Přehled zásad aktualizace.

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

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

  1. Na webu Azure Portal přejděte na stránku přehledu clusteru a pak 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 zobrazující možnost Vytvořit datové připojení 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 Popis
    Název databáze Zvolte databázi Azure Data Exploreru, 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 služby Cosmos DB Zvolte účet služby 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 Exploreru, 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 následující akce:

    1. Zadejte počáteční datum načtení události. To je čas, kdy 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 normou ISO 8601 UTC, která je určena takto: yyyy-MM-ddTHH:mm:ss.fffffffZ.

    2. Vyberte Uživatelem přiřazenou a pak vyberte identitu. Ve výchozím nastavení se pro připojení používá spravovaná identita přiřazená 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í se zobrazeným nastavením Upřesnit

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

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 Exploreru 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ím přijatý dokument

Poznámka:

Azure Data Explorer má zásadu agregace (dávkování) pro příjem dat ve frontě navrženou tak, aby optimalizovala proces příjmu dat. Výchozí zásada dávkování je nakonfigurovaná tak, aby zapečetila dávku jednou z následujících podmínek: maximální doba zpoždění 5 minut, celková velikost jedné GB nebo 1000 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í.

Důležité informace

Následující aspekty platí pro kanál změn cosmos DB:

  • 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ý. Přidá se vlastnost pro aktualizaci událostí, které označují, zda byl dokument odstraněn. Pomocí operátoru where v dotazech je pak můžete vyfiltrovat.

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

    TestTable
| where not(IsDeleted)

  • Informační kanál změn zveřejňuje pouze nejnovější aktualizaci dokumentu.

    Abyste pochopili 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
    T Modrý Vytvoření 20
    A Orange Aktualizovat 30
    A Růžový Aktualizace 40
    T Fialka Aktualizovat 50
    A Karmín Aktualizovat 50
    T NeonBlue Aktualizovat 70

    Rozhraní API kanálu změn se dotazuje datovým konektorem 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.

    Pokud chcete tento problém ilustrovat, 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 T Modrý 20
    35 A Orange 30
    55 T Fialka 50
    55 A Karmín 60
    75 T NeonBlue 70

    Porovnání výsledků rozhraní API se seznamem změn provedených v dokumentu 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 nezobrazí ve výsledcích volání rozhraní API.

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

    ID dokumentu Vlastnost foo Událost Časové razítko dokumentu (_ts)
    A Růžová Aktualizovat 40
    A Karmín Aktualizovat 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 Pink do Carmine.

    Kvůli tomuto scénáři může datový konektor vynechat některé přechodné změny dokumentu. Některé události se například můžou zmeškat, pokud je služba datového připojení po dobu několika minut nižší nebo pokud je frekvence změn dokumentu vyšší než frekvence dotazování rozhraní API. Zachytí se ale 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á využití datového připojení Cosmos DB na využití jednotek žádostí (RU) kontejneru Cosmos DB?

Konektor vyvolá rozhraní API kanálu změn služby Cosmos DB v každém fyzickém oddílu kontejneru až jednou za sekundu. K těmto voláním jsou přidruženy následující náklady:

Náklady Popis
Pevné náklady Pevné náklady jsou přibližně 2 RU na fyzický oddíl každou sekundu.
Variabilní náklady Proměnlivé náklady jsou přibližně 2 % 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 napíš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í tohoto dokumentu jsou přibližně 2 % nákladů na jejich zápis, přibližně 20 RU.

Související obsah