Amazon QuickSight에서 런타임 시 임베디드 콜백 작업 추가 - Amazon QuickSight

Amazon QuickSight에서 런타임 시 임베디드 콜백 작업 추가

임베디드 데이터 포인트 콜백 작업을 사용하여 서비스형 소프트웨어(SaaS) 애플리케이션과 Amazon QuickSight 임베디드 대시보드 및 시각적 객체를 더욱 긴밀하게 통합할 수 있습니다. 개발자는 QuickSight 임베딩 SDK를 사용하여 콜백할 데이터 포인트를 등록할 수 있습니다. 시각적 객체에 대한 콜백 작업을 등록하면, 독자는 시각적 객체에서 데이터 포인트를 선택하여 선택한 데이터 포인트와 관련된 데이터를 제공하는 콜백을 수신할 수 있습니다. 이 정보를 사용하여 주요 레코드에 플래그를 지정하고, 데이터 포인트와 관련된 원시 데이터를 컴파일하고, 레코드를 캡처하고, 백엔드 프로세스용 데이터를 컴파일할 수 있습니다.

사용자 지정 시각적 콘텐츠, 텍스트 상자 또는 인사이트에는 임베디드 콜백이 지원되지 않습니다.

콜백에 데이터 포인트를 등록하기 전에 Embedding SDK를 버전 2.3.0으로 업데이트하세요. QuickSight 임베딩 SDK 사용에 대한 자세한 내용은 GitHub의 amazon-quicksight-embedding-sdk를 참조하세요.

QuickSight SDK를 통해 런타임에 하나 이상의 시각적 객체에 데이터 포인트 콜백을 등록할 수 있습니다. 또한 VisualCustomAction API 구조에서 지원하는 모든 상호 작용에 데이터 포인트 콜백을 등록할 수 있습니다. 이렇게 하면 사용자가 시각적 객체에서 데이터 포인트를 선택하거나 데이터 포인트 컨텍스트 메뉴에서 데이터 포인트를 선택할 때 데이터 포인트 콜백이 시작될 수 있습니다. 다음 예제는 독자가 시각적 객체에서 데이터 포인트를 선택할 때 시작하는 데이터 포인트 콜백을 등록합니다.

/const MY_GET_EMBED_URL_ENDPOINT =
  "https://my.api.endpoint.domain/MyGetEmbedUrlApi"; // Sample URL

// The dashboard id to embed
const MY_DASHBOARD_ID = "my-dashboard"; // Sample ID

// The container element in your page that will have the embedded dashboard
const MY_DASHBOARD_CONTAINER = "#experience-container"; // Sample ID

// SOME HELPERS

const ActionTrigger = {
  DATA_POINT_CLICK: "DATA_POINT_CLICK",
  DATA_POINT_MENU: "DATA_POINT_MENU",
};

const ActionStatus = {
  ENABLED: "ENABLED",
  DISABLED: "DISABLED",
};

// This function makes a request to your endpoint to obtain an embed url for a given dashboard id
// The example implementation below assumes the endpoint takes dashboardId as request data
// and returns an object with EmbedUrl property
const myGetEmbedUrl = async (dashboardId) => {
  const apiOptions = {
    dashboardId,
  };
  const apiUrl = new URL(MY_GET_EMBED_URL_ENDPOINT);
  apiUrl.search = new URLSearchParams(apiOptions).toString();
  const apiResponse = await fetch(apiUrl.toString());
  const apiResponseData = await apiResponse.json();
  return apiResponseData.EmbedUrl;
};

// This function constructs a custom action object
const myConstructCustomActionModel = (
  customActionId,
  actionName,
  actionTrigger,
  actionStatus
) => {
  return {
    Name: actionName,
    CustomActionId: customActionId,
    Status: actionStatus,
    Trigger: actionTrigger,
    ActionOperations: [
      {
        CallbackOperation: {
          EmbeddingMessage: {},
        },
      },
    ],
  };
};

// This function adds a custom action on the first visual of first sheet of the embedded dashboard
const myAddVisualActionOnFirstVisualOfFirstSheet = async (
  embeddedDashboard
) => {
  // 1. List the sheets on the dashboard
  const { SheetId } = (await embeddedDashboard.getSheets())[0];
  // If you'd like to add action on the current sheet instead, you can use getSelectedSheetId method
  // const SheetId = await embeddedDashboard.getSelectedSheetId();

  // 2. List the visuals on the specified sheet
  const { VisualId } = (await embeddedDashboard.getSheetVisuals(SheetId))[0];

  // 3. Add the custom action to the visual
  try {
    const customActionId = "custom_action_id"; // Sample ID
    const actionName = "Flag record"; // Sample name
    const actionTrigger = ActionTrigger.DATA_POINT_CLICK; // or ActionTrigger.DATA_POINT_MENU
    const actionStatus = ActionStatus.ENABLED;
    const myCustomAction = myConstructCustomActionModel(
      customActionId,
      actionName,
      actionTrigger,
      actionStatus
    );
    const response = await embeddedDashboard.addVisualActions(
      SheetId,
      VisualId,
      [myCustomAction]
    );
    if (!response.success) {
      console.log("Adding visual action failed", response.errorCode);
    }
  } catch (error) {
    console.log("Adding visual action failed", error);
  }
};

