Внедрение веб-интерфейса Azure Data Explorer в iframe

Область применения: ✅Microsoft Fabric✅Azure Data Explorer

Веб-интерфейс Azure Data Explorer можно внедрить в iframe и разместить на сторонних веб-сайтах. В этой статье описывается внедрение веб-интерфейса Azure Data Explorer в iframe.

Все функциональные возможности проверяются для специальных возможностей и поддерживают темные и светлые темы на экране.

Внедрение веб-интерфейса в iframe

Добавьте следующий код на веб-сайт:

<iframe
  src="https://dataexplorer.azure.com/?f-IFrameAuth=true&f-UseMeControl=false&workspace=<guid>"
></iframe>

Параметр f-IFrameAuth запроса сообщает веб-интерфейсу не перенаправлять маркер проверки подлинности, а f-UseMeControl=false параметр сообщает веб-интерфейсу , что не отображает всплывающее окно сведений об учетной записи пользователя. Эти действия необходимы, так как веб-сайт размещения отвечает за проверку подлинности.

Параметр workspace=<guid> запроса создает отдельную рабочую область для внедренного iframe. Рабочая область — это единица логики, содержащая вкладки, запросы, параметры и подключения. Задав его уникальное значение, он предотвращает общий доступ к данным между внедренной и не внедренной версией https://dataexplorer.azure.com.

Обработка проверки подлинности

При внедрении веб-интерфейса страница размещения отвечает за проверку подлинности. На следующих схемах описан поток проверки подлинности.

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

1. В приложении прослушивайте сообщение getToken .

   window.addEventListener('message', (event) => {
      if (event.data.signature === "queryExplorer" && event.data.type === "getToken") {
        // CODE-1: Replace this placeholder with code to get the access token from Microsoft Entra ID and
        //         then post a "postToken" message with an access token and an event.data.scope
      }
   })    
   

2. Определите функцию для сопоставления event.data.scope области Microsoft Entra. Используйте следующую таблицу, чтобы решить, как сопоставить event.data.scope области Microsoft Entra:

   Ресурс	event.data.scope	Область Microsoft Entra
   Кластер	query	https://{your_cluster}.{your_region}.kusto.windows.net/.default
   График	People.Read	People.Read, , User.ReadBasic.AllGroup.Read.All
   Панели мониторинга	https://rtd-metadata.azurewebsites.net/user_impersonation	https://rtd-metadata.azurewebsites.net/user_impersonation

   Например, следующие области функций сопоставляются на основе сведений в таблице.

       function mapScope(scope) {
           switch(scope) {
               case "query": return ["https://your_cluster.your_region.kusto.windows.net/.default"];
               case "People.Read": return ["People.Read", "User.ReadBasic.All", "Group.Read.All"];
               default: return [scope]
           }
       }
   

3. Получите маркер доступа JWT из проверки подлинности одностраничного приложения (SPA) для области. Этот код заменяет заполнитель CODE-1.

   Например, можно использовать @azure/MSAL-react для получения маркера доступа. В примере используется функция mapScope , определенная ранее.

   import { useMsal } from "@azure/msal-react";
   const { instance, accounts } = useMsal();
   
   instance.acquireTokenSilent({
     scopes: mapScope(event.data.scope),
     account: accounts[0],
   })
   .then((response) =>
       var accessToken = response.accessToken
       // - CODE-2: Replace this placeholder with code to post a "postToken" message with an access token and an event.data.scope
   )
   

   Внимание

   Имя участника-пользователя (UPN) можно использовать только для проверки подлинности, субъекты-службы не поддерживаются.

4. Разместите сообщение postToken с маркером доступа. Этот код заменяет заполнитель CODE-2:

        iframeWindow.postMessage({
            "type": "postToken",
            "message": // the access token your obtained earlier
            "scope": // event.data.scope as passed to the "getToken" message
        }, '*');
      }
   

   Внимание

   Окно размещения должно обновить маркер до истечения срока действия, отправив новое сообщение postToken с обновленными маркерами. В противном случае после истечения срока действия маркеров вызовы служб завершаются сбоем.

Внедрение панелей мониторинга

Чтобы внедрить панель мониторинга, необходимо установить связь доверия между приложением Microsoft Entra узла и службой панели мониторинга Azure Data Explorer (служба метаданных RTD).

1. Выполните действия, описанные в разделе "Выполнение проверки подлинности одностраничного приложения (SPA).

2. Откройте портал Azure и убедитесь, что вы вошли в правильный клиент. В правом верхнем углу проверьте удостоверение, используемое для входа на портал.

3. В области ресурсов выберите идентификатор Microsoft Entra ID> Регистрация приложений.

4. Найдите приложение, которое использует поток от имени и откройте его.

5. Выберите манифест.

6. Выберите requiredResourceAccess.

7. В манифесте добавьте следующую запись:

     {
       "resourceAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
       "resourceAccess": [
           {
               "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
               "type": "Scope"
           }
       ]
     }
   

   • 00001111-aaaa-2222-bbbb-3333cccc4444 — это идентификатор приложения службы панели мониторинга Azure Data Explorer.
   • 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c — это разрешение user_impersonation.

8. Сохраните изменения в манифесте.

9. Выберите разрешения API и проверьте, есть новая запись: служба метаданных RTD.

10. В Microsoft Graph добавьте разрешения для People.Read, User.ReadBasic.Allа также Group.Read.All.

11. В Azure PowerShell добавьте следующий новый субъект-службу для приложения:

    New-MgServicePrincipal -AppId 00001111-aaaa-2222-bbbb-3333cccc4444
    

    Если возникла Request_MultipleObjectsWithSameKeyValue ошибка, это означает, что приложение уже находится в клиенте, указывающее, что оно было успешно добавлено.

12. На странице разрешений API выберите предоставить согласие администратора на согласие для всех пользователей.

 <iframe src="https://dataexplorer.azure.com/dashboards?[feature-flags]" />

"f-IFrameAuth": true,
"f-PersistAfterEachRun": true,
"f-Homepage": false,
"f-ShowPageHeader": false,
"f-ShowNavigation": false,
"f-DisableExploreQuery": false,

Флаги функций

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

Флаг компонента можно использовать в URL-адресе в качестве параметра запроса. Чтобы отключить добавление других кластеров, используйте https://dataexplorer.azure.com/?f-ShowConnectionButtons=false в приложении размещения.

Связанный контент

• Обзор языка запросов Kusto (KQL)
• Написание запросов Kusto
• Пример внедрения