Adição de ações de retorno de chamada incorporadas no runtime no Amazon QuickSight - Amazon QuickSight

Adição de ações de retorno de chamada incorporadas no runtime no Amazon QuickSight

Use ações de retorno de chamada do ponto de dados incorporado para criar integrações mais estreitas entre a aplicação de software como serviço (SaaS) e os painéis e elementos visuais incorporados do Amazon QuickSight. Os desenvolvedores podem registrar pontos de dados para terem um retorno de chamada com o SDK de incorporação do QuickSight. Quando você registra uma ação de retorno de chamada para um elemento visual, os leitores podem selecionar um ponto de dados no elemento visual para receber um retorno de chamada que forneça dados específicos ao ponto de dados selecionado. Essas informações podem ser usadas para sinalizar registros fundamentais, compilar dados brutos específicos para o ponto de dados, capturar registros e compilar dados para processos de back-end.

Os retornos de chamadas incorporados não são compatíveis com o conteúdo de elementos visuais personalizados, caixas de texto ou insights.

Antes de começar a registrar pontos de dados para o retorno de chamada, atualize o SDK de incorporação para a versão 2.3.0. Para obter mais informações sobre como usar o SDK de incorporação do QuickSight, consulte amazon-quicksight-embedding-sdk no GitHub.

Um retorno de chamada do ponto de dados pode ser registrado em um ou mais elementos visuais no runtime por meio do SDK do QuickSight. Você também pode registrar um retorno de chamada do ponto de dados para qualquer interação compatível com a estrutura de API VisualCustomAction. Isso permite que o retorno de chamada do ponto de dados seja iniciado quando o usuário seleciona o ponto de dados no elemento visual ou quando o ponto de dados é selecionado usando o menu de contexto do ponto de dados. O exemplo apresentado a seguir registra um retorno de chamada do ponto de dados que o leitor inicia ao selecionar um ponto de dados no elemento 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);

Você também pode configurar o exemplo anterior para iniciar o retorno de chamada do ponto de dados quando o usuário abrir o menu de contexto. Para fazer isso com o exemplo anterior, defina o valor de actionTrigger como ActionTrigger.DATA_POINT_MENU.

Depois que um retorno de chamada do ponto de dados é registrado, ele é aplicado à maioria dos pontos de dados no elemento visual ou aos elementos visuais especificados. Os retornos de chamada não se aplicam a totais ou subtotais em elementos visuais. Quando um leitor interage com um ponto de dados, uma mensagem CALLBACK_OPERATION_INVOKED é emitida para o SDK de incorporação do QuickSight. Esta mensagem é capturada pelo manipulador onMessage. A mensagem contém os valores brutos e de exibição para a linha completa de dados associada ao ponto de dados selecionado. Além disso, ela contém os metadados de coluna para todas as colunas do elemento visual em que o ponto de dados está contido. Veja a seguir um exemplo de uma mensagem 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"
                                }
                            }
                        }
                    }
            ]
        }
   ]
}