9 - Apache Superset Embedded SDK 소개

Apache Superset Embedded SDK는 Superset 대시보드를 외부 애플리케이션에 임베드할 수 있게 해주는 도구입니다. 이를 통해 사용자는 자신의 애플리케이션 내에서 Superset의 강력한 시각화 및 분석 기능을 활용할 수 있습니다.

Embedded SDK의 주요 기능

Embedded SDK를 사용하면 다음과 같은 작업을 수행할 수 있습니다:

1. 대시보드 임베딩: Superset 대시보드를 외부 애플리케이션에 삽입
2. 인증 관리: 게스트 토큰을 통한 인증 처리
3. UI 커스터마이징: 대시보드 UI 요소 표시/숨김 설정
4. 필터 관리: 임베디드 대시보드의 필터 설정 제어

사용 방법

1. 설치

npm을 사용하여 SDK를 설치합니다:

npm install --save @superset-ui/embedded-sdk

또는 CDN을 통해 로드할 수도 있습니다:

<script src="https://unpkg.com/@superset-ui/embedded-sdk"></script>

2. 기본 사용법

import { embedDashboard } from "@superset-ui/embedded-sdk";

embedDashboard({
  id: "abc123", // Superset 임베딩 UI에서 제공하는 ID
  supersetDomain: "https://superset.example.com",
  mountPoint: document.getElementById("my-superset-container"), // iframe을 포함할 수 있는 HTML 요소
  fetchGuestToken: () => fetchGuestTokenFromBackend(),
  dashboardUiConfig: { // 대시보드 UI 구성
      hideTitle: true,
      hideTab: true,
      hideChartControls: true,
      filters: {
          visible: false,
          expanded: false,
      },
      urlParams: {
          foo: 'value1',
          bar: 'value2',
      }
  },
  // 선택적 추가 iframe 샌드박스 속성
  iframeSandboxExtras: ['allow-top-navigation', 'allow-popups-to-escape-sandbox'],
  // 선택적 referrerPolicy 설정
  referrerPolicy: "same-origin"
});

CDN을 사용하는 경우:

<script>
  supersetEmbeddedSdk.embedDashboard({
    // 위와 동일한 파라미터
  });
</script>

Superset Embedded SDK

3. 게스트 토큰 생성

임베디드 리소스는 게스트 토큰을 사용하여 사용자에게 Superset 접근 권한을 부여합니다. 백엔드에서 다음과 같이 게스트 토큰을 생성해야 합니다:

// POST /security/guest_token 요청 페이로드 예시
{
  "user": {
    "username": "embedded_user",
    "first_name": "Embedded",
    "last_name": "User"
  },
  "resources": [{
    "type": "dashboard",
    "id": "abc123"
  }],
  "rls": [
    { "clause": "publisher = 'Nintendo'" }
  ]
}

Authentication/Authorization with Guest Tokens

실제 구현 예시

React 애플리케이션에서의 구현 예시:

"use client";

import React, { useEffect } from "react";
import axios from "axios";
import { embedDashboard } from "@superset-ui/embedded-sdk";

const supersetUrl = "http://localhost:8088/";
const supersetApiUrl = `${supersetUrl}/api/v1/security`;
const dashboardId = "af70a229-7d8e-4917-8ce3-795ca257fa85";

const DashboardPage = () => {
  useEffect(() => {
    async function getToken() {
      try {
        // 1. 로그인하여 액세스 토큰 획득
        const loginBody = {
          password: "admin",
          provider: "db",
          refresh: true,
          username: "admin",
        };
        const { data } = await axios.post(
          `${supersetApiUrl}/login`,
          loginBody,
          { headers: { "Content-Type": "application/json" }, withCredentials: true, }
        );
        const accessToken = data.access_token;

        // 2. 게스트 토큰 획득
        const guestTokenBody = JSON.stringify({
          resources: [{ type: "dashboard", id: dashboardId }],
          rls: [{"clause": "customer_id=4"}],
          user: { username: "guest", first_name: "Guest", last_name: "User" },
        });

        const guestTokenResponse = await axios.post(
          `${supersetApiUrl}/guest_token/`,
          guestTokenBody,
          { headers: { "Content-Type": "application/json", Authorization: `Bearer ${accessToken}` }, withCredentials: true, }
        );
        const guestToken = guestTokenResponse.data.token;

        // 3. 대시보드 임베드
        const mountPoint = document.getElementById("superset-container");
        if (!mountPoint) {
          console.error("Error: mountPoint is null.");
          return;
        }

        embedDashboard({
          id: dashboardId,
          supersetDomain: supersetUrl,
          mountPoint,
          fetchGuestToken: () => guestToken,
          dashboardUiConfig: {
            filters: { expanded: true },
            urlParams: { standalone: 3 },
          },
        });

        // 4. iframe 스타일 조정
        setTimeout(() => {
          const iframe = document.querySelector("iframe");
          if (iframe) {
            iframe.style.width = "100%";
            iframe.style.minHeight = "100vh";
          }
        }, 1000);
      } catch (error) {
        console.error("Error fetching token:", error);
      }
    }

    getToken();
  }, []);

  return <div id="superset-container"></div>;
};

export default DashboardPage;

주의사항 및 알려진 문제점

1. 필터 표시 문제: hideChartControls: true로 설정하면 적용된 필터가 차트에 표시되지 않는 문제가 있습니다. GitHub Issue #30374

2. 대시보드 UI 구성 옵션 무시: 일부 dashboardUiConfig 옵션이 무시되는 문제가 보고되었습니다. GitHub Issue #30630

3. 긴 대시보드 PDF 다운로드 문제: 긴 대시보드를 PDF로 다운로드할 때 뷰포트 밖의 차트가 로딩 이미지로 표시되는 문제가 있습니다. 이 문제는 DASHBOARD_VIRTUALIZATION: False 설정으로 해결할 수 있습니다. GitHub Issue #29719

4. 보안 경고: 일부 사용자는 Chrome에서 임베디드 대시보드가 악성으로 표시되는 문제를 보고했습니다. GitHub Issue #32177

Superset Embedded SDK를 사용하기 위해서는 Superset 서버에서 EMBEDDED_SUPERSET 기능 플래그를 활성화하고, GUEST_TOKEN_JWT_SECRET 구성 변수에 강력한 비밀번호를 설정해야 합니다.