Dela via

Använda ett Jupyter Notebook- och kqlmagic-tillägg för att analysera data i Azure Data Explorer

  • Artikel

Jupyter Notebook är ett webbprogram med öppen källkod som gör att du kan skapa och dela dokument som innehåller livekod, ekvationer, visualiseringar och berättande text. Det är användbart för en mängd olika uppgifter, till exempel datarensning och transformering, numerisk simulering, statistisk modellering, datavisualisering och maskininlärning.

Kqlmagic utökar funktionerna i Python-kerneln i Jupyter Notebook så att du kan köra Kusto-frågespråk-frågor (KQL) internt. Du kan kombinera Python och KQL för att fråga och visualisera data med hjälp av det omfattande Plot.ly-biblioteket som är integrerat med renderingsoperatorn . Kqlmagic-tillägget är kompatibelt med Jupyter Lab, Visual Studio Code Jupyter-tillägget och Azure Data Studio, och datakällor som stöds inkluderar Azure Data Explorer, Azure Monitor-loggar och Application Insights.

I den här artikeln får du lära dig hur du använder kqlmagic i en Jupyter Notebook för att ansluta till och fråga efter data som lagras i Azure Data Explorer.

Förutsättningar

  • Ett Microsoft-konto eller en Microsoft Entra användaridentitet. En Azure-prenumeration krävs inte.
  • Jupyter Notebook installerat på den lokala datorn. Annars använder du Azure Data Studio.
  • Python 3.6. Om du vill ändra Jupyter Notebook kernelversion till Python 3.6 väljer du Kernel>Change Kernel>Python 3.6.

Installera kqlmagic

När du har installerat och läst in kqlmagic-tillägget kan du skriva KQL-frågor i anteckningsboken. Om kerneln stoppas eller resultatet inte är som förväntat läser du in kqlmagic-tillägget igen.

  1. Installera kqlmagic genom att köra följande kommando:

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

  2. Kör följande kommando för att läsa in kqlmagic-tillägget:

    %reload_ext Kqlmagic

Anslut till ett kluster

Välj fliken för önskad metod för att ansluta till klustret.

Den Microsoft Entra kodmetoden uppmanar interaktiv MSAL-inloggning. Du får en kod att ange för autentisering.

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

Tips

  • Om du vill parametrisera anslutningssträng använder du värden som inte anges när de tolkas som Python-uttryck.
  • Mer information om hur du hämtar autentiseringsuppgifter finns i Anslutningsalternativ.

Exempel på klusteranslutning

Följande kommando använder Microsoft Entra kodmetod för att autentisera till databasen Samples som finns i help klustret. För användare som inte Microsoft Entra ersätter du klientorganisationens namn Microsoft.com med din Microsoft Entra klientorganisation.

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

Anslutningsalternativ

För att förenkla processen med att hämta autentiseringsuppgifter kan du lägga till någon av följande alternativflaggor efter anslutningssträng.

Alternativ Beskrivning Exempelsyntax
try_azcli_login Försök att hämta autentiseringsuppgifter från Azure CLI. -try_azcli_login
try_azcli_login_subscription Försök att hämta autentiseringsuppgifter från Azure CLI baserat på den angivna prenumerationen. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Försök att hämta autentiseringsuppgifter från inloggningen för Visual Studio Code Azure-kontot. -try_vscode_login
try_msi Försök att hämta autentiseringsuppgifter från den lokala MSI-slutpunkten. Förväntar sig en ordlista med valfria MSI-parametrar: resource,/client_idobject_idmis_res_id/ , cloud_environment, . timeout -try_msi={"client_id":<id>}
try_token Autentisera med en angiven token. Förväntar sig en ordlista med Azure AD v1- eller v2-tokenegenskaper. -try_token={"tokenType":"bearer","accessToken":"<token>"}

Exempel på anslutningsalternativ

Alla alternativ som beskrivs i föregående tabell kan läggas till efter en anslutningssträng. I följande exempel används inloggningsalternativet Azure CLI:

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

Visa anslutningsinformation

Om du vill se alla befintliga anslutningar kör du följande kommando:

%kql --conn

Om du vill kontrollera information om en specifik anslutning kör du följande kommando:

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

Fråga och visualisera

Fråga efter data med renderningsoperatorn och visualisera data med hjälp av ploy.ly-biblioteket. Den här frågan och visualiseringen tillhandahåller en integrerad upplevelse som använder inbyggd KQL. Kqlmagic stöder de flesta diagram utom timepivot, pivotchartoch ladderchart. Återgivning stöds med alla attribut utom kind, ysplitoch accumulate.

Fråga och återge cirkeldiagram

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

Tidsschema för fråga och återgivning

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

Anteckning

Dessa diagram är interaktiva. Välj ett tidsintervall för att zooma in på en viss tid.

Anpassa diagramfärgerna

Om du inte gillar standardfärgpaletten anpassar du diagrammen med hjälp av palettalternativ. Tillgängliga paletter finns här: Välj färgpalett för ditt kqlmagiska frågediagramresultat

  1. För en lista över paletter:

    %kql --palettes -popup_window

  2. cool Välj färgpaletten och rendera frågan igen:

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

Parametrisera en fråga med Python

Kqlmagic möjliggör enkelt utbyte mellan Kusto-frågespråk och Python. Läs mer: Parametrisera din kqlmagic-fråga med Python

Använda en Python-variabel i din KQL-fråga

Du kan använda värdet för en Python-variabel i frågan för att filtrera data:

statefilter = ["TEXAS", "KANSAS"]

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

Konvertera frågeresultat till Pandas DataFrame

Du kan komma åt resultatet av en KQL-fråga i Pandas DataFrame. Få åtkomst till de senast utförda frågeresultaten efter variabel _kql_raw_result_ och konvertera enkelt resultatet till Pandas DataFrame på följande sätt:

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

Exempel

I många analysscenarier kanske du vill skapa återanvändbara notebook-filer som innehåller många frågor och mata in resultaten från en fråga i efterföljande frågor. I exemplet nedan används Python-variabeln statefilter för att filtrera data.

  1. Kör en fråga för att visa de 10 översta tillstånden med maximalt DamageProperty:

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

  2. Kör en fråga för att extrahera det översta tillståndet och ange det till en Python-variabel:

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

  3. Kör en fråga med instruktionen let och Python-variabeln:

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

  4. Kör hjälpkommandot:

    %kql --help "help"

Tips

Om du vill ta emot information om alla tillgängliga konfigurationer använder du %config Kqlmagic. Om du vill felsöka och samla in Kusto-fel, till exempel anslutningsproblem och felaktiga frågor, använder du %config Kqlmagic.short_errors=False

Exempel på notebook-filer

Relaterat innehåll