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

  • Artikel

Jupyter Notebook ist eine Open-Source-Webanwendung, mit der Sie Dokumente erstellen und freigeben können, die Livecode, Formeln, Visualisierungen und narrativen Text enthalten. Es ist nützlich für eine Vielzahl von Aufgaben, z. B. Datenreinigung 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. Unterstützte Datenquellen sind Azure Data Explorer, Azure Monitor-Protokolle und Application Insights.

In diesem Artikel erfahren Sie, wie Sie kqlmagic in einer Jupyter Notebook verwenden, um eine Verbindung mit in Azure Data Explorer gespeicherten Daten herzustellen und diese abzufragen.

Voraussetzungen

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

Installieren von kqlmagic

Nachdem Sie die Erweiterung kqlmagic installiert und geladen haben, können Sie KQL-Abfragen in Ihr Notebook schreiben. Wenn der Kernel beendet wird oder die Ergebnisse nicht wie erwartet angezeigt werden, laden Sie die Erweiterung kqlmagic 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.

Die Microsoft Entra Codemethode fordert die interaktive MSAL-Anmeldung auf. Sie erhalten einen Code, der für die Authentifizierung eingegeben werden soll.

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

Tipp

  • Um die Verbindungszeichenfolge zu parametrisieren, verwenden Sie werte ohne Zitate, da sie als Python-Ausdrücke interpretiert werden.
  • Informationen zum Abrufen von Anmeldeinformationen finden Sie unter Verbindungsoptionen.

Beispiel für eine Clusterverbindung

Der folgende Befehl verwendet die Microsoft Entra Codemethode, um sich bei der im help Cluster gehosteten Samples Datenbank zu authentifizieren. Ersetzen Sie für Benutzer, die nicht Microsoft Entra, den Mandantennamen Microsoft.com durch Ihren Microsoft Entra Mandanten.

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

Verbindungsoptionen

Um den Prozess des Abrufens von Anmeldeinformationen zu vereinfachen, können Sie nach dem Verbindungszeichenfolge eines der folgenden Optionsflags hinzufügen.

Option BESCHREIBUNG Beispielsyntax
try_azcli_login Versuchen Sie, Authentifizierungsanmeldeinformationen von der Azure CLI abzurufen. -try_azcli_login
try_azcli_login_subscription Versuchen Sie, Authentifizierungsanmeldeinformationen von der Azure CLI basierend auf dem angegebenen Abonnement abzurufen. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Versuchen Sie, Authentifizierungsanmeldeinformationen von der Visual Studio Code Azure-Kontoanmeldung abzurufen. -try_vscode_login
try_msi Versuchen Sie, Authentifizierungsanmeldeinformationen vom lokalen MSI-Endpunkt abzurufen. Erwartet ein Wörterbuch mit den optionalen MSI-Parametern: resource,/client_idobject_idmis_res_id/ , , . timeoutcloud_environment -try_msi={"client_id":<id>}
try_token Authentifizieren Sie sich mit einem angegebenen Token. Erwartet ein Wörterbuch mit Azure AD v1- oder v2-Tokeneigenschaften. -try_token={"tokenType":"bearer","accessToken":"<token>"}

Beispiel für die Verbindungsoption

Jede der in der vorherigen Tabelle beschriebenen Optionen kann nach einer 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

Hinweis

Diese Diagramme sind interaktiv. Wählen Sie einen Zeitbereich aus, um einen bestimmten Zeitraum zu vergrößern.

Anpassen der Diagrammfarben

Wenn Ihnen die Standardfarbpalette nicht gefällt, können Sie die Diagramme mit Palettenoptionen anpassen. Die verfügbaren Paletten finden Sie auf der folgenden Website: Auswählen der Farbpalette für das kqlmagic-Abfragendiagrammergebnis

  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 den einfachen Austausch zwischen Kusto-Abfragesprache und Python. Weitere Informationen: Parametrisieren von kqlmagic-Abfragen 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"

Tipp

Um Informationen zu allen verfügbaren Konfigurationen zu erhalten, verwenden Sie %config Kqlmagic. Verwenden Sie zum Beheben und Erfassen von Kusto-Fehlern (z. B. Verbindungsprobleme und falsche Abfragen) %config Kqlmagic.short_errors=False.

Beispiel-Notebooks

Verwandte Inhalte