Verwenden einer Jupyter Notebook-Instanz und der kqlmagic-Erweiterung zum Analysieren von Daten in Azure Data Explorer

Jupyter Notebook ist eine Open-Source-Webanwendung, mit der Sie Dokumente erstellen und freigeben können, die Live-Code, Formeln, Visualisierungen und narrativen Text enthalten. Es ist nützlich für eine vielzahl von Aufgaben, z. B. Daten sauber ing und Transformation, numerische Simulation, statistische Modellierung, Datenvisualisierung und maschinelles Lernen.

Kqlmagic ist eine Funktion, die die Funktionen des Python-Kernels in Jupyter Notebook erweitert, damit Sie Abfragen in der Kusto-Abfragesprache (KQL) nativ ausführen können. Sie können Python und KQL zum Abfragen und Visualisieren von Daten mithilfe der umfassenden Bibliothek „Plot.ly“ kombinieren, die im render-Operator integriert ist. Die kqlmagic-Erweiterung ist mit jupyter Lab, Visual Studio Code Jupyter Erweiterung und Azure Data Studio kompatibel, und unterstützte Datenquellen umfassen Azure Data Explorer, Azure Monitor-Protokolle und Application Insights.

In diesem Artikel erfahren Sie, wie Sie kqlmagic in einem Jupyter-Notizbuch verwenden, um eine Verbindung mit daten herzustellen und abzufragen, die im Azure-Daten-Explorer gespeichert sind.

Voraussetzungen

• Ein Microsoft-Konto oder eine Microsoft Entra-Benutzeridentität. Ein Azure-Abonnement ist nicht erforderlich.
• Jupyter-Notizbuch auf Ihrem lokalen Computer installiert. Verwenden Sie andernfalls Azure Data Studio.
• Python 3.6. Um die Jupyter Notebook Kernel-Version in Python 3.6 zu ändern, wählen Sie Kernel Ändern Kernel>>Python 3.6.

Installieren von kqlmagic

Nachdem Sie die kqlmagic-Erweiterung installiert und geladen haben, können Sie KQL-Abfragen in Ihrem Notizbuch schreiben. Wenn der Kernel beendet wird oder die Ergebnisse nicht wie erwartet auftreten, laden Sie die kqlmagic-Erweiterung neu.

1. Führen Sie zum Installieren von kqlmagic den folgenden Befehl aus:

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

2. Führen Sie den folgenden Befehl aus, um die kqlmagic-Erweiterung zu laden:

   %reload_ext Kqlmagic
   

Herstellen der Verbindung zu einem Cluster

Wählen Sie die Registerkarte für Ihre bevorzugte Methode aus, um eine Verbindung mit Ihrem Cluster herzustellen.

%kql AzureDataExplorer://tenant='<tenant-id>';certificate='<certificate>';certificate_thumbprint='<thumbprint>';cluster='<cluster-name>';database='<database-name>'

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

%kql AzureDataExplorer://tenant='<tenant-id>';clientid='<aad-appid>';clientsecret='<aad-appkey>';cluster='<cluster-name>';database='<database-name>'

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

%kql azureDataExplorer://anonymous;cluster='<cluster-name>';database='<database-name>'

Beispiel für eine Clusterverbindung

Der folgende Befehl verwendet die Microsoft Entra-Codemethode, um sich bei der Samples im help Cluster gehosteten Datenbank zu authentifizieren. Ersetzen Sie bei Nicht-Microsoft Entra-Benutzern den Mandantennamen Microsoft.com durch Ihren Microsoft Entra-Mandanten.

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

Verbindungsoptionen

Um das Abrufen von Anmeldeinformationen zu vereinfachen, können Sie nach dem Verbindungszeichenfolge eine der folgenden Optionskennzeichnungen hinzufügen.

Beispiel für verbindungsoption

Alle in der vorherigen Tabelle beschriebenen Optionen können nach einem Verbindungszeichenfolge hinzugefügt werden. Im folgenden Beispiel wird die Azure CLI-Anmeldeoption verwendet:

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

Anzeigen von Verbindungsinformationen

Führen Sie den folgenden Befehl aus, um alle vorhandenen Verbindungen anzuzeigen:

%kql --conn

Führen Sie den folgenden Befehl aus, um die Details einer bestimmten Verbindung zu überprüfen:

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

Abfragen und Visualisieren

Fragen Sie Daten mit dem Render-Operator ab, und visualisieren Sie Daten mithilfe der Bibliothek „ploy.ly“ Durch die Abfrage und Visualisierung wird eine integrierte Benutzeroberfläche bereitgestellt, die die native KQL verwendet. Kqlmagic unterstützt abgesehen von timepivot, pivotchart und ladderchart die meisten Diagramme. Der Render-Operator wird mit Ausnahme von kind, ysplit und accumulate mit allen Attributen unterstützt.

Abfragen und Rendern eines Kreisdiagramms

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

Abfragen und Rendern eines Zeitdiagramms

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

Anpassen der Diagrammfarben

Wenn Ihnen die Standardfarbpalette nicht gefällt, können Sie die Diagramme mit Palettenoptionen anpassen. Die verfügbaren Paletten finden Sie hier: Farbpalette für Ihr kqlmagic-Abfragediagrammergebnis auswählen

1. Mit folgendem Befehl rufen Sie eine Liste der Paletten auf:

   %kql --palettes -popup_window
   

2. Wählen Sie die Farbpalette cool aus, und rendern Sie die Abfrage erneut:

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

Parametrisieren einer Abfrage mit Python

Kqlmagic ermöglicht einfachen Austausch zwischen Kusto-Abfragesprache und Python. Weitere Informationen: Parametrisieren Ihrer kqlmagic-Abfrage mit Python

Verwenden einer Python-Variablen in KQL-Abfragen

Sie können den Wert einer Python-Variablen in Ihrer Abfrage verwenden, um die Daten zu filtern:

statefilter = ["TEXAS", "KANSAS"]

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

Konvertieren von Abfrageergebnissen in Pandas Dataframe

Sie können in Pandas DataFrame auf die Ergebnisse einer KQL-Abfrage zugreifen. Wie im folgenden Beispiel gezeigt können Sie mit der Variablen _kql_raw_result_ auf die Ergebnisse der zuletzt ausgeführten Abfrage zugreifen und diese unkompliziert in Pandas DataFrame konvertieren:

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

Beispiel

In vielen Analyseszenarios sollten Sie, wiederverwendbare Notebooks erstellen, die viele Abfragen enthalten und die Ergebnisse einer Abfrage an nachfolgende Abfragen übergeben. Im folgenden Beispiel wird die Python-Variable statefilter verwendet, um die Daten zu filtern.

1. Führen Sie eine Abfrage aus, um die zehn Zustände mit dem Höchstwert für die DamageProperty-Eigenschaft aufzuführen:

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

2. Führen Sie eine Abfrage aus, um den Zustand mit dem Höchstwert zu extrahieren, und legen Sie diesen in einer Python-Variablen fest:

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

3. Führen Sie eine Abfrage mit der let-Anweisung und der Python-Variablen aus:

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

4. Führen Sie den help-Befehl aus:

   %kql --help "help"
   

Beispiel-Notebooks

• Erste Schritte mit kqlmagic für Azure Data Explorer
• Erste Schritte mit kqlmagic für Application Insights
• Erste Schritte mit kqlmagic für Azure Monitor-Protokolle
• Parametrisieren von kqlmagic-Abfragen mit Python
• Auswählen der Farbpalette für das kqlmagic-Abfragendiagrammergebnis

Zugehöriger Inhalt

• Learn Kusto-Abfragesprache (KQL)