iframe에 Azure Data Explorer 웹 UI 포함

아티클
10/30/2024

적용 대상: ✅Microsoft Fabric ✅Azure Data Explorer

Azure Data Explorer 웹 UI는 iframe에 포함되고 타사 웹 사이트에 호스트될 수 있습니다. 이 문서에서는 Azure Data Explorer 웹 UI를 iframe에 포함하는 방법을 설명합니다.

Azure Data Explorer 웹 U I의 스크린샷

모든 기능은 접근성을 테스트하고 화면의 어두운 테마와 밝은 테마를 지원합니다.

iframe에 웹 UI를 포함하는 방법

웹 사이트에 다음 코드를 추가합니다.

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

쿼리 매개 변수는 f-IFrameAuth 인증 토큰을 가져오도록 리디렉션하지 않도록 웹 UI에 지시하고 f-UseMeControl=false 매개 변수는 웹 UI에 사용자 계정 정보 팝업 창을 표시하지 않도록 지시합니다. 호스팅 웹 사이트가 인증을 담당하기 때문에 이러한 작업이 필요합니다.

쿼리 매개 변수는 workspace=<guid> 포함된 iframe에 대해 별도의 작업 영역을 만듭니다. 작업 영역은 탭, 쿼리, 설정 및 연결을 포함하는 논리 단위입니다. 고유한 값으로 설정하면 포함된 버전과 포함되지 않은 버전의 https://dataexplorer.azure.com데이터 공유를 방지합니다.

인증 처리

웹 UI를 포함할 때 호스팅 페이지는 인증을 담당합니다. 다음 다이어그램에서는 인증 흐름을 설명합니다.

다음 단계를 사용하여 인증을 처리합니다.

애플리케이션에서 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
   }
})

Microsoft Entra 범위에 매핑할 event.data.scope 함수를 정의합니다. 다음 표를 사용하여 Microsoft Entra 범위에 매핑 event.data.scope 하는 방법을 결정합니다.

리소스	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]
        }
    }

범위에 대한 SPA(단일 페이지 애플리케이션) 인증 에서 JWT 액세스 토큰을 가져옵니다. 이 코드는 자리 표시자 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
)
```
Important

인증에 UPN(사용자 계정 이름)만 사용할 수 있으며 서비스 주체는 지원되지 않습니다.
액세스 토큰을 사용하여 postToken 메시지를 게시합니다. 이 코드는 자리 표시자 CODE-2를 대체합니다.
```
     iframeWindow.postMessage({
         "type": "postToken",
         "message": // the access token your obtained earlier
         "scope": // event.data.scope as passed to the "getToken" message
     }, '*');
   }
