Используйте блокнот Jupyter и расширение kqlmagic для анализа данных в Azure Data Explorer

  • Статья

Jupyter Notebook — это веб-приложение с открытым исходным кодом, которое позволяет создавать и совместно использовать документы, содержащие динамический код, уравнения, визуализации и текст описания. Она полезна для широкого спектра задач, таких как очистка и преобразование данных, числовое моделирование, статистическое моделирование, визуализация данных и машинное обучение.

Kqlmagic расширяет возможности ядра Python в Jupyter Notebook, что позволяет выполнять запросы язык запросов Kusto (KQL) в собственном коде. Вы можете объединить Python и KQL для запроса и визуализации данных с помощью полнофункциональной библиотеки Plot.ly, интегрированной с оператором render . Расширение kqlmagic совместимо с Jupyter Lab, Visual Studio Code расширением Jupyter и Azure Data Studio. Поддерживаемые источники данных включают Data Explorer Azure, журналы Azure Monitor и Application Insights.

Из этой статьи вы узнаете, как использовать kqlmagic в Jupyter Notebook для подключения и запроса данных, хранящихся в Azure Data Explorer.

Предварительные требования

  • Учетная запись Майкрософт или удостоверение пользователя Microsoft Entra. Подписка Azure не обязательна.
  • Jupyter Notebook установлен на локальном компьютере. В противном случае используйте Azure Data Studio.
  • Python 3.6. Чтобы изменить версию ядра Jupyter Notebook на Python 3.6, выберите Ядро>Изменить ядро>Python 3.6.

Установка kqlmagic

После установки и загрузки расширения kqlmagic можно написать запросы KQL в записной книжке. Если ядро останавливается или результаты не являются ожидаемыми, перезагрузите расширение kqlmagic.

  1. Чтобы установить kqlmagic, выполните следующую команду:

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

  2. Чтобы загрузить расширение kqlmagic, выполните следующую команду:

    %reload_ext Kqlmagic

Подключение к кластеру

Выберите вкладку для предпочтительного метода подключения к кластеру.

Метод кода Microsoft Entra запрашивает интерактивный вход в MSAL. Вы получите код, который нужно ввести для проверки подлинности.

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

Совет

  • Чтобы параметризовать строка подключения, используйте значения без кавов, так как они интерпретируются как выражения Python.
  • Чтобы упростить процесс получения учетных данных, см. раздел Параметры подключения.

Пример подключения к кластеру

Следующая команда использует метод кода Microsoft Entra для проверки подлинности в Samples базе данных, размещенной в кластереhelp. Для пользователей, не являющихся Microsoft Entra, замените имя Microsoft.com клиента своим клиентом Microsoft Entra.

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

Параметры подключения

Чтобы упростить процесс получения учетных данных, можно добавить один из следующих флагов параметров после строка подключения.

Параметр Описание Пример синтаксиса
try_azcli_login Попробуйте получить учетные данные проверки подлинности из Azure CLI. -try_azcli_login
try_azcli_login_subscription Попробуйте получить учетные данные проверки подлинности из Azure CLI на основе указанной подписки. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Попробуйте получить учетные данные для проверки подлинности из Visual Studio Code входа в учетную запись Azure. -try_vscode_login
try_msi Попробуйте получить учетные данные проверки подлинности из локальной конечной точки MSI. Ожидает словарь с необязательными параметрами MSI: resource,/client_idobject_idmis_res_id/ , cloud_environment, . timeout -try_msi={"client_id":<id>}
try_token Проверка подлинности с помощью указанного маркера. Ожидает словарь со свойствами маркера Azure AD версии 1 или 2. -try_token={"tokenType":"bearer","accessToken":"<token>"}

Пример параметра подключения

Любой из параметров, описанных в предыдущей таблице, можно добавить после строка подключения. В следующем примере используется параметр входа в Azure CLI:

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

Отображение сведений о подключении

Чтобы просмотреть все существующие подключения, выполните следующую команду:

%kql --conn

Чтобы проверка сведения о конкретном подключении, выполните следующую команду:

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

Отправка запросов и визуализация

Запрашивайте данные с помощью оператора отображения и визуализируйте их с помощью библиотеки ploy.ly. Для запрашивания и визуализации данных используется интегрированный интерфейс, использующий собственный KQL. Kqlmagic поддерживает большинство диаграмм, за исключением timepivot, pivotchart и ladderchart. Отображение поддерживается для всех атрибутов, за исключением kind, ysplit и accumulate.

Запрос и отображение круговой диаграммы

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

Запрос и отображение временной диаграммы

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

Примечание

Эти диаграммы являются интерактивными. Выберите диапазон времени, чтобы изменить масштаб в соответствии с этим диапазоном.

Настройка цветов диаграммы

Если вам не нравится цветовая палитра по умолчанию, настройте диаграммы с помощью параметров палитры. Доступные палитры можно найти здесь: Выберите цветовую палитру для результата диаграммы запроса kqlmagic.

  1. Для списка палитр:

    %kql --palettes -popup_window

  2. Выберите палитру цветов cool и снова отобразите результаты запроса.

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

Параметризация запроса с помощью Python

Kqlmagic обеспечивает простой обмен данными между язык запросов Kusto и Python. Чтобы узнать больше: Параметризуйте свой запрос kqlmagic с помощью Python

Использование переменной Python в запросе KQL

Для фильтрации данных можно использовать значение переменной Python в своем запросе.

statefilter = ["TEXAS", "KANSAS"]

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

Преобразование результатов запроса в Pandas DataFrame

Вы можете получить доступ к результатам выполнения запроса KQL в Pandas DataFrame. Вы можете получить доступ к результатам последних выполненных запросов с помощью переменной _kql_raw_result_ и легко преобразовать результаты в Pandas DataFrame следующим образом.

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

Пример

Во многих сценариях анализа может потребоваться создать повторно используемые записные книжки, которые содержат множество запросов, и передать результаты из одного запроса в последующие. В следующем примере используется переменная Python statefilter для фильтрации данных.

  1. Выполнение запроса для просмотра 10 состояний с максимальным значением параметра DamageProperty:

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

  2. Выполнение запроса для получения максимального состояния и запись этого значения в переменную Python:

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

  3. Выполнение запроса с использованием инструкции let и переменной Python:

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

  4. Выполнение команды help:

    %kql --help "help"

Совет

Для получения информации обо всех доступных конфигурациях используйте %config Kqlmagic. Для поиска и устранения ошибок Kusto, таких как проблемы с подключением и неправильные запросы, используйте %config Kqlmagic.short_errors=False

Записные книжки с примерами

См. также