Freigeben über

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, Gleichungen, Visualisierungen und beschreibenden Text enthalten. Es ist nützlich für eine breite Palette 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, der 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.

Hinweis

Es wird empfohlen, nach Möglichkeit die Zertifikatmethode der Authentifizierung zu verwenden.

Das Microsoft Entra-Zertifikat sollte in einer Datei gespeichert werden, auf die über das Notizbuch zugegriffen werden kann. Auf diese Datei kann im Verbindungszeichenfolge verwiesen werden.

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

Tipp

  • Um die Verbindungszeichenfolge zu parametrisieren, verwenden Sie nicht zitierte Werte, wie sie als Python-Ausdrücke interpretiert werden.
  • Informationen zum Vereinfachen des Abrufens von Anmeldeinformationen finden Sie unter "Verbindungsoptionen".

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.

Option Beschreibung Beispielsyntax
try_azcli_login Versuchen Sie, Authentifizierungsanmeldeinformationen von Azure CLI abzurufen. -try_azcli_login
try_azcli_login_subscription Versuchen Sie, Authentifizierungsanmeldeinformationen basierend auf dem angegebenen Abonnement von Azure CLI abzurufen. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Versuchen Sie, Authentifizierungsanmeldeinformationen aus der Azure-Kontoanmeldung von Visual Studio Code 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 mit einem angegebenen Token. Erwartet ein Wörterbuch mit Azure AD v1- oder v2-Tokeneigenschaften. -try_token={"tokenType":"bearer","accessToken":"<token>"}

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 
| take 10
| 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 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
| take 10
| 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
| take 10

  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

Zugehöriger Inhalt