const parseDatapoint = (visualId, datapoint) => {
  datapoint.Columns.forEach((Column, index) => {
    // FIELD | METRIC
    const columnType = Object.keys(Column)[0];

    // STRING | DATE | INTEGER | DECIMAL
    const valueType = Object.keys(Column[columnType])[0];
    const { Column: columnMetadata } = Column[columnType][valueType];

    const value = datapoint.RawValues[index][valueType];
    const formattedValue = datapoint.FormattedValues[index];

    console.log(
      `Column: ${columnMetadata.ColumnName} has a raw value of ${value}
           and formatted value of ${formattedValue.Value} for visual: ${visualId}`
    );
  });
};

// This function is used to start a custom workflow after the end user selects a datapoint
const myCustomDatapointCallbackWorkflow = (callbackData) => {
  const { VisualId, Datapoints } = callbackData;

  parseDatapoint(VisualId, Datapoints);
};

// EMBEDDING THE DASHBOARD

const main = async () => {
  // 1. Get embed url
  let url;
  try {
    url = await myGetEmbedUrl(MY_DASHBOARD_ID);
  } catch (error) {
    console.log("Obtaining an embed url failed");
  }

  if (!url) {
    return;
  }

  // 2. Create embedding context
  const embeddingContext = await createEmbeddingContext();

  // 3. Embed the dashboard
  const embeddedDashboard = await embeddingContext.embedDashboard(
    {
      url,
      container: MY_DASHBOARD_CONTAINER,
      width: "1200px",
      height: "300px",
      resizeHeightOnSizeChangedEvent: true,
    },
    {
      onMessage: async (messageEvent) => {
        const { eventName, message } = messageEvent;
        switch (eventName) {
          case "CONTENT_LOADED": {
            await myAddVisualActionOnFirstVisualOfFirstSheet(embeddedDashboard);
            break;
          }
          case "CALLBACK_OPERATION_INVOKED": {
            myCustomDatapointCallbackWorkflow(message);
            break;
          }
        }
      },
    }
  );
};

main().catch(console.error);

사용자가 컨텍스트 메뉴를 열 때 데이터포인트 콜백을 시작하도록 위 예제를 구성할 수도 있습니다. 위 예제에서 이 작업을 수행하려면 actionTrigger의 값을 ActionTrigger.DATA_POINT_MENU(으)로 설정합니다.

데이터포인트 콜백이 등록되면, 지정된 시각적 객체나 시각적 객체의 대부분의 데이터포인트에 적용됩니다. 콜백은 시각적 객체의 합계 또는 소계에는 적용되지 않습니다. 리더가 데이터 포인트와 상호 작용하면, QuickSight 임베딩 SDK로 CALLBACK_OPERATION_INVOKED 메시지가 전송됩니다. 이 메시지는 onMessage 핸들러에 의해 캡처됩니다. 메시지에는 선택한 데이터 포인트와 관련된 전체 데이터 행의 원시 및 표시 값이 포함됩니다. 또한 데이터 포인트가 포함된 시각적 객체의 모든 열에 대한 열 메타데이터도 포함됩니다. 다음은 CALLBACK_OPERATION_INVOKED 메시지의 예입니다.

{
   CustomActionId: "custom_action_id",
   DashboardId: "dashboard_id",
   SheetId: "sheet_id",
   VisualId: "visual_id",
   DataPoints: [
        {
            RawValues: [
                    {
                        String: "Texas" // 1st raw value in row
                    },
                    {
                        Integer: 1000 // 2nd raw value in row
                    }
            ],
            FormattedValues: [
                    {Value: "Texas"}, // 1st formatted value in row
                    {Value: "1,000"} // 2nd formatted value in row
            ],
            Columns: [
                    { // 1st column metadata
                        Dimension: {
                            String: {
                                Column: {
                                    ColumnName: "State",
                                    DatsetIdentifier: "..."
                                }
                            }
                        }
                    },
                    { // 2nd column metadata
                        Measure: {
                            Integer: {
                                Column: {
                                    ColumnName: "Cancelled",
                                    DatsetIdentifier: "..."
                                },
                                AggregationFunction: {
                                    SimpleNumericalAggregation: "SUM"
                                }
                            }
                        }
                    }
            ]
        }
   ]
}