Použití rozšíření Jupyter Notebook a kqlmagic k analýze dat v Azure Data Explorer

  • Článek

Jupyter Notebook je opensourcová webová aplikace, která umožňuje vytvářet a sdílet dokumenty obsahující živý kód, rovnice, vizualizace a text vyprávění. Je užitečný pro širokou škálu úloh, jako je čištění a transformace dat, numerická simulace, statistické modelování, vizualizace dat a strojové učení.

Kqlmagic rozšiřuje možnosti jádra Pythonu v Jupyter Notebook, abyste mohli nativně spouštět dotazy dotazovací jazyk Kusto (KQL). Kombinací Pythonu a KQL můžete dotazovat a vizualizovat data pomocí bohaté knihovny Plot.ly integrované s operátorem vykreslování . Rozšíření kqlmagic je kompatibilní s Jupyter Lab, rozšířením Visual Studio Code Jupyter a Azure Data Studio a mezi podporované zdroje dat patří Azure Data Explorer, protokoly Azure Monitoru a Application Insights.

V tomto článku se dozvíte, jak používat kqlmagic v Jupyter Notebook k připojení k datům uloženým v Azure Data Explorer a dotazování se na data uložená v Azure Data Explorer.

Požadavky

  • Účet Microsoft nebo identita uživatele Microsoft Entra. Předplatné Azure se nevyžaduje.
  • Jupyter Notebook nainstalovaný na místním počítači. V opačném případě použijte Azure Data Studio.
  • Python 3.6. Pokud chcete změnit verzi jádra Jupyter Notebook na Python 3.6, vyberte Změnit jádro>Jádro>Python 3.6.

Instalace kqlmagic

Po instalaci a načtení rozšíření kqlmagic můžete do poznámkového bloku psát dotazy KQL. Pokud se jádro zastaví nebo výsledky nejsou podle očekávání, znovu načtěte rozšíření kqlmagic.

  1. Pokud chcete nainstalovat kqlmagic, spusťte následující příkaz:

    !pip install Kqlmagic --no-cache-dir  --upgrade

  2. Pokud chcete načíst rozšíření kqlmagic, spusťte následující příkaz:

    %reload_ext Kqlmagic

Připojení ke clusteru

Vyberte kartu pro upřednostňovanou metodu připojení ke clusteru.

Metoda kódu Microsoft Entra vyzve k interaktivnímu přihlášení MSAL. Obdržíte kód, který zadáte pro ověření.

%kql AzureDataExplorer://code;cluster='<cluster-name>';database='<database-name>'

Tip

  • Pokud chcete parametrizovat připojovací řetězec, použijte hodnoty bez citací, které jsou interpretovány jako výrazy Pythonu.
  • Pokud chcete proces získávání přihlašovacích údajů zjednodušit, přečtěte si téma Možnosti připojení.

Příklad připojení clusteru

Následující příkaz používá metodu kódu Microsoft Entra k ověření Samples databáze hostované v clusteruhelp. Pro uživatele, kteří nejsou Microsoft Entra, nahraďte název Microsoft.com tenanta vaším Microsoft Entra tenantem.

%kql AzureDataExplorer://tenant="Microsoft.com";code;cluster='help';database='Samples'

Možnosti připojení

Pro zjednodušení procesu získávání přihlašovacích údajů můžete za připojovací řetězec přidat jeden z následujících příznaků možností.

Možnost Popis Příklad syntaxe
try_azcli_login Pokuste se získat přihlašovací údaje pro ověřování z Azure CLI. -try_azcli_login
try_azcli_login_subscription Pokuste se získat ověřovací přihlašovací údaje z Azure CLI na základě zadaného předplatného. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Pokuste se získat přihlašovací údaje pro ověřování z přihlášení k účtu Azure v editoru Visual Studio Code. -try_vscode_login
try_msi Pokuste se získat přihlašovací údaje pro ověřování z místního koncového bodu MSI. Očekává slovník s volitelnými parametry MSI: resource,/client_idobject_idmis_res_id/ , cloud_environment, . timeout -try_msi={"client_id":<id>}
try_token Ověření pomocí zadaného tokenu Očekává slovník s vlastnostmi tokenu Azure AD v1 nebo v2. -try_token={"tokenType":"bearer","accessToken":"<token>"}

