Partager via

Utiliser un notebook et kqlmagic pour analyser des données dans Azure Data Explorer

Jupyter Notebook est une application web open-source qui permet de créer et de partager des documents contenant du code en direct, des équations, des visualisations et du texte explicatif. Elle est utile pour un large éventail de tâches, par exemple le nettoyage et la transformation des données, la simulation numérique, la modélisation statistique, la visualisation des données et l’apprentissage automatique.

Kqlmagic est une commande qui étend les fonctionnalités du noyau Python dans Jupyter Notebook pour que vous puissiez exécuter des requêtes en langage Kusto (KQL) en mode natif. Vous pouvez combiner Python et KQL pour interroger et visualiser des données à l’aide de la vaste bibliothèque Plot.ly intégrée à l’opérateur render. L’extension Kqlmagic est compatible avec Jupyter Lab, Visual Studio Code Jupyter et Azure Data Studio, et les sources de données prises en charge incluent Azure Data Explorer, les journaux Azure Monitor et Application Insights.

Dans cet article, découvrez comment utiliser l’extension Kqlmagic dans un notebook pour vous connecter aux données stockées dans Azure Data Explorer et les interroger.

Prerequisites

  • Un compte Microsoft ou une identité utilisateur Microsoft Entra. Un abonnement Azure n’est pas requis.
  • Un Notebook installé sur votre ordinateur local. Sinon, utilisez Azure Data Studio.
  • Python 3.6. Pour remplacer la version du noyau Jupyter Notebook par Python 3.6, sélectionnez Noyau>Modifier le noyau>Python 3.6.

Installer kqlmagic

Une fois que vous avez installé et chargé l’extension kqlmagic, vous pouvez écrire des requêtes KQL dans le notebook. Si le noyau s’arrête ou si les résultats sont inattendus, rechargez l’extension kqlmagic.

  1. Pour installer kqlmagic, exécutez la commande suivante :

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

  2. Pour charger l’extension kqlmagic, exécutez la commande suivante :

    %reload_ext Kqlmagic

Se connecter à un cluster

Sélectionnez l’onglet correspondant à votre méthode de prédilection pour vous connecter à votre cluster.

Note

Nous vous recommandons d’utiliser la méthode d’authentification de certificat si possible.

Le certificat Microsoft Entra doit être stocké dans un fichier accessible à partir du notebook. Ce fichier peut être référencé dans la chaîne de connexion.

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

Conseil

  • Pour paramétrer la chaîne de connexion, utilisez des valeurs non mises en guillemets, car elles sont interprétées comme des expressions Python.
  • Pour simplifier le processus d’obtention des informations d’identification, consultez Options de connexion.

Exemple de connexion de cluster

La commande suivante utilise la méthode de code Microsoft Entra pour l’authentification auprès de la base de données Samples hébergée sur le cluster help. Pour les utilisateurs autres que Microsoft Entra, remplacez le nom du locataire Microsoft.com par votre locataire Microsoft Entra.

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

Options de connexion

Pour simplifier le processus d’obtention des informations d’identification, vous pouvez ajouter l’un des indicateurs d’option suivants après la chaîne de connexion.

Choix Descriptif Exemple de syntaxe
try_azcli_login Tentative d’obtention d’identifiants d’authentification à partir d’Azure CLI. Attend que vous soyez connecté à l’aide d’Azure CLI. Consultez l’exemple d’une connexion à l’aide d’Azure CLI. -try_azcli_login
try_azcli_login_subscription Tentative d’obtention d’identifiants d’authentification à partir d’Azure CLI en fonction de l’abonnement spécifié. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Tentative d’obtention d’identifiants d’authentification à partir de la connexion au compte Azure Visual Studio Code. -try_vscode_login
try_msi Tentative d’obtention d’identifiants d’authentification à partir du point de terminaison local MSI. Attend un dictionnaire avec les paramètres MSI facultatifs : resource,client_id/object_id/mis_res_id, cloud_environment, timeout. -try_msi={"client_id":<id>}
try_token Effectue l’authentification avec un jeton spécifié. Attend un dictionnaire avec les propriétés de jeton Azure AD v1 ou v2. -try_token={"tokenType":"bearer","accessToken":"<token>"}

Exemple de connexion à l’aide d’Azure CLI

Toutes les options décrites dans le tableau précédent peuvent être ajoutées après une chaîne de connexion. L’exemple suivant utilise l’option de connexion Azure CLI comme méthode d’authentification :

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

Note

Cette option part du principe que vous êtes connecté à Azure à l’aide d’Azure CLI. Si vous n’êtes pas connecté, une fenêtre contextuelle vous invite à vous connecter à Azure.

Afficher les informations de connexion

Pour afficher toutes les connexions existantes, exécutez la commande suivante :

%kql --conn

Pour vérifier les détails d’une connexion spécifique, exécutez la commande suivante :

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

Interroger et visualiser

Interrogez les données à l’aide de l’opérateur de rendu et visualisez les données à l’aide de la bibliothèque ploy.ly. Cette requête et cette visualisation fournit une expérience intégrée qui utilise KQL natif.

Kqlmagic prend en charge la plupart des graphiques, à l’exception de timepivot, pivotchart et ladderchart. Le rendu est pris en charge avec tous les attributs, à l’exception de kind, ysplit et accumulate.

Interroger et afficher un graphique en secteurs

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

Interroger et afficher un graphique temporel

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

Note

Ces graphiques sont interactifs. Sélectionnez un intervalle de temps pour zoomer sur une durée spécifique.

Personnaliser les couleurs du graphique

Si vous n’aimez pas la palette de couleurs par défaut, personnalisez les graphiques à l’aide des options de palette. Les palettes disponibles sont disponibles ici : Choisir la palette de couleurs pour le résultat de votre graphique de requête kqlmagic

  1. Pour obtenir la liste des palettes :

    %kql --palettes -popup_window

  2. Sélectionnez la palette de couleurs cool et affichez de nouveau la requête :

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

Paramétrer une requête avec Python

Kqlmagic permet l’échange simple entre le langage de requête Kusto et Python. Pour en savoir plus : Paramétrer votre requête kqlmagic avec Python

Utiliser une variable Python dans votre requête KQL

Vous pouvez utiliser la valeur d’une variable Python dans votre requête pour filtrer les données :

statefilter = ["TEXAS", "KANSAS"]

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

Convertir les résultats de la requête en DataFrame Pandas

Vous pouvez accéder aux résultats d’une requête KQL dans les DataFrames Pandas. Pour accéder aux résultats de la dernière requête exécutée par la variable _kql_raw_result_ et convertir facilement les résultats en DataFrame Pandas, procédez comme suit :

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

Exemple

Dans de nombreux scénarios d’analyse, vous souhaitez créer des notebooks réutilisables qui contiennent de nombreuses requêtes et alimentent les résultats d’une requête dans les requêtes suivantes. L’exemple ci-dessous utilise la variable Python statefilter pour filtrer les données.

  1. Exécutez une requête pour afficher les 10 principaux états avec maximum DamageProperty :

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

  2. Exécutez une requête pour extraire l’état principal et le définir dans une variable Python :

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

  3. Exécuter une requête en utilisant l’instruction let et la variable Python :

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

  4. Exécuter la commande d’aide :

    %kql --help "help"

Conseil

  • Pour recevoir des informations sur toutes les configurations disponibles, utilisez %config Kqlmagic.
  • Pour résoudre les problèmes et capturer les erreurs Kusto, comme les problèmes de connexion et les requêtes incorrectes, utilisez %config Kqlmagic.short_errors=False

Exemples de notebooks

Contenu associé

  • Last updated on