Compartir a través de

Uso de una instancia de Jupyter Notebook y una extensión de kqlmagic para analizar datos en Azure Data Explorer

  • Artículo

Jupyter Notebook es una aplicación web de código abierto que le permite crear y compartir documentos que contengan código activo, ecuaciones, visualizaciones y texto narrativo. Resulta útil para una amplia gama de tareas, como la limpieza y transformación de datos, la simulación numérica, el modelado estadístico, la visualización de datos y el aprendizaje automático.

Kqlmagic amplía las funciones del kernel de Python en Jupyter Notebook para que pueda ejecutar consultas del lenguaje de consulta Kusto (KQL) de forma nativa. Puede combinar Python y KQL para hacer consultas y visualizar datos mediante la biblioteca Plot.ly enriquecida integrada con el operador render. La extensión kqlmagic es compatible con Jupyter Lab, la extensión Jupyter de Visual Studio Code y Azure Data Studio, y los orígenes de datos admitidos incluyen Azure Data Explorer, registros de Azure Monitor y Application Insights.

En este artículo, aprenderá a usar kqlmagic en un cuaderno de Jupyter Notebook para conectarse a datos almacenados en Azure Data Explorer y consultarlos.

Requisitos previos

  • Una cuenta de Microsoft o una identidad de usuario de Microsoft Entra. No se necesita una suscripción a Azure.
  • Jupyter Notebook instalado en el equipo local. De lo contrario, use Azure Data Studio.
  • Python 3.6. Para cambiar la versión del kernel de Jupyter Notebook a Python 3.6, seleccione Kernel Change Kernel Python 3.6 (Cambiar kernel>>python 3.6).

Instalación de kqlmagic

Una vez que instale y cargue la extensión kqlmagic, puede escribir consultas KQL en el cuaderno. Si el kernel se detiene o los resultados no son los esperados, vuelva a cargar la extensión kqlmagic.

  1. Para instalar kqlmagic, ejecute el siguiente comando:

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

  2. Para cargar la extensión kqlmagic, ejecute el siguiente comando:

    %reload_ext Kqlmagic

Conectarse a un clúster

Seleccione la pestaña del método preferido para conectarse al clúster.

Nota:

Se recomienda usar el método certificate de autenticación siempre que sea posible.

El certificado de Microsoft Entra debe almacenarse en un archivo accesible desde el cuaderno. Se puede hacer referencia a este archivo en el cadena de conexión.

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

Sugerencia

  • Para parametrizar el cadena de conexión, use valores sin comillas, ya que se interpretan como expresiones de Python.
  • Para simplificar el proceso de obtención de credenciales, consulte Opciones de conexión.

Ejemplo de conexión de clúster

El comando siguiente usa el método de código Microsoft Entra para autenticarse en la Samples base de datos hospedada en el help clúster. Para los usuarios que no son de Microsoft Entra, reemplace el nombre Microsoft.com del inquilino por su inquilino de Microsoft Entra.

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

Opciones de conexión

Para simplificar el proceso de obtención de credenciales, puede agregar una de las siguientes marcas de opción después del cadena de conexión.

Opción Descripción Ejemplo de sintaxis
try_azcli_login Intente obtener las credenciales de autenticación de la CLI de Azure. -try_azcli_login
try_azcli_login_subscription Intente obtener las credenciales de autenticación de la CLI de Azure en función de la suscripción especificada. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Intente obtener las credenciales de autenticación del inicio de sesión de la cuenta de Azure de Visual Studio Code. -try_vscode_login
try_msi Intente obtener las credenciales de autenticación del punto de conexión local msi. Espera un diccionario con los parámetros MSI opcionales: resource, client_id/object_idmis_res_id/, cloud_environment, . timeout -try_msi={"client_id":<id>}
try_token Autentíquese con un token especificado. Espera un diccionario con las propiedades de token de Azure AD v1 o v2. -try_token={"tokenType":"bearer","accessToken":"<token>"}

Ejemplo de opción de conexión

Cualquiera de las opciones descritas en la tabla anterior se puede agregar después de un cadena de conexión. En el ejemplo siguiente se usa la opción de inicio de sesión de la CLI de Azure:

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

Mostrar información de conexión

Para ver todas las conexiones existentes, ejecute el siguiente comando:

%kql --conn

Para comprobar los detalles de una conexión específica, ejecute el siguiente comando:

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

Consultar y visualizar

Consulte datos mediante el operador “render” y visualice datos mediante la biblioteca de ploy.ly. Esta consulta y visualización proporciona una experiencia integrada que usa KQL de forma nativa. Kqlmagic admite la mayoría de los gráficos, excepto timepivot, pivotchart y ladderchart. La representación se admite con todos los atributos, excepto kind, ysplit y accumulate.

Consultar y representar un gráfico circular

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

Consultar y representar un gráfico de tiempo

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

Nota:

Los gráficos son interactivos. Seleccione un intervalo de tiempo para explorar un momento específico.

Personalizar los colores del gráfico

Si no le gusta la paleta de colores predeterminada, puede personalizar los gráficos con opciones de paleta. Las paletas disponibles se pueden encontrar aquí: Elija la paleta de colores para el resultado del gráfico de consultas kqlmagic.

  1. Para obtener una lista de paleta:

    %kql --palettes -popup_window

  2. Seleccione la paleta de colores cool y vuelva a representar la consulta:

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

Parametrizar una consulta con Python

Kqlmagic permite un intercambio sencillo entre Lenguaje de consulta Kusto y Python. Para más información: Parametrización de la consulta kqlmagic con Python

Usar una variable de Python en una consulta KQL

Puede usar el valor de una variable de Python en una consulta para filtrar los datos:

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 resultados de la consulta en Pandas DataFrame

Puede acceder a los resultados de una consulta KQL en Pandas DataFrame. Accederá a los resultados de la última consulta ejecutada mediante la variable _kql_raw_result_ y podrá convertir fácilmente los resultados en Pandas DataFrame, como se indica a continuación:

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

Ejemplo

En muchos escenarios de análisis, puede que quiera crear blocs de notas reutilizables que contengan un gran número de consultas y pasar los resultados de una consulta a consultas posteriores. En el ejemplo siguiente, se usa la variable de Python statefilter para filtrar los datos.

  1. Ejecute la consulta para ver los 10 estados principales con un máximo de DamageProperty:

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

  2. Ejecute una consulta para extraer el estado principal y establecerlo en una variable de Python:

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

  3. Ejecute una consulta con la instrucción let y la variable de Python:

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

  4. Ejecute el comando de ayuda:

    %kql --help "help"

Sugerencia

Para recibir información sobre todas las configuraciones disponibles, use %config Kqlmagic. Para solucionar problemas y capturar errores de Kusto, como problemas de conexión y consultas incorrectas, use %config Kqlmagic.short_errors=False.

Cuadernos de ejemplo

Contenido relacionado