Příklad možnosti připojení

Za připojovací řetězec je možné přidat libovolnou z možností popsaných v předchozí tabulce. Následující příklad používá možnost přihlášení k Azure CLI:

%kql azureDataExplorer://code;cluster='help';database='Samples' -try_azcli_login

Zobrazení informací o připojení

Pokud chcete zobrazit všechna existující připojení, spusťte následující příkaz:

%kql --conn

Pokud chcete zkontrolovat podrobnosti o konkrétním připojení, spusťte následující příkaz:

%kql --conn <database-name>@<cluster-name>

Dotazování a vizualizace

Dotazování na data pomocí operátoru vykreslování a vizualizace dat pomocí knihovny ploy.ly Tento dotaz a vizualizace poskytuje integrované prostředí, které používá nativní KQL. Kqlmagic podporuje většinu grafů s výjimkou timepivot, pivotcharta ladderchart. Vykreslování je podporováno u všech atributů kromě kind, ysplita accumulate.

Dotazování a vykreslení piechartu

%%kql
StormEvents
| summarize statecount=count() by State
| sort by statecount 
| take10
| render piechart title="My Pie Chart by State"

Dotazování a vykreslení časového diagramu

%%kql
StormEvents
| summarize count() by bin(StartTime,7d)
| render timechart

Poznámka

Tyto grafy jsou interaktivní. Vyberte časový rozsah, který chcete přiblížit k určitému času.

Přizpůsobení barev grafu

Pokud se vám výchozí paleta barev nelíbí, přizpůsobte si grafy pomocí možností palety. Dostupné palety najdete tady: Zvolte paletu barev pro výsledek grafu dotazu kqlmagic.

  1. Seznam palet:

    %kql --palettes -popup_window

  2. Vyberte paletu cool barev a znovu vykreslíte dotaz:

    %%kql -palette_name "cool"
StormEvents
| summarize statecount=count() by State
| sort by statecount
| take10
| render piechart title="My Pie Chart by State"

Parametrizace dotazu pomocí Pythonu

Kqlmagic umožňuje jednoduchou výměnu mezi dotazovací jazyk Kusto a Pythonem. Další informace: Parametrizace dotazu kqlmagic pomocí Pythonu

Použití proměnné Pythonu v dotazu KQL

K filtrování dat můžete použít hodnotu proměnné Pythonu v dotazu:

statefilter = ["TEXAS", "KANSAS"]

%%kql
let _state = statefilter;
StormEvents 
| where State in (_state) 
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

Převod výsledků dotazu na datový rámec Pandas

K výsledkům dotazu KQL se dostanete v datovém rámci Pandas. Získejte přístup k naposledy spuštěným výsledkům dotazu podle proměnné _kql_raw_result_ a výsledky snadno převeďte na datový rámec Pandas následujícím způsobem:

df = _kql_raw_result_.to_dataframe()
df.head(10)

Příklad

V mnoha analytických scénářích můžete chtít vytvořit opakovaně použitelné poznámkové bloky, které obsahují mnoho dotazů, a výsledky z jednoho dotazu se budou zobrazovat do následných dotazů. V následujícím příkladu se k filtrování dat používá proměnná statefilter Pythonu.

  1. Spuštěním dotazu zobrazte prvních 10 stavů s maximálním počtem DamageProperty:

    %%kql
StormEvents
| summarize max(DamageProperty) by State
| order by max_DamageProperty desc
| take10

  2. Spuštěním dotazu extrahujte nejvyšší stav a nastavte ho do proměnné Pythonu:

    df = _kql_raw_result_.to_dataframe()
statefilter =df.loc[0].State
statefilter

  3. Spusťte dotaz pomocí let příkazu a proměnné Pythonu:

    %%kql
let _state = statefilter;
StormEvents 
| where State in (_state)
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

  4. Spusťte příkaz nápovědy:

    %kql --help "help"

Tip

Pokud chcete získat informace o všech dostupných konfiguracích, použijte %config Kqlmagic. Pokud chcete řešit a zachytit chyby Kusto, jako jsou problémy s připojením nebo nesprávné dotazy, použijte %config Kqlmagic.short_errors=False

Ukázkové poznámkové bloky

Související obsah