Delen via

Een Jupyter Notebook- en kqlmagic-extensie gebruiken om gegevens te analyseren in Azure Data Explorer

  • Artikel

Jupyter Notebook is een opensource-webtoepassing waarmee u documenten met livecode, vergelijkingen, visualisaties en verhalende tekst kunt maken en delen. Het is handig voor een breed scala aan taken, zoals het opschonen en transformeren van gegevens, numerieke simulatie, statistische modellering, gegevensvisualisatie en machine learning.

Kqlmagic breidt de mogelijkheden van de Python-kernel in Jupyter Notebook uit, zodat u Kusto-querytaal -query's (KQL) systeemeigen kunt uitvoeren. U kunt Python en KQL combineren om gegevens op te vragen en te visualiseren met behulp van de rich Plot.ly-bibliotheek die is geïntegreerd met de render-operator . De kqlmagic-extensie is compatibel met Jupyter Lab, Visual Studio Code Jupyter-extensie en Azure Data Studio, en ondersteunde gegevensbronnen zijn Azure Data Explorer, Azure Monitor-logboeken en Application Insights.

In dit artikel leert u hoe u kqlmagic gebruikt in een Jupyter Notebook om verbinding te maken met en query's uit te voeren op gegevens die zijn opgeslagen in Azure Data Explorer.

Vereisten

  • Een Microsoft-account of een Microsoft Entra gebruikersidentiteit. Er is geen Azure-abonnement vereist.
  • Jupyter Notebook geïnstalleerd op uw lokale computer. Gebruik anders Azure Data Studio.
  • Python 3.6. Als u de Jupyter Notebook kernelversie wilt wijzigen in Python 3.6, selecteert u Kernel>wijzigen Python>3.6.

kqlmagic installeren

Nadat u de kqlmagic-extensie hebt geïnstalleerd en geladen, kunt u KQL-query's schrijven in uw notebook. Als de kernel stopt of als de resultaten niet naar verwachting zijn, laadt u de extensie kqlmagic opnieuw.

  1. Voer de volgende opdracht uit om kqlmagic te installeren:

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

  2. Voer de volgende opdracht uit om de extensie kqlmagic te laden:

    %reload_ext Kqlmagic

Verbinding maken met een cluster

Selecteer het tabblad voor de methode van uw voorkeur om verbinding te maken met uw cluster.

De methode Microsoft Entra code vraagt om interactieve MSAL-aanmelding. U ontvangt een code die u moet invoeren voor verificatie.

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

Tip

  • Als u de verbindingsreeks wilt parameteriseren, gebruikt u waarden zonder aanhalingstekens omdat deze worden geïnterpreteerd als Python-expressies.
  • Zie Verbindingsopties om het ophalen van referenties te vereenvoudigen.

Voorbeeld van een clusterverbinding

Met de volgende opdracht wordt de codemethode Microsoft Entra gebruikt om te verifiëren bij de Samples database die wordt gehost op het help cluster. Voor niet-Microsoft Entra gebruikers vervangt u de tenantnaam Microsoft.com door uw Microsoft Entra tenant.

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

Verbindingsopties

Om het ophalen van referenties te vereenvoudigen, kunt u een van de volgende optievlagmen toevoegen nadat de verbindingsreeks.

Optie Beschrijving Voorbeeldsyntaxis
try_azcli_login Probeer verificatiereferenties op te halen uit Azure CLI. -try_azcli_login
try_azcli_login_subscription Probeer verificatiereferenties op te halen uit Azure CLI op basis van het opgegeven abonnement. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Probeer verificatiereferenties op te halen uit aanmelden bij het Azure-account van Visual Studio Code. -try_vscode_login
try_msi Probeer verificatiereferenties op te halen van het lokale MSI-eindpunt. Verwacht een woordenlijst met de optionele MSI-parameters: resource,/client_idobject_idmis_res_id/ , cloud_environment, . timeout -try_msi={"client_id":<id>}
try_token Verifieer met een opgegeven token. Verwacht een woordenlijst met Azure AD v1- of v2-tokeneigenschappen. -try_token={"tokenType":"bearer","accessToken":"<token>"}

Voorbeeld van verbindingsoptie

Alle opties die in de vorige tabel worden beschreven, kunnen worden toegevoegd na een verbindingsreeks. In het volgende voorbeeld wordt de azure CLI-aanmeldingsoptie gebruikt:

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

Verbindingsgegevens weergeven

Voer de volgende opdracht uit om alle bestaande verbindingen te zien:

%kql --conn

Voer de volgende opdracht uit om de details van een specifieke verbinding te controleren:

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

Query's uitvoeren en visualiseren

Query's uitvoeren op gegevens met behulp van de operator render en gegevens visualiseren met behulp van de ploy.ly-bibliotheek. Deze query en visualisatie bieden een geïntegreerde ervaring die gebruikmaakt van systeemeigen KQL. Kqlmagic ondersteunt de meeste grafieken, behalve timepivot, pivotcharten ladderchart. Render wordt ondersteund met alle kenmerken, behalve kind, yspliten accumulate.

Cirkeldiagram opvragen en weergeven

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

Tijddiagram query's uitvoeren en weergeven

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

Notitie

Deze grafieken zijn interactief. Selecteer een tijdsbereik om in te zoomen op een specifiek tijdstip.

De grafiekkleuren aanpassen

Als het standaardkleurenpalet u niet bevalt, past u de grafieken aan met behulp van paletopties. De beschikbare paletten vindt u hier: Kleurenpalet kiezen voor het resultaat van uw kqlmagic-querygrafiek

  1. Voor een lijst met paletten:

    %kql --palettes -popup_window

  2. Selecteer het cool kleurenpalet en geef de query opnieuw weer:

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

Een query parametriseren met Python

Kqlmagic maakt eenvoudige uitwisseling mogelijk tussen Kusto-querytaal en Python. Voor meer informatie: Uw kqlmagic-query parameteriseren met Python

Een Python-variabele gebruiken in uw KQL-query

U kunt de waarde van een Python-variabele in uw query gebruiken om de gegevens te filteren:

statefilter = ["TEXAS", "KANSAS"]

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

Queryresultaten converteren naar Pandas DataFrame

U hebt toegang tot de resultaten van een KQL-query in Pandas DataFrame. Open de laatst uitgevoerde queryresultaten per variabele _kql_raw_result_ en converteer de resultaten eenvoudig als volgt naar Pandas DataFrame:

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

Voorbeeld

In veel analysescenario's wilt u mogelijk herbruikbare notebooks maken die veel query's bevatten en de resultaten van de ene query in de volgende query's invoeren. In het onderstaande voorbeeld wordt de Python-variabele statefilter gebruikt om de gegevens te filteren.

  1. Voer een query uit om de top 10 statussen met maximum DamagePropertyweer te geven:

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

  2. Voer een query uit om de bovenste status te extraheren en deze in te stellen in een Python-variabele:

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

  3. Voer een query uit met behulp van de let instructie en de Python-variabele:

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

  4. Voer de Help-opdracht uit:

    %kql --help "help"

Tip

Als u informatie wilt ontvangen over alle beschikbare configuraties, gebruikt u %config Kqlmagic. Als u Kusto-fouten, zoals verbindingsproblemen en onjuiste query's, wilt oplossen en vastleggen, gebruikt u %config Kqlmagic.short_errors=False

Voorbeelden van notebooks

Gerelateerde inhoud