Usare un'estensione Jupyter Notebook e kqlmagic per analizzare i dati in Azure Esplora dati

  • Articolo

Jupyter Notebook è un'applicazione Web open source che consente di creare e condividere documenti contenenti codice live, equazioni, visualizzazioni e testo narrativo. È utile per un'ampia gamma di attività, ad esempio la pulizia e la trasformazione dei dati, la simulazione numerica, la modellazione statistica, la visualizzazione dei dati e l'apprendimento automatico.

Kqlmagic estende le funzionalità del kernel Python in Jupyter Notebook in modo da poter eseguire query Linguaggio di query Kusto (KQL) in modo nativo. È possibile combinare Python e KQL per eseguire query e visualizzare i dati usando la libreria di Plot.ly avanzata integrata con l'operatore di rendering . L'estensione kqlmagic è compatibile con Jupyter Lab, Visual Studio Code Jupyter e Azure Data Studio e le origini dati supportate includono Azure Esplora dati, log di Monitoraggio di Azure e Application Insights.

In questo articolo si apprenderà come usare kqlmagic in un Jupyter Notebook per connettersi ai dati archiviati in Azure Esplora dati.

Prerequisiti

  • Un account Microsoft o un'identità utente di Microsoft Entra. Non è necessaria una sottoscrizione di Azure.
  • Jupyter Notebook installato nel computer locale. In caso contrario, usare Azure Data Studio.
  • Python 3.6. Per modificare la versione del kernel Jupyter Notebook in Python 3.6, selezionareKernel Change Kernel>>Python 3.6.

Installare kqlmagic

Dopo aver installato e caricato l'estensione kqlmagic, è possibile scrivere query KQL nel notebook. Se il kernel si arresta o i risultati non sono come previsto, ricaricare l'estensione kqlmagic.

  1. Per installare kqlmagic, eseguire il comando seguente:

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

  2. Per caricare l'estensione kqlmagic, eseguire il comando seguente:

    %reload_ext Kqlmagic

Connettersi a un cluster

Selezionare la scheda per il metodo preferito per connettersi al cluster.

Il metodo di codice Microsoft Entra richiede l'accesso interattivo MSAL. Si riceverà un codice da immettere per l'autenticazione.

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

Suggerimento

  • Per parametrizzare la stringa di connessione, usare valori senza virgolette come espressioni Python.
  • Per semplificare il processo di recupero delle credenziali, vedere Opzioni di connessione.

Esempio di connessione del cluster

Il comando seguente usa il metodo di codice Microsoft Entra per eseguire l'autenticazione al Samples database ospitato nel help cluster. Per gli utenti non Microsoft Entra, sostituire il nome Microsoft.com del tenant con il tenant Microsoft Entra.

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

Opzioni di connessione

Per semplificare il processo di recupero delle credenziali, è possibile aggiungere uno dei flag di opzione seguenti dopo il stringa di connessione.

Opzione Descrizione Sintassi di esempio
try_azcli_login Provare a ottenere le credenziali di autenticazione dall'interfaccia della riga di comando di Azure. -try_azcli_login
try_azcli_login_subscription Provare a ottenere le credenziali di autenticazione dall'interfaccia della riga di comando di Azure in base alla sottoscrizione specificata. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Provare a ottenere le credenziali di autenticazione dall'account di Azure di Visual Studio Code. -try_vscode_login
try_msi Provare a ottenere le credenziali di autenticazione dall'endpoint locale del servizio gestito. Si prevede un dizionario con i parametri MSI facoltativi: resource, client_id/object_idmis_res_id/, cloud_environment, . timeout -try_msi={"client_id":<id>}
try_token Eseguire l'autenticazione con un token specificato. Si prevede un dizionario con le proprietà del token di Azure AD v1 o v2. -try_token={"tokenType":"bearer","accessToken":"<token>"}

Esempio di opzione di connessione

Una delle opzioni descritte nella tabella precedente può essere aggiunta dopo un stringa di connessione. Nell'esempio seguente viene usata l'opzione di accesso all'interfaccia della riga di comando di Azure:

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

Visualizzare le informazioni di connessione

Per visualizzare tutte le connessioni esistenti, eseguire il comando seguente:

%kql --conn

Per controllare i dettagli di una connessione specifica, eseguire il comando seguente:

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

Eseguire una query e visualizzare

Eseguire la query dei dati usando l'operatore di rendering e visualizzare i dati tramite la libreria ploy.ly. La query e la visualizzazione forniscono un'esperienza integrata che fa uso di KQL (linguaggio di query Kusto) nativo. Kqlmagic supporta la maggior parte dei grafici tranne timepivot, pivotchart e ladderchart. Il rendering è supportato con tutti gli attributi tranne kind, ysplit e accumulate.

Eseguire una query e il rendering del grafico a torta

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

Eseguire una query e il rendering del diagramma temporale

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

Nota

I grafici sono interattivi. Selezionare un intervallo di tempo per ingrandire un momento specifico.

Personalizzare i colori del grafico

Se non si piace la tavolozza colori predefinita, personalizzare i grafici usando le opzioni della tavolozza. Le tavolozze disponibili sono disponibili qui: scegliere la tavolozza colori per il risultato del grafico della query kqlmagic

  1. Per un elenco delle tavolozze:

    %kql --palettes -popup_window

  2. Selezionare la tavolozza dei colori cool ed eseguire nuovamente il rendering della query:

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

Stabilire i parametri di una query con Python

Kqlmagic consente un semplice interscambio tra Linguaggio di query Kusto e Python. Per altre informazioni: Parametrizzare la query kqlmagic con Python

Usare una variabile di Python nella query KQL

È possibile usare il valore di una variabile di Python nella query per filtrare i dati:

statefilter = ["TEXAS", "KANSAS"]

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

Convertire i risultati della query in dataframe Pandas

È possibile accedere ai risultati di una query KQL in dataframe Pandas. Accedere ai risultati dell'ultima query eseguita tramite la variabile _kql_raw_result_ e convertire facilmente i risultati in dataframe Pandas come indicato di seguito:

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

Esempio

In molti scenari di analitica è possibile creare notebook riutilizzabili contenenti molte query e distribuire i risultati da una query a quelle successive. L'esempio seguente usa la variabile di Python statefilter per filtrare i dati.

  1. Eseguire una query per visualizzare i primi 10 stati con DamageProperty massima:

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

  2. Eseguire una query per estrarre lo stato principale e impostarlo in una variabile di Python:

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

  3. Eseguire una query usando l'istruzione let e la variabile di Python:

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

  4. Eseguire il comando Guida:

    %kql --help "help"

Suggerimento

Per ricevere informazioni su tutte le configurazioni disponibili, usare %config Kqlmagic. Per risolvere e acquisire errori Kusto, ad esempio problemi di connessione e query non corrette, usare %config Kqlmagic.short_errors=False

Notebook di esempio

Contenuti correlati