```
Important

호스팅 창은 업데이트된 토큰이 포함된 새 postToken 메시지를 전송하여 만료 전에 토큰 을 새로 고쳐야 합니다. 그렇지 않으면 토큰이 만료되면 서비스 호출이 실패합니다.

팁

샘플 프로젝트에서 인증을 사용하는 애플리케이션을 볼 수 있습니다.

대시보드 포함

대시보드를 포함하려면 호스트의 Microsoft Entra 앱과 Azure Data Explorer 대시보드 서비스(RTD 메타데이터 서비스) 간에 트러스트 관계를 설정해야 합니다.

SPA(단일 페이지 애플리케이션) 인증 수행의 단계를 따릅니다.
Azure Portal을 열고 올바른 테넌트에 로그인했는지 확인합니다. 오른쪽 위 모서리에서 포털에 로그인하는 데 사용되는 ID를 확인합니다.
리소스 창에서 Microsoft Entra ID>앱 등록 선택합니다.
대신 흐름을 사용하는 앱을 찾아 엽니다.
매니페스트를 선택합니다.
requiredResourceAccess를 선택합니다.
매니페스트에서 다음 항목을 추가합니다.
```
  {
    "resourceAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
```
- 00001111-aaaa-2222-bbbb-3333cccc4444 는 Azure Data Explorer 대시보드 서비스의 애플리케이션 ID입니다.
- 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c 는 user_impersonation 권한입니다.
매니페스트에서 변경 내용을 저장합니다.
API 권한을 선택하고 RTD 메타데이터 서비스라는 새 항목이 있는지 확인합니다.
Microsoft Graph에서 , User.ReadBasic.All및 Group.Read.All.에 대한 People.Read권한을 추가합니다.
Azure PowerShell에서 앱에 대해 다음과 같은 새 서비스 주체를 추가합니다.
```
New-MgServicePrincipal -AppId 00001111-aaaa-2222-bbbb-3333cccc4444
```
오류가 발생하면 Request_MultipleObjectsWithSameKeyValue 앱이 성공적으로 추가되었음을 나타내는 테넌트에 이미 있음을 의미합니다.
API 권한 페이지에서 관리자 동의 부여를 선택하여 모든 사용자에 대해 동의합니다.

참고 항목

쿼리 영역 없이 대시보드를 포함하려면 다음 설정을 사용합니다.

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

위치 [feature-flags] :

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

기능 플래그

Important

f-IFrameAuth=true iframe이 작동하려면 플래그가 필요합니다. 다른 플래그는 선택 사항입니다.

호스팅 앱은 사용자 환경의 특정 측면을 제어할 수 있습니다. 예를 들어 연결 창을 숨기거나 다른 클러스터에 대한 연결을 사용하지 않도록 설정합니다. 이 시나리오의 경우 웹 탐색기는 기능 플래그를 지원합니다.

URL에서 기능 플래그를 쿼리 매개 변수로 사용할 수 있습니다. 다른 클러스터 추가를 사용하지 않도록 설정하려면 호스팅 앱에서 사용합니다 https://dataexplorer.azure.com/?f-ShowConnectionButtons=false .

setting	설명	기본값
f-ShowShareMenu	공유 메뉴 항목 표시	true
f-ShowConnectionButtons	연결 추가 단추를 표시하여 새 클러스터 추가	true
f-ShowOpenNewWindowButton	새 브라우저 창을 열고 범위에서 올바른 클러스터 및 데이터베이스를 https://dataexplorer.azure.com 가리키는 웹 UI에서 열기 단추 표시	false
f-ShowFileMenu	파일 메뉴 표시(다운로드, 탭, 콘텐츠 등)	true
f-ShowToS	설정 대화 상자에서 Azure Data Explorer 서비스 약관에 대한 링크 표시	true
f-ShowPersona	설정 메뉴의 오른쪽 위 모서리에 사용자 이름을 표시합니다.	true
f-UseMeControl	사용자의 계정 정보 표시	true
f-IFrameAuth	true이면 웹 탐색기는 iframe이 인증을 처리하고 메시지를 통해 토큰을 제공할 것으로 예상합니다. 이 매개 변수는 iframe 시나리오에 필요합니다.	false
f-PersistAfterEachRun	일반적으로 브라우저는 언로드 이벤트에서 유지됩니다. 그러나 iframe에서 호스팅할 때 언로드 이벤트가 항상 트리거되는 것은 아닙니다. 이 플래그는 각 쿼리가 실행된 후 지속되는 로컬 상태 이벤트를 트리거합니다. 이렇게 하면 발생할 수 있는 모든 데이터 손실이 실행되지 않은 새 쿼리 텍스트에만 영향을 미치도록 제한됩니다.	false
f-ShowSmoothIngestion	true이면 데이터베이스를 마우스 오른쪽 단추로 클릭할 때 수집 마법사 환경을 표시합니다.	true
f-RefreshConnection	true이면 페이지를 로드할 때 항상 스키마를 새로 고치고 로컬 스토리지에 의존하지 않습니다.	false
f-ShowPageHeader	true이면 Azure Data Explorer 제목 및 설정이 포함된 페이지 헤더를 표시합니다.	true
f-HideConnectionPane	true이면 왼쪽 연결 창이 표시되지 않습니다.	false
f-SkipMonacoFocusOnInit	iframe에서 호스팅할 때의 포커스 문제 해결	false
f-홈페이지	홈페이지를 사용하도록 설정하고 새 사용자를 해당 홈페이지로 다시 라우팅	true
f-ShowNavigation	true이면 왼쪽에 탐색 창이 표시됩니다.	true
f-DisableDashboardTopBar	true이면 대시보드의 위쪽 막대를 숨깁니다.	false
f-DisableNewDashboard	true이면 새 대시보드를 추가하는 옵션을 숨깁니다.	false
f-DisableNewDashboard	true이면 대시보드 목록에서 검색하는 옵션을 숨깁니다.	false
f-DisableDashboardEditMenu	true이면 대시보드 편집 옵션을 숨깁니다.	false
f-DisableDashboardFileMenu	true이면 대시보드에서 파일 메뉴 단추를 숨깁니다.	false
f-DisableDashboardShareMenu	true이면 대시보드에서 공유 메뉴 단추를 숨깁니다.	false
f-DisableDashboardDelete	true이면 대시보드 삭제 단추를 숨깁니다.	false
f-DisableTileRefresh	true이면 대시보드에서 타일 새로 고침 단추를 사용하지 않도록 설정합니다.	false
f-DisableDashboardAutoRefresh	true이면 대시보드에서 타일 자동 새로 고침을 사용하지 않도록 설정합니다.	false
f-DisableExploreQuery	true이면 타일의 쿼리 탐색 단추를 사용하지 않도록 설정합니다.	false
f-DisableCrossFiltering	true이면 대시보드에서 교차 필터링 기능을 사용하지 않도록 설정합니다.	false
f-HideDashboardParametersBar	true이면 대시보드에서 매개 변수 막대를 숨깁니다.	false

다음을 통해 공유

iframe에 Azure Data Explorer 웹 UI 포함

iframe에 웹 UI를 포함하는 방법

인증 처리

대시보드 포함

기능 플래그

피드백

추가 리소스

다음을 통해 공유

iframe에 Azure Data Explorer 웹 UI 포함

iframe에 웹 UI를 포함하는 방법

인증 처리

대시보드 포함

기능 플래그

관련 콘텐츠

피드백

추가 리소스