Ajouter des actions de rappel intégrées lors de l'exécution sur Amazon QuickSight

Utilisez des actions de rappel de points de données intégrées pour renforcer les intégrations entre votre application SaaS (logiciel en tant que service) et vos tableaux de bord et visuels Amazon QuickSight intégrés. Les développeurs peuvent enregistrer des points de données à rappeler avec le SDK d' QuickSight intégration. Lorsque vous enregistrez une action de rappel pour une représentation visuelle, les lecteurs peuvent sélectionner un point de données sur la représentation visuelle pour recevoir un rappel fournissant des données spécifiques au point de données sélectionné. Ces informations peuvent être utilisées pour signaler des enregistrements clés, compiler des données brutes spécifiques au point de données, capturer des enregistrements et compiler des données pour les processus backend.

Les rappels intégrés ne sont pas pris en charge pour le contenu visuel personnalisé, les zones de texte ou les informations.

Avant de commencer à enregistrer des points de données pour le rappel, mettez à jour le kit SDK d'intégration vers la version 2.3.0. Pour plus d'informations sur l'utilisation du SDK d' QuickSight intégration, consultez le amazon-quicksight-embedding-sdk GitHub

Un rappel de point de données peut être enregistré sur un ou plusieurs visuels lors de l'exécution via le SDK. QuickSight Vous pouvez également enregistrer un rappel de point de données pour toute interaction prise en charge par la structure de l'VisualCustomActionAPI. Cela permet au rappel du point de données de démarrer lorsque l'utilisateur sélectionne le point de données sur la représentation visuelle ou lorsque le point de données est sélectionné dans le menu contextuel du point de données. L'exemple suivant enregistre un rappel de point de données lancé par le lecteur lorsqu'il sélectionne un point de données sur la représentation visuelle.

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

Vous pouvez également configurer l'exemple précédent pour lancer le rappel du point de données lorsque l'utilisateur ouvre le menu contextuel. Pour faire cela à l'aide de l'exemple précédent, définissez la valeur de actionTrigger sur ActionTrigger.DATA_POINT_MENU.

Une fois qu'un rappel de point de données est enregistré, il est appliqué à la plupart des points de données sur la ou les représentations visuelles spécifiées. Les rappels ne s'appliquent pas aux totaux ou aux sous-totaux des représentations visuelles. Lorsqu'un lecteur interagit avec un point de données, un CALLBACK_OPERATION_INVOKED message est envoyé au SDK d'intégration. QuickSight Ce message est capturé par le gestionnaire onMessage. Le message contient des valeurs brutes et afficher des valeurs pour la ligne complète de données associée au point de données sélectionné. Il contient également les métadonnées de colonne pour toutes les colonnes de la représentation visuelle dans laquelle le point de données est contenu. Voici un exemple de message 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"
                                }
                            }
                        }
                    }
            ]
        }
   ]
}