Använda ett Jupyter Notebook- och kqlmagic-tillägg för att analysera data i Azure Data Explorer
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.
- 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.
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.
Installera kqlmagic genom att köra följande kommando:
!pip install Kqlmagic --no-cache-dir --upgrade
Kör följande kommando för att läsa in kqlmagic-tillägget:
%reload_ext Kqlmagic
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.
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'
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_id object_id mis_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>"} |
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
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 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
, pivotchart
och ladderchart
. Återgivning stöds med alla attribut utom kind
, ysplit
och accumulate
.
%%kql
StormEvents
| summarize statecount=count() by State
| sort by statecount
| take10
| render piechart title="My Pie Chart by State"
%%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.
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
För en lista över paletter:
%kql --palettes -popup_window
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"
Kqlmagic möjliggör enkelt utbyte mellan Kusto-frågespråk och Python. Läs mer: Parametrisera din kqlmagic-fråga med Python
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"
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)
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.
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
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
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"
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
- Kom igång med kqlmagic för Azure Data Explorer
- Kom igång med kqlmagic för Application Insights
- Kom igång med kqlmagic för Azure Monitor-loggar
- Parametrisera din kqlmagic-fråga med Python
- Välj färgpalett för ditt kqlmagiska frågediagramresultat
- Lär dig Kusto-frågespråk (KQL)