Share via

Utilizar uma extensão Jupyter Notebook e kqlmagic para analisar dados no Azure Data Explorer

  • Artigo

Jupyter Notebook é uma aplicação Web open source que lhe permite criar e partilhar documentos que contenham código dinâmico, equações, visualizações e texto narrativo. É útil para uma vasta gama de tarefas, como limpeza e transformação de dados, simulação numérica, modelação estatística, visualização de dados e machine learning.

O Kqlmagic expande as capacidades do kernel do Python no Jupyter Notebook para que possa executar consultas Linguagem de Pesquisa Kusto (KQL) nativamente. Pode combinar Python e KQL para consultar e visualizar dados com a biblioteca de Plot.ly avançada integrada com o operador de composição . A extensão kqlmagic é compatível com o Jupyter Lab, a extensão Jupyter do Visual Studio Code e o Azure Data Studio e as origens de dados suportadas incluem o Azure Data Explorer, os registos do Azure Monitor e o Application Insights.

Neste artigo, irá aprender a utilizar kqlmagic numa Jupyter Notebook para ligar e consultar dados armazenados no Azure Data Explorer.

Pré-requisitos

  • Uma conta Microsoft ou uma identidade de utilizador Microsoft Entra. Não é necessária uma subscrição do Azure.
  • Jupyter Notebook instalado no seu computador local. Caso contrário, utilize o Azure Data Studio.
  • Python 3.6. Para alterar a versão Jupyter Notebook kernel para Python 3.6, selecione KernelAlterar Kernel>>Python 3.6.

Instalar kqlmagic

Depois de instalar e carregar a extensão kqlmagic, pode escrever consultas KQL no seu bloco de notas. Se o kernel parar ou os resultados não forem os esperados, recarregue a extensão kqlmagica.

  1. Para instalar o kqlmagic, execute o seguinte comando:

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

  2. Para carregar a extensão kqlmagic, execute o seguinte comando:

    %reload_ext Kqlmagic

Ligar a um cluster

Selecione o separador do seu método preferencial para ligar ao cluster.

O método de código Microsoft Entra pede o início de sessão interativo da MSAL. Receberá um código para introduzir para autenticação.

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

Dica

  • Para parametrizar o cadeia de ligação, utilize valores não listados, uma vez que são interpretados como expressões Python.
  • Para simplificar o processo de obtenção de credenciais, veja Opções de ligação.

Exemplo de ligação de cluster

O comando seguinte utiliza o método de código Microsoft Entra para autenticar na Samples base de dados alojada no help cluster. Para utilizadores que não Microsoft Entra, substitua o nome Microsoft.com do inquilino pelo seu inquilino Microsoft Entra.

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

Opções de ligação

Para simplificar o processo de obtenção de credenciais, pode adicionar um dos seguintes sinalizadores de opção após o cadeia de ligação.

Opção Descrição Sintaxe de exemplo
try_azcli_login Tente obter credenciais de autenticação da CLI do Azure. -try_azcli_login
try_azcli_login_subscription Tente obter credenciais de autenticação da CLI do Azure com base na subscrição especificada. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Tente obter credenciais de autenticação a partir do início de sessão da conta do Azure do Visual Studio Code. -try_vscode_login
try_msi Tente obter credenciais de autenticação a partir do ponto final local do MSI. Espera um dicionário com os parâmetros MSI opcionais: resource, ,object_idmis_res_id//client_id , . cloud_environmenttimeout -try_msi={"client_id":<id>}
try_token Autenticar com um token especificado. Espera um dicionário com Azure AD propriedades de token v1 ou v2. -try_token={"tokenType":"bearer","accessToken":"<token>"}

Exemplo de opção de ligação

Qualquer uma das opções descritas na tabela anterior pode ser adicionada após uma cadeia de ligação. O exemplo seguinte utiliza a opção de início de sessão da CLI do Azure:

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

Apresentar informações de ligação

Para ver todas as ligações existentes, execute o seguinte comando:

%kql --conn

Para verificar os detalhes de uma ligação específica, execute o seguinte comando:

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

Consultar e visualizar

Consultar dados com o operador de composição e visualizar dados com a biblioteca de ploy.ly. Esta consulta e visualização fornecem uma experiência integrada que utiliza KQL nativo. O Kqlmagic suporta a maioria dos gráficos, exceto timepivot, pivotcharte ladderchart. A composição é suportada com todos os atributos, exceto kind, ysplite accumulate.

Consultar e compor gráfico circular

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

Consultar e compor o tempograma

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

Nota

Estes gráficos são interativos. Selecione um intervalo de tempo para ampliar uma hora específica.

Personalizar as cores do gráfico

Se não gostar da paleta de cores predefinida, personalize os gráficos com as opções de paleta. As paletas disponíveis podem ser encontradas aqui: selecione a paleta de cores para o resultado do gráfico de consultas kqlmagico

  1. Para obter uma lista de paletas:

    %kql --palettes -popup_window

  2. Selecione a cool paleta de cores e volte a compor a consulta:

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

Parametrizar uma consulta com Python

O Kqlmagic permite um intercâmbio simples entre Linguagem de Pesquisa Kusto e Python. Para saber mais: Parametrizar a consulta kqlmagica com Python

Utilizar uma variável Python na consulta KQL

Pode utilizar o valor de uma variável Python na consulta para filtrar os dados:

statefilter = ["TEXAS", "KANSAS"]

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

Converter resultados de consulta em DataFrame do Pandas

Pode aceder aos resultados de uma consulta KQL no Pandas DataFrame. Aceda aos resultados da última consulta executada por variável _kql_raw_result_ e converta facilmente os resultados em DataFrame do Pandas da seguinte forma:

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

Exemplo

Em muitos cenários de análise, poderá querer criar blocos de notas reutilizáveis que contenham muitas consultas e alimentar os resultados de uma consulta em consultas subsequentes. O exemplo abaixo utiliza a variável statefilter Python para filtrar os dados.

  1. Execute uma consulta para ver os 10 principais estados com o máximo DamageProperty:

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

  2. Execute uma consulta para extrair o estado superior e defina-a numa variável python:

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

  3. Execute uma consulta com a let instrução e a variável Python:

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

  4. Execute o comando de ajuda:

    %kql --help "help"

Dica

Para receber informações sobre todas as configurações disponíveis, utilize %config Kqlmagic. Para resolver e capturar erros do Kusto, como problemas de ligação e consultas incorretas, utilize %config Kqlmagic.short_errors=False

Blocos de notas de exemplo

Conteúdo relacionado