Menambahkan tindakan panggilan balik yang disematkan saat runtime di Amazon QuickSight

Gunakan tindakan callback titik data tertanam untuk membangun integrasi yang lebih erat antara aplikasi perangkat lunak sebagai layanan (SaaS) dan dasbor serta visual tertanam Amazon Anda. QuickSight Pengembang dapat mendaftarkan titik data untuk dipanggil kembali dengan penyematan. QuickSight SDK Saat Anda mendaftarkan tindakan callback untuk visual, pembaca dapat memilih titik data pada visual untuk menerima panggilan balik yang menyediakan data spesifik ke titik data yang dipilih. Informasi ini dapat digunakan untuk menandai catatan kunci, mengkompilasi data mentah khusus untuk titik data, menangkap catatan, dan mengkompilasi data untuk proses backend.

Panggilan balik yang disematkan tidak didukung untuk konten visual kustom, kotak teks, atau wawasan.

Sebelum Anda mulai mendaftarkan titik data untuk callback, perbarui Embedding SDK ke versi 2.3.0. Untuk informasi selengkapnya tentang penggunaan QuickSight EmbeddingSDK, lihat amazon-quicksight-embedding-sdkpada GitHub.

Callback titik data dapat didaftarkan ke satu atau lebih visual saat runtime melalui file. QuickSight SDK Anda juga dapat mendaftarkan callback titik data ke interaksi apa pun yang didukung oleh struktur. VisualCustomActionAPI Hal ini memungkinkan callback titik data untuk memulai ketika pengguna memilih titik data pada visual atau ketika titik data dipilih dari menu konteks titik data. Contoh berikut mendaftarkan callback titik data yang dimulai pembaca ketika mereka memilih titik data pada visual.

/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);

Anda juga dapat mengonfigurasi contoh sebelumnya untuk memulai callback titik data saat pengguna membuka menu konteks. Untuk melakukan ini dengan contoh sebelumnya, tetapkan nilai to. actionTrigger ActionTrigger.DATA_POINT_MENU

Setelah callback titik data terdaftar, itu diterapkan ke sebagian besar titik data pada visual atau visual yang ditentukan. Callback tidak berlaku untuk total atau subtotal pada visual. Saat pembaca berinteraksi dengan titik data, CALLBACK_OPERATION_INVOKED pesan dipancarkan ke penyematan. QuickSight SDK Pesan ini ditangkap oleh onMessage handler. Pesan berisi nilai mentah dan tampilan untuk baris penuh data yang terkait dengan titik data yang dipilih. Ini juga berisi metadata kolom untuk semua kolom dalam visual tempat titik data terkandung di dalamnya. Berikut ini adalah contoh CALLBACK_OPERATION_INVOKED pesan.

{
   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"
                                }
                            }
                        }
                    }
            ]
        }
   ]
}