Partager via

Utiliser un notebook Jupyter et l’extension kqlmagic pour analyser des données dans Azure Data Explorer

  • Article

Jupyter Notebook est une application web open source qui vous permet de créer et de partager des documents contenant du code exécutable en temps réel, des équations, des visualisations et du texte narratif. Elle s’avère 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 le Machine Learning.

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

Dans cet article, vous allez apprendre à utiliser kqlmagic dans un notebook Jupyter pour vous connecter et interroger des données stockées dans Azure Data Explorer.

Prérequis

  • Un compte Microsoft ou une identité utilisateur Microsoft Entra. Un abonnement Azure n’est pas requis.
  • Jupyter 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 votre notebook. Si le noyau s’arrête ou si les résultats ne sont pas comme prévu, 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 de votre méthode préférée pour vous connecter à votre cluster.

Remarque

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 le chaîne de connexion.

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

Conseil

  • Pour paramétrer le 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 les options de connexion.

Exemple de connexion de cluster

La commande suivante utilise la méthode de code Microsoft Entra pour s’authentifier auprès de la Samples base de données hébergée sur le help cluster. Pour les utilisateurs non-Microsoft Entra, remplacez le nom Microsoft.com du locataire 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 le chaîne de connexion.

Option Description Exemple de syntaxe
try_azcli_login Essayez d’obtenir des informations d’identification d’authentification à partir d’Azure CLI. -try_azcli_login
try_azcli_login_subscription Essayez d’obtenir des informations d’identification d’authentification à partir d’Azure CLI en fonction de l’abonnement spécifié. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Essayez d’obtenir des informations d’identification d’authentification à partir de la connexion au compte Azure Visual Studio Code. -try_vscode_login
try_msi Essayez d’obtenir des informations d’identification d’authentification à partir du point de terminaison local MSI. Attend un dictionnaire avec les paramètres MSI facultatifs : resource,/client_idobject_idmis_res_id/ , cloud_environment, . timeout -try_msi={"client_id":<id>}
try_token Authentifiez-vous 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 d’option de connexion

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

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

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

Remarque

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 : choisissez 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 un échange simple entre 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 tramedonnées Pandas

Vous pouvez accéder aux résultats d’une requête KQL dans les tramedonnées 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 tramedonnées 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 connexe