本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 亚马逊 Quick Sight 的嵌入式分析
<a name="embedded-analytics"></a>

**重要**  
Amazon Quick Sight 推出了用于嵌入分析的新 API 操作：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` API 操作来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关使用旧 API 操作进行嵌入的更多信息，请参阅 [使用 GetDashboardEmbedURL 和 GetSessionEmbedURL API 操作嵌入分析](embedded-analytics-deprecated.md)。


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

借助 Amazon Quick Sight 嵌入式分析，您可以将数据驱动的体验无缝集成到您的软件应用程序中。您可以设计嵌入式组件的样式，让其匹配自己的品牌。此功能将 Amazon Quick Sight 的强大功能带给您的最终用户，他们无需离开应用程序即可分析数据并与之交互。通过降低认知复杂性来改善用户体验，让用户有更好的机会进行深入理解并提高效率。

Amazon Quick Sight 支持嵌入以下元素：
+ Amazon Quick Sight 控制台（为注册用户提供完整的创作体验）
+ Amazon Quick Sight 控制面板和视觉效果（适用于注册用户、匿名用户、公共最终用户）
+ Amazon Quick Sight Q 搜索栏（适用于注册用户和匿名用户）

使用嵌入式 Amazon Quick Sight 控制台，你可以嵌入完整的 Amazon Quick Sight 体验。这样就可以将 Amazon Quick Sight 创作工具用作应用程序的一部分，而不是在 AWS 管理控制台 或独立网站的环境中使用。嵌入式 Amazon Quick Sight 控制台的用户需要在你的 AWS 账户游戏中注册为 Amazon Quick Sight 的作者或管理员。他们还需要使用任何 Amazon Qu AWS 账户 ick Sight 支持的身份验证方法进行身份验证。

借助嵌入式 Amazon Quick Sight 控制面板或视觉效果，读者可以获得与发布的控制面板或视觉效果相同的功能和交互性。要使用嵌入式控制面板或视觉对象，读者（查看者）可以为下列任何身份：
+ Amazon Quick Sight 用户 AWS 账户 通过亚马逊 Quick Sight 支持的任何方法在你的账户中进行身份验证。
+ 未经身份验证的网站或应用程序访问者 – 此选项需要具有容量定价的会话包。有关订阅类型的信息，请参阅[了解 Amazon Quick Sight 订阅和角色](https://docs.aws.amazon.com/quicksight/latest/user/user-types.html#subscription-role-mapping)。
+ 通过编程访问方式在监视器或大屏幕上查看显示内容的多个最终用户。

如果您的应用程序也位于中 AWS，则该应用程序无需与 Amazon Quick Sight 订阅位于同一 AWS 账户 位置。但是，该应用程序需要能够代入您用于 API 调用的 AWS Identity and Access Management (IAM) 角色。

在嵌入内容之前，请确保在计划使用嵌入 AWS 账户 的地方使用了 Amazon Quick Sight Enterprise 版。

所有支持的版本都提供了 Amazon Quick Sight 嵌入 AWS 区域功能。

**Topics**
+ [

# 将 Amazon Quick Sight 分析嵌入您的应用程序中
](embedding-overview.md)
+ [

# 将自定义 Amazon Quick Sight 资产嵌入您的应用程序中
](customize-and-personalize-embedded-analytics.md)
+ [

# 使用一键嵌入代码嵌入 Amazon Quick Sight 视觉效果和仪表板
](1-click-embedding.md)
+ [

# 嵌入 Amazon Quick Sight APIs
](embedded-analytics-api.md)

# 将 Amazon Quick Sight 分析嵌入您的应用程序中
<a name="embedding-overview"></a>


|  | 
| --- |
|  适用于：企业版  | 

要嵌入分析，您可以运行 Amazon Quick Sight 嵌入 API 来生成嵌入代码。或者，对于控制面板，您可以在 Amazon Quick Sight 中共享控制面板时复制嵌入代码。每个选项如下所述。

## 注册用户一键式嵌入
<a name="embedding-overview-1-click"></a>

在与账户中的注册用户共享控制面板时，您可以复制控制面板的嵌入代码并将其粘贴到内部应用程序的 HTML 中。

当您想要将 Amazon Quick Sight 控制面板嵌入到用户需要进行身份验证的内部应用程序中时，最好使用一键式企业嵌入。复制嵌入代码时，您会获得一个不变的静态嵌入代码。

有关更多信息，请参阅 [通过一键嵌入代码为注册用户嵌入 Amazon Quick Sight 视觉效果和控制面板](embedded-analytics-1-click.md)。

## 嵌入 Amazon Quick Sight APIs
<a name="embedding-overview-api"></a>

当你想将 Amazon Quick Sight 体验嵌入到用户必须进行身份验证的内部应用程序或任何人都可以访问的外部应用程序中时，最适合嵌入 Amazon Quick Sight API。使用嵌入 API 操作生成嵌入代码时，您会获得一个一次性代码。

有关更多信息，请参阅 [嵌入 Amazon Quick Sight APIs](embedded-analytics-api.md)。

# 将自定义 Amazon Quick Sight 资产嵌入您的应用程序中
<a name="customize-and-personalize-embedded-analytics"></a>

您可以使用 Amazon Quick Sight 嵌入式分析将自定义 Amazon Quick Sight 资产嵌入到您的应用程序中，这些资产专为满足您的业务需求而量身定制。对于嵌入式仪表板和视觉对象，Amazon Quick Sight 作者可以添加筛选器和向下钻取，供读者在浏览仪表板或视觉对象时进行访问。Amazon Quick Sight 开发人员还可以使用 Amazon Quick Sight SDKs 在 SaaS 应用程序和 Amazon Quick Sight 嵌入式资产之间建立更紧密的集成，从而在运行时向仪表板上的视觉对象添加数据点回调操作。

有关 Amazon Quick Sight 的更多信息 SDKs，请参阅 `amazon-quicksight-embedding-sdk` on [GitHub](https://github.com/awslabs/amazon-quicksight-embedding-sdk)或 [NPM](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。

下面，您可以找到有关如何使用 Amazon Quick Sight SDKs 自定义 Amazon Quick Sight 嵌入式分析的说明。

**Topics**
+ [

# 在 Amazon Quick Sight 中添加运行时嵌入式回调操作
](embedding-custom-actions-callback.md)
+ [

# 在 Amazon Quick Sight 嵌入式控制面板和视觉对象的运行时筛选数据
](embedding-runtime-filtering.md)
+ [

# 自定义 Amazon Quick Sight 嵌入式仪表板和视觉效果的外观
](embedding-runtime-theming.md)
+ [

# 使用 Amazon Quick Sight Embedging SDK 启用指向嵌入式控制面板视图的可共享链接
](embedded-view-sharing.md)

# 在 Amazon Quick Sight 中添加运行时嵌入式回调操作
<a name="embedding-custom-actions-callback"></a>

使用嵌入式数据点回调操作在您的软件即服务 (SaaS) 应用程序与 Amazon Quick Sight 嵌入式仪表板和视觉对象之间建立更紧密的集成。开发人员可以使用 Amazon Quick Sight 嵌入式 SDK 注册要回调的数据点。当您为视觉对象注册回调操作时，读者可以在视觉对象上选择一个数据点，用来接收会针对所选数据点提供数据的回调。此信息可用于标记关键记录、编译针对数据点的原始数据、捕获记录以及为后端进程编译数据。

自定义视觉内容、文本框或见解不支持嵌入式回调。

在开始注册回调数据点之前，请将嵌入开发工具包更新到版本 2.3.0。有关使用 Amazon Quick Sight 嵌入软件开发工具包的更多信息，请参阅[amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)上的 GitHub。

数据点回调可以在运行时通过 Amazon Quick Sight SDK 注册到一个或多个视觉对象。您还可以向 [VisualCustomAction](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_VisualCustomAction.html)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`。

注册数据点回调后，就会应用到指定视觉对象上的大多数数据点。回调不适用于视觉对象的总计或小计。当读者与数据点交互时，会向 Amazon Quick S `CALLBACK_OPERATION_INVOKED` ight 嵌入式 SDK 发送一条消息。此消息由 `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"
                                }
                            }
                        }
                    }
            ]
        }
   ]
}
```

# 在 Amazon Quick Sight 嵌入式控制面板和视觉对象的运行时筛选数据
<a name="embedding-runtime-filtering"></a>

您可以在 Amazon Quick Sight 嵌入软件开发工具包中使用筛选方法，在运行时在软件即服务 (SaaS) 应用程序中利用 Amazon Quick Sight 筛选器的强大功能。运行时筛选器允许企业主将其应用程序与嵌入式 Amazon Quick Sight 仪表板和视觉效果集成。为此，请在应用程序中创建自定义筛选条件控件，并根据应用程序中的数据应用筛选条件预设。然后，开发人员可以在运行时为最终用户个性化筛选条件配置。

开发人员可以使用 Amazon Quick Sight Embedding SDK 在嵌入式控制面板上创建、查询、更新和移除 Amazon Quick Sight 筛选条件，或者从应用程序中移除视觉效果。使用[FilterGroup](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_FilterGroup.html)数据模型在您的应用程序中创建 Amazon Quick Sight 筛选对象，并使用筛选方法将其应用于嵌入式仪表板和视觉对象。有关使用 Amazon Quick Sight 嵌入软件开发工具包的更多信息，请参阅[amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)上的 GitHub。

**先决条件**

在开始之前，请确保您使用的是 Amazon Quick Sight Embedding SDK 版本 2.5.0 或更高版本。

## 术语和概念
<a name="runtime-filtering-terminology"></a>

使用嵌入式运行时筛选时，以下术语可能很有用。
+ *筛选条件组* – 一组单独的筛选条件。位于 `FilterGroup` 内的筛选条件彼此之间进行 OR 运算。中的筛选[FilterGroup](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_FilterGroup.html)器应用于相同的工作表或视觉对象。
+ *筛选条件* - 单个筛选条件。筛选条件可以是类别、数字或日期时间筛选条件类型。有关筛选条件的更多信息，请参阅[筛选条件](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_Filter.html)。

## 设置
<a name="runtime-filtering-setup"></a>

开始之前，请确保您已准备好以下资产和信息。
+ 您想要将 `FilterGroup` 范围限定到的工作表的工作表 ID。这可以通过 Embedding SDK 中的 `getSheets` 方法获取。
+ 您想要筛选的数据集和数据集的列标识符。这可以通过 [DescribeDashboardDefinition](https://docs.aws.amazon.com/APIReference/API_DescribeDashboardDefinition.html)API 操作获得。

  根据您使用的列类型，可以添加到嵌入式资产的筛选条件类型可能会受到限制。有关筛选条件限制的更多信息，请参阅 [Filter](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_Filter.html)。
+ 如果适用，则为要将 `FilterGroup` 范围限定到的视觉对象的视觉对象 ID。这可以使用 Embedding SDK 中的 `getSheetVisuals` 方法获取。

  除了 `getSheetVisuals` 方法之外，您添加的 `FilterGroup` 只能限于当前选定的工作表。

要使用此功能，您必须已经通过 Amazon Quick Sight Embedding SDK 将仪表板或视觉效果嵌入到应用程序中。有关使用 Amazon Quick Sight 嵌入软件开发工具包的更多信息，请参阅[amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)上的 GitHub。

## SDK 方法接口
<a name="runtime-filtering-sdk-interface"></a>

**控制面板嵌入 getter 方法**

下表介绍了开发人员可以使用的不同控制面板嵌入 getter 方法。


| 方法 | 说明 | 
| --- | --- | 
|  `getFilterGroupsForSheet(sheetId: string) `  |  返回当前限 FilterGroups 定为参数中提供的表单的所有内容。  | 
|  `getFilterGroupsForVisual(sheetId: string, visualId: string)`  |  返回范围限定为参数中提供的视觉对象的所有 `FilterGroups`。  | 

如果参数中提供的工作表不是嵌入式控制面板中当前选定的工作表，则上述方法会返回错误。

**视觉对象嵌入 getter 方法**

下表介绍了开发人员可以使用的不同视觉对象嵌入 getter 方法。


| 方法 | 说明 | 
| --- | --- | 
|  `getFilterGroups()`  |  返回范围当前限定为嵌入式视觉对象的所有 `FilterGroups`。  | 

**Setter 方法**

下表介绍了开发人员可用于控制面板或视觉对象嵌入的不同 setter 方法。


| 方法 | 说明 | 
| --- | --- | 
|  `addFilterGroups(filterGroups: FilterGroup[])`  |  将提供的内容添加并应用**FilterGroups**到嵌入式仪表板或视觉对象。返回 `ResponseMessage` 指示添加是否成功。  | 
|  `updateFilterGroups(filterGroups: FilterGroup[])`  |  更新嵌入式体验上与参数中提供的 `FilterGroup` 包含相同 `FilterGroupId` 的 `FilterGroups`。返回 `ResponseMessage` 指示更新是否成功。  | 
|  `removeFilterGroups(filterGroupsOrIds: FilterGroup[] \| string[])`  |   FilterGroups 从仪表板中移除提供的内容，并返回 a，`ResponseMessage`表示删除尝试是否成功。  | 

提供的 `FilterGroup` 的范围必须限定于当前选定的嵌入式工作表或视觉对象。

# 自定义 Amazon Quick Sight 嵌入式仪表板和视觉效果的外观
<a name="embedding-runtime-theming"></a>

您可以使用 Amazon Quick Sight Embedding SDK（版本 2.5.0 及更高版本）在运行时更改嵌入式 Amazon Quick Sight 仪表板和视觉对象的主题。运行时主题可以更轻松地将软件即服务 (SaaS) 应用程序与 Amazon Quick Sight 嵌入式资产集成。运行时主题允许您将嵌入内容的主题与嵌入 Amazon Quick Sight 资产的父应用程序的主题同步。您还可以使用运行时主题为读者添加自定义选项。主题更改可以在初始化时应用于嵌入式资产，也可以在嵌入式控制面板或视觉对象的整个生命周期内应用。

有关主题的更多信息，请参阅 [使用 Amazon Quick Sight 中的主题](themes-in-quicksight.md)。有关使用 Amazon Quick Sight 嵌入软件开发工具包的更多信息，请参阅[amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)上的 GitHub。

**先决条件**

在开始之前，请确保您已满足以下先决条件。
+ 你使用的是 Amazon Quick Sight Embedding SDK 版本 2.5.0 或更高版本
+ 访问您想要使用的主题的权限。要在 Amazon Quick Sight 中授予主题的权限，请调用 `UpdateThemePermissions` API 或使用 Amazon Quick Sight 控制台分析编辑器中主题旁边的**共享**图标。

## 术语和概念
<a name="runtime-theming-terminology"></a>

使用嵌入式运行时主题时，以下术语可能很有用。
+ *主题* – 可应用于多个分析和控制面板的设置集合，可更改内容的显示方式。
+ *ThemeConfiguration*— 包含主题所有显示属性的配置对象。
+ *主题覆盖* - 应用于活动主题的 `ThemeConfiguration` 对象，用于覆盖内容显示方式的部分或全部方面。
+ *主题 ARN* — 标识亚马逊 Quick Sight 主题的亚马逊资源名称 (ARN)。以下是自定义主题 ARN 的示例。

  `arn:aws:quicksight:region:account-id:theme/theme-id`

  Amazon Quick Sight 提供的入门主题在其主题 ARN 中没有区域。以下是入门主题 ARN 的示例。

  `arn:aws:quicksight::aws:theme/CLASSIC`

## 设置
<a name="runtime-theming-setup"></a>

确保您已准备好以下信息，以开始使用运行时主题。
+ 您要使用的主题的主题。 ARNs 您可以选择现有主题，也可以创建一个新主题。要获取您的 Amazon Quick Sight 账户 ARNs 中所有主题和主题的列表，请调用 [ListThemes](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_ListThemes.html)API 操作。有关预设 Amazon Quick Sight 主题的信息，请参阅[使用 Amazon Quick 为 Amazon Quick 分析设置默认主题 APIs](customizing-quicksight-default-theme.md)。
+ 如果您使用注册用户嵌入，请确保该用户可以访问您想要使用的主题。

  如果您使用匿名用户嵌入，请将主题 ARNs列表传递给 `GenerateEmbedUrlForAnonymousUser` API 的`AuthorizedResourceArns`参数。匿名用户有权访问 `AuthorizedResourceArns` 参数中列出的任何主题。

## SDK 方法接口
<a name="runtime-theming-sdk-interface"></a>

**Setter 方法**

下表介绍了开发人员可以用于运行时主题的不同 setter 方法。


| 方法 | 说明 | 
| --- | --- | 
|  `setTheme(themeArn: string)`  |  将控制面板或视觉对象的活动主题替换为其他主题。如果应用，则会移除主题覆盖。 如果您无权访问主题或主题不存在，则会返回错误。  | 
|  `setThemeOverride(themeOverride: ThemeConfiguration)`  |  设置动态 `ThemeConfiguration` 以覆盖当前活动主题。这将替换之前设置的主题覆盖。新 `ThemeConfiguration` 中未提供的任何值都将默认为当前活动主题中的值。 如果您提供的 `ThemeConfiguration` 无效，则会返回错误。  | 

## 使用主题初始化嵌入式内容
<a name="runtime-theming-sdk-initialize"></a>

要使用非默认主题初始化嵌入式控制面板或视觉对象，请在 `DashboardContentOptions` 或 `VisualContentOptions` 参数上定义 `themeOptions` 对象，并将 `themeOptions` 中的 `themeArn` 属性设置为所需的主题 ARN。

以下示例使用 `MIDNIGHT` 主题初始化嵌入式控制面板。

```
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        themeArn: "arn:aws:quicksight::aws:theme/MIDNIGHT"
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```

## 使用主题覆盖初始化嵌入式内容
<a name="runtime-theming-runtime-initialize-override"></a>

开发人员可以使用主题覆盖在运行时定义嵌入式控制面板或视觉对象的主题。这允许控制面板或视觉对象从第三方应用程序继承主题，而无需在 Amazon Quick Sight 中预先配置主题。要使用主题覆盖初始化嵌入式控制面板或视觉对象，请在 `DashboardContentOptions` 或 `VisualContentOptions` 参数中的 `themeOptions` 中设置 `themeOverride` 属性。以下示例将控制面板主题的字体从默认字体覆盖为 `Amazon Ember`。

```
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        "themeOverride":{"Typography":{"FontFamilies":[{"FontFamily":"Comic Neue"}]}}
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```

## 使用预加载的主题初始化嵌入式内容
<a name="runtime-theming-runtime-initialize-preloaded"></a>

开发人员可以配置一组控制面板主题，以便在初始化时预加载。这对于在不同视图（例如深色和浅色模式）之间快速切换最为有利。嵌入式控制面板或视觉对象最多可使用 5 个预加载的主题进行初始化。要使用预加载的主题，请使用最多 5 个 `themeArns` 的数组在 `DashboardContentOptions` 或 `VisualContentOptions` 中设置 `preloadThemes` 属性。以下示例将 `Midnight` 和 `Rainier` 入门主题预加载到控制面板。

```
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        "preloadThemes": ["arn:aws:quicksight::aws:theme/RAINIER", "arn:aws:quicksight::aws:theme/MIDNIGHT"]
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```

# 使用 Amazon Quick Sight Embedging SDK 启用指向嵌入式控制面板视图的可共享链接
<a name="embedded-view-sharing"></a>

Amazon Quick Sight 开发人员可以使用 Amazon Quick Sight Embedding SDK（版本 2.8.0 及更高版本），允许嵌入式仪表板的读者接收和分发指向嵌入式仪表板视图的可共享链接。开发人员可以使用仪表板或控制台嵌入来生成指向其应用程序页面的可共享链接，其中包含使用Amazon Quick Sight嵌入软件开发工具包封装的Amazon Quick Sight参考文献。然后，Amazon Quick Sight Readers 可以将此可共享链接发送给同行。当他们的同行访问共享链接时，他们会被带到包含嵌入式 Amazon Quick Sight 控制面板的应用程序页面。开发人员还可以生成和保存控制面板视图的可共享链接，当使用匿名嵌入时，这些链接可用作 Amazon Quick Sight 匿名读者的书签。

**先决条件**

在开始之前，请确保您使用的是 Amazon Quick Sight Embedding SDK 版本 2.8.0 或更高版本

**Topics**
+ [

# 为 Amazon Quick Sight 嵌入式分析启用`SharedView`功能配置
](embedded-view-sharing-set-up.md)
+ [

# 使用 Amazon Quick Sight `createSharedView` API 创建共享视图
](embedded-view-sharing-sdk-create.md)
+ [

# 使用共享的 Amazon Quick Sight 视图
](embedded-view-sharing-sdk-consume.md)

# 为 Amazon Quick Sight 嵌入式分析启用`SharedView`功能配置
<a name="embedded-view-sharing-set-up"></a>

当您使用 Amazon Quick Sight API 创建嵌入式实例时，请将`FeatureConfigurations`有效负载中的值设置为`true`，如下例所示。`SharedView` `SharedView`覆盖访问嵌入式仪表板的注册用户的`StatePersistence`配置。如果控制面板用户已禁用 `StatePersistence` 并启用 `SharedView`，则其状态将保留。

```
const generateNewEmbedUrl = async () => {
    const generateUrlPayload = {
        experienceConfiguration: {
            QuickSightConsole: {
            FeatureConfigurations: {
                "SharedView": { 
                    "Enabled": true
                 },
            },
        },
    }
    const result: GenerateEmbedUrlResult = await generateEmbedUrlForRegisteredUser(generateUrlPayload);
    return result.url;
};
```

# 使用 Amazon Quick Sight `createSharedView` API 创建共享视图
<a name="embedded-view-sharing-sdk-create"></a>

将 Embedding SDK 更新至版本 2.8.0 或更高版本后，请使用 `createSharedView` API 创建新的共享视图。记录操作返回的 `sharedViewId` 和 `dashboardId`。下面的示例创建了一个新的共享视图。

```
const response = await embeddingFrame.createSharedView();
const sharedViewId = response.message.sharedViewId;
const dashboardId = response.message.dashboardId;
```

仅当用户查看控制面板时才能调用 `createSharedView`。对于特定于控制台的共享视图创建，请先确保用户位于控制面板页面上，然后再启用 `createSharedView` 操作。您可以使用 `PAGE_NAVIGATION` 事件执行此操作，如下例所示。

```
const contentOptions = {
    onMessage: async (messageEvent, metadata) => {
    switch (messageEvent.eventName) {
            case 'CONTENT_LOADED': {
                console.log("Do something when the embedded experience is fully loaded.");
                break;
            }
            case 'ERROR_OCCURRED': {
                console.log("Do something when the embedded experience fails loading.");
                break;
            }
            case 'PAGE_NAVIGATION': {
                setPageType(messageEvent.message.pageType); 
                if (messageEvent.message.pageType === 'DASHBOARD') {
                    setShareEnabled(true);
                    } else {
                    setShareEnabled(false);
                }
                break;
            }
        }
    }
};
```

# 使用共享的 Amazon Quick Sight 视图
<a name="embedded-view-sharing-sdk-consume"></a>

创建新的共享视图后，请使用 Embedding SDK 使其他用户可以使用共享视图。以下示例在 Amazon Quick Sight 中为嵌入式控制面板设置了可使用的共享视图。

------
#### [ With an appended URL ]

将 `sharedViewId` 附加到嵌入式 URL（位于 ` /views/{viewId}` 下），并将此 URL 公开给您的用户。用户可以使用此 URL 导航到该共享视图。

```
const response = await dashboardFrame.createSharedView();
const newEmbedUrl = await generateNewEmbedUrl();
const formattedUrl = new URL(newEmbedUrl);
formattedUrl.pathname = formattedUrl.pathname.concat('/views/' + response.message.sharedViewId);
const baseUrl = formattedUrl.href;
alert("Click to view this QuickSight shared view", baseUrl);
```

------
#### [ With the contentOptions SDK ]

将 `viewId` 传递给 `contentOptions` 以打开具有给定 `viewId` 的体验。

```
const contentOptions = {
    toolbarOptions: {
        ...
    },
    viewId: sharedViewId,
};

const embeddedDashboard = await embeddingContext.embedDashboard(
    {container: containerRef.current},
    contentOptions
);
```

------
#### [ With the InitialPath property ]

```
const shareView = async() => {
    const returnValue = await consoleFrame.createSharedView();
    const {dashboardId, sharedViewId} = returnValue.message;
    const newEmbedUrl = await generateNewEmbedUrl(`/dashboards/${dashboardId}/views/${sharedViewId}`);
    setShareUrl(newEmbedUrl);
};

const generateNewEmbedUrl = async (initialPath) => {
    const generateUrlPayload = {
        experienceConfiguration: {
            QuickSightConsole: {
            InitialPath: initialPath,
            FeatureConfigurations: {
                "SharedView": { 
                    "Enabled": true
                 },
            },
        },
    }
    const result: GenerateEmbedUrlResult = await generateEmbedUrlForRegisteredUser(generateUrlPayload);
    return result.url;
};
```

------

# 使用一键嵌入代码嵌入 Amazon Quick Sight 视觉效果和仪表板
<a name="1-click-embedding"></a>

您可以使用嵌入代码在应用程序中嵌入视觉对象或控制面板。当你共享控制面板或从 Amazon Quick Sight 的 “**嵌入” 视觉**菜单中时，你会得到这个代码。

您可以在内部应用程序中为注册用户嵌入视觉对象或控制面板，或者你可以在 Amazon Quick Sight 控制台中开启公共共享。此举可让互联网上的任何人访问嵌入在公共应用程序、wiki 或门户中的共享视觉对象或控制面板。

接下来，您可以了解有关如何使用一键式视觉对象或控制面板嵌入代码嵌入视觉对象和控制面板的说明。

**Topics**
+ [

# 通过一键嵌入代码为注册用户嵌入 Amazon Quick Sight 视觉效果和控制面板
](embedded-analytics-1-click.md)
+ [

# 使用一键嵌入代码为匿名用户嵌入 Amazon Quick Sight 视觉效果和控制面板
](embedded-analytics-1-click-public.md)

# 通过一键嵌入代码为注册用户嵌入 Amazon Quick Sight 视觉效果和控制面板
<a name="embedded-analytics-1-click"></a>


|  | 
| --- |
|  适用于：企业版  | 

您可以在内部应用程序中嵌入视觉或控制面板，供您的 Amazon Quick Sight 账户的注册用户使用。您可以使用共享控制面板时获得的嵌入代码或从 Amazon Quick Sight 的 “**嵌入” 视觉**菜单中获得的嵌入代码来执行此操作。您无需运行 Amazon Quick Sight 嵌入 API 即可生成嵌入代码。您可以从 Amazon Quick Sight 中复制嵌入代码并将其粘贴到内部应用程序的 HTML 代码中。

当有权访问您要嵌入的控制面板或包含您要嵌入的视觉效果的用户和群组（或您的 Amazon Quick Sight 账户中的所有用户）访问您的内部应用程序时，系统会提示他们使用自己的凭证登录 Amazon Quick Sight 账户。通过身份验证后，他们可以访问各自内部页面上的视觉对象或控制面板。如果启用了单点登录，系统不会提示用户再次登录。

接下来，您可以了解有关如何使用视觉对象或控制面板嵌入代码为注册用户嵌入视觉对象或控制面板的说明。

## 开始之前
<a name="embedded-analytics-1-click-prerequisites"></a>

在开始之前，您应确保满足以下条件：
+ 互联网浏览器设置包含以下某一项，以允许弹出窗口与 iframe 进行通信：
  + Mozilla Broadcast Channel API 的本机支持。有关更多信息，请参阅 Mozilla 文档中的 [Broadcast Channel API](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API)。
  + IndexedDB 支持。
  + LocalStorage 支持。
+ 互联网浏览器的“阻止所有 Cookie”设置已关闭。

## 步骤 1：授予对控制面板的访问权限
<a name="embedded-analystics-1-click-share"></a>

要让用户访问您的嵌入式控制面板，请向其授予查看该控制面板的权限。您可以授予个人用户和用户组对控制面板的访问权限，也可以向账户中的所有人授予访问权限。视觉对象权限在控制面板级别确定。要授予对嵌入式视觉对象的访问权限，请授予对视觉对象所属控制面板的访问权限。有关更多信息，请参阅 [授予对控制面板的访问权限](share-a-dashboard.md)。

## 步骤 2：将要嵌入视觉对象或控制面板的域放入允许列表
<a name="embedded-analytics-1-click-allow-list"></a>

要在内部应用程序中嵌入视觉对象和控制面板，请确保您要嵌入的域名已列入您的 Amazon Quick Sight 账户的允许名单。有关更多信息，请参阅 [允许列出静态域](manage-domains.md#embedding-static)。

## 步骤 3：获取嵌入代码
<a name="embedded-analytics-1-click-code"></a>

要获取视觉对象或控制面板嵌入代码，请按照以下过程操作。

**获取控制面板嵌入代码**

1. 在 Amazon Quick Sight 中打开已发布的控制面板，然后选择右上角的 “**共享**”。再选择**共享控制面板**。

1. 在打开的**共享控制面板**页面中，选择左上角的**复制嵌入代码**。

   嵌入代码已复制到剪贴板，且类似于以下内容。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。

   ```
   <iframe
           width="960"
           height="720"
           src="https://quicksightdomain/sn/embed/share/accounts/accountid/dashboards/dashboardid?directory_alias=account_directory_alias">
       </iframe>
   ```

**获取视觉对象嵌入代码**

1. 在 Amazon Quick Sight 中打开已发布的控制面板，然后选择要嵌入的视觉效果。然后打开视觉对象右上角的视觉对象菜单，从中选择**嵌入视觉对象**。

1. 在打开的**嵌入视觉对象**窗格中，选择**复制代码**。

   嵌入代码已复制到剪贴板，且类似于以下内容。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。

   ```
   <iframe
           width="600"
           height="400"
           src="https://quicksightdomain/sn/embed/share/accounts/111122223333/dashboards/DASHBOARDID/sheets/SHEETID>/visuals/VISUALID">
       </iframe>
   ```

## 步骤 4：将代码粘贴到内部应用程序的 HTML 页面中
<a name="embedded-analytics-1-click-html"></a>

要将嵌入代码粘贴到内部应用程序的 HTML 页面中，请按照以下过程操作。

**将代码粘贴到内部应用程序的 HTML 页面中**
+ 打开要嵌入控制面板的任何页面的 HTML 代码，然后将嵌入代码粘贴到其中。

  以下示例演示了嵌入式控制面板的大致样式。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。

  ```
  <!DOCTYPE html>
      <html>
      <body>
  
      <h2>Example.com - Employee Portal</h2>
      <h3>Current shipment stats</h3>
          <iframe
          width="960"
          height="720"
          src="https://quicksightdomain/sn/embed/share/accounts/accountid/dashboards/dashboardid?directory_alias=account_directory_alias">
      </iframe>
  
      </body>
      </html>
  ```

  以下示例演示了嵌入式视觉对象的大致样式。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。

  ```
  <!DOCTYPE html>
      <html>
      <body>
  
      <h2>Example.com - Employee Portal</h2>
      <h3>Current shipment stats</h3>
          <iframe
          width="600"
          height="400"
          src="https://quicksightdomain/sn/embed/share/accounts/111122223333/dashboards/DASHBOARDID/sheets/SHEETID>/visuals/VISUALID?directory_alias=account_directory_alias">
      </iframe>
  
      </body>
      </html>
  ```

例如，假设您希望将视觉对象或控制面板嵌入 Google 协作平台内部页面。您可以在 Google 协作平台上打开该页面，然后将嵌入代码粘贴到嵌入小部件中。

如果要将视觉对象或仪表板嵌入到 Microsoft 内部 SharePoint 网站中，可以创建一个新页面，然后将嵌入代码粘贴到嵌入的 Web 部件中。

# 使用一键嵌入代码为匿名用户嵌入 Amazon Quick Sight 视觉效果和控制面板
<a name="embedded-analytics-1-click-public"></a>


|  | 
| --- |
|  适用于：企业版  | 

您可以使用在 Amazon Quick Sight 中共享视觉对象或控制面板时获得的嵌入代码将视觉对象或控制面板嵌入到公共网站中。您还可以使用 Amazon Quick Sight 控制台开启公开共享，并自动向互联网上的任何人授予访问共享视觉对象或控制面板的权限。

接下来，您可以了解如何为视觉对象或控制面板开启公开共享，以及如何嵌入视觉对象或控制面板供互联网上的任何人查看。在这两种情况下，您都可以使用一键式嵌入代码来完成此操作。

## 开始之前
<a name="embedded-analytics-1-click-prerequisites"></a>

在开始之前，您应确保满足以下条件：
+ 互联网浏览器设置包含以下某一项，以允许弹出窗口与共享使用的 iframe 进行通信：
  + Mozilla Broadcast Channel API 的本机支持。有关更多信息，请参阅 Mozilla 文档中的 [Broadcast Channel API](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API)。
  + IndexedDB 支持。
  + LocalStorage 支持。
+ 互联网浏览器的“阻止所有 Cookie”设置已关闭。

## 步骤 1：开启控制面板的公有访问权限
<a name="embedded-analytics-1-click-step-1"></a>

要让互联网上的任何人都能访问您的嵌入式视觉对象或控制面板，请先开启控制面板的公有访问权限。视觉对象权限在控制面板级别确定。要授予对嵌入式视觉对象的访问权限，请授予对视觉对象所属控制面板的访问权限。有关更多信息，请参阅 [允许互联网上的任何人访问 Amazon Quick Sight 控制面板](share-a-dashboard-grant-access-anyone.md)。

## 步骤 2：将要嵌入视觉对象或控制面板的域放入允许列表
<a name="embedded-analytics-1-click-step-2"></a>

要在公共应用程序、wiki 或门户中嵌入视觉对象和控制面板，请确保您要嵌入的域名位于您的 Amazon Quick Sight 账户的允许列表中。

## 步骤 3：获取嵌入代码
<a name="embedded-analytics-1-click-step-3"></a>

要获取视觉对象或控制面板嵌入代码，请按照以下过程操作。

**获取控制面板嵌入代码**

1. 在 Amazon Quick Sight 中打开已发布的控制面板，然后选择右上角的 “**共享**”。再选择**共享控制面板**。

1. 在打开的**共享控制面板**页面中，选择左上角的**复制嵌入代码**。

   嵌入代码已复制到剪贴板，且类似于以下内容。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。

   ```
   <iframe
           width="960"
           height="720"
           src="https://quicksightdomain/sn/
               embed/share/accounts/accountid/dashboards/dashboardid">
       </iframe>
   ```

**获取视觉对象嵌入代码**

1. 在 Amazon Quick Sight 中打开已发布的控制面板，然后选择要嵌入的视觉效果。然后打开视觉对象右上角的视觉对象菜单，从中选择**嵌入视觉对象**。

1. 在打开的**嵌入视觉对象**窗格中，选择**复制代码**。

   嵌入代码已复制到剪贴板，且类似于以下内容。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。

   ```
   <iframe
           width="600"
           height="400"
           src="https://quicksightdomain/sn/embed/share/accounts/111122223333/dashboards/DASHBOARDID/sheets/SHEETID>/visuals/VISUALID">
       </iframe>
   ```

## 步骤 4：将嵌入代码粘贴到 HTML 页面、wiki 页面或门户中
<a name="embedded-analytics-1-click-step-4"></a>

要将嵌入代码粘贴到 HTML 页面、wiki 页面或门户中，请按照以下过程操作。

**粘贴嵌入代码**
+ 打开要嵌入视觉对象或控制面板的位置的 HTML 代码，然后将嵌入代码粘贴到其中。

  以下示例演示了嵌入式控制面板的大致样式。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。

  ```
  <!DOCTYPE html>
      <html>
      <body>
  
      <h2>Example.com - Employee Portal</h2>
      <h3>Current shipment stats</h3>
          <iframe
          width="960"
          height="720"
          src="https://quicksightdomain/sn/
              embed/share/accounts/accountid/dashboards/dashboardid">
      </iframe>
  
      </body>
      </html>
  ```

  以下示例演示了嵌入式视觉对象的大致样式。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。

  ```
  <!DOCTYPE html>
      <html>
      <body>
  
      <h2>Example.com - Employee Portal</h2>
      <h3>Current shipment stats</h3>
          <iframe
          width="600"
          height="400"
          src="https://quicksightdomain/sn/embed/share/accounts/111122223333/dashboards/DASHBOARDID/sheets/SHEETID>/visuals/VISUALID">
      </iframe>
  
      </body>
      </html>
  ```

如果面向公众的应用程序是基于 Google 协作平台构建的，请在 Google 协作平台中打开该页面，然后使用嵌入小部件粘贴嵌入代码。

在 Google 协作平台中嵌入时，请确保 Amazon Quick Sight 中的以下域名在允许列表中：
+ `https://googleusercontent.com`（开启子域）
+ `https://www.gstatic.com`
+ `https://sites.google.com`

将视觉对象或控制面板嵌入应用程序后，能够访问您应用程序的任何人都可以访问嵌入式视觉对象或控制面板。要更新与公众共享的控制面板，请参阅 [更新公开共享的控制面板](share-a-dashboard-grant-access-anyone-update.md)。要关闭公开共享，请参阅 [关闭公开共享设置](share-a-dashboard-grant-access-anyone-no-share.md)。

当您关闭公开共享后，互联网上的任何人都无法访问您嵌入公共应用程序的或通过链接共享的控制面板。下次有人尝试通过互联网查看此类控制面板时，他们会收到一条消息，提示他们无权查看控制面板。

# 嵌入 Amazon Quick Sight APIs
<a name="embedded-analytics-api"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

使用 Amazon Quick Sight 嵌入分析的实际过程只涉及几个步骤 APIs。

开始之前，请确保下列事项已准备就绪：
+ 为将使用 AWS 软件开发工具包进行 API 调用的应用程序使用的来电者身份设置所需的 IAM 权限。例如，授予允许 `quicksight:GenerateEmbedUrlForAnonymousUser` 或 `quicksight:GenerateEmbedUrlForRegisteredUser` 操作的权限。
+ 要为注册用户嵌入，请事先与他们共享 Amazon Quick Sight 资产。对于新的身份验证用户，请知晓如何授予对资产的访问权限。一种方法是将所有资产添加到 Amazon Quick Sight 文件夹。如果您更喜欢使用 Amazon Quick Sight API，请使用`DescribeDashboardPermissions`和 `UpdateDashboardPermissions` API 操作。有关更多信息，请参阅 *Amazon Quick API 参考[UpdateDashboardPermissions](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_UpdateDashboardPermissions.html)*中的[DescribeDashboardPermissions](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeDashboardPermissions.html)或。如果您想与命名空间或用户组中的所有用户共享控制面板，则可以与 `namespace` 或 `group` 共享控制面板。
+ 如果您要嵌入控制面板，请确保拥有要嵌入的控制面板 ID。控制面板 ID 是控制面板 URL 中的代码。您也可以从控制面板 URL 中获得该信息。
+ Amazon Quick Sight 管理员必须明确启用您计划在其中嵌入 Amazon Quick Sight 分析的域名。您可以使用个人资料菜单中的 “**管理 Amazon Quick Sight**、**域名和嵌入**” 来执行此操作，也可以使用`GenerateEmbedUrlForAnonymousUser`或 `GenerateEmbedUrlForRegisteredUser` API 调用的`AllowedDomains`参数。

  此选项仅对 Amazon Quick Sight 管理员可见。您也可以将子域添加为域的一部分。有关更多信息，请参阅 [允许在运行时使用 Amazon Quick API 上架域名](manage-domains.md#embedding-run-time)。

  必须显式允许静态允许列表中的所有域（如开发、暂存和生产），并且这些域必须使用 HTTPS。最多可以向允许列表添加 100 个域。您可以在运行时使用 Amazon Quick Sight API 操作添加域名。

在完成所有先决条件后，嵌入 Amazon Quick Sight 涉及以下步骤，稍后将详细介绍这些步骤：

1. 对于身份验证，请使用您的应用程序服务器对用户进行身份验证。在服务器中进行身份验证后，使用所需的 AWS SDK 生成嵌入式控制面板 URL。

1. 在您的门户网站或应用程序中，使用生成的 URL 嵌入 Amazon Quick Sight。为了简化此过程，你可以使用 [NPMJS 上提供的 Amazon Quick Sight Embedding Sight Embeddin](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) g S [GitHub](https://github.com/awslabs/amazon-quicksight-embedding-sdk) 此自定义 JavaScript SDK 旨在帮助您高效地将 Amazon Quick Sight 集成到应用程序页面、设置默认值、连接控件、获取回调和处理错误。

您可以使用 AWS CloudTrail 审计日志来获取有关嵌入式仪表板数量、嵌入式体验的用户和访问率的信息。

**Topics**
+ [

# 将 Amazon Quick Sight 仪表板嵌入亚马逊快速视图 API
](embedding-dashboards.md)
+ [

# 将 Amazon Quick Sight 视觉效果嵌入到亚马逊快速瞄准器中 APIs
](embedding-visuals.md)
+ [

# 为注册用户嵌入 Amazon Quick Sight 控制台的全部功能
](embedded-analytics-full-console-for-authenticated-users.md)
+ [

# 在 Amazon Quick Sight 生成问答体验中嵌入 Amazon Q
](embedding-gen-bi.md)
+ [

# 嵌入 Amazon Quick Sight Q 搜索栏（经典版）
](embedding-quicksight-q.md)
+ [

# 使用 GetDashboardEmbedURL 和 GetSessionEmbedURL API 操作嵌入分析
](embedded-analytics-deprecated.md)

# 将 Amazon Quick Sight 仪表板嵌入亚马逊快速视图 API
<a name="embedding-dashboards"></a>

使用以下主题了解如何使用 Amazon Quick Sight API 嵌入控制面板。

**Topics**
+ [

# 为注册用户嵌入 Amazon 快速浏览控制面板
](embedded-analytics-dashboards-for-authenticated-users.md)
+ [

# 为匿名（未注册）用户嵌入 Amazon Quick Sight 控制面板
](embedded-analytics-dashboards-for-everyone.md)
+ [

# 在嵌入式控制面板中启用执行摘要
](embedded-analytics-genbi-executive-summaries-dashboard.md)

# 为注册用户嵌入 Amazon 快速浏览控制面板
<a name="embedded-analytics-dashboards-for-authenticated-users"></a>

**重要**  
Amazon Quick Sight 推出了用于嵌入分析的新 API 操作：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` API 操作来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关使用旧 API 操作进行嵌入的更多信息，请参阅[使用GetDashboardEmbedURL和 GetSessionEmbedURL API 操作嵌入分析](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics-deprecated.html)。


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在以下各节中，您可以找到有关如何为 Amazon Quick Sight 的注册用户设置嵌入式 Amazon Quick Sight 控制面板的详细信息。

**Topics**
+ [

## 步骤 1：设置权限
](#embedded-dashboards-for-authenticated-users-step-1)
+ [

## 步骤 2：生成附带身份验证代码的 URL
](#embedded-dashboards-for-authenticated-users-step-2)
+ [

## 步骤 3：嵌入控制面板 URL
](#embedded-dashboards-for-authenticated-users-step-3)

## 步骤 1：设置权限
<a name="embedded-dashboards-for-authenticated-users-step-1"></a>

在下节中，您可以了解如何设置后端应用程序或 Web 服务器的权限。该任务需要具有 IAM 的管理访问权限。

每个访问控制面板的用户都扮演一个角色，授予他们 Amazon Quick Sight 访问控制面板的权限和权限。要实现这一点，请在您的中创建一个 IAM 角色 AWS 账户。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。IAM 角色需要提供权限才能检索特定用户池 URLs 的嵌入内容。借助通配符 *\$1*，您可以授予为特定命名空间中的所有用户部分用户生成 URL 的权限。为此，请添加 `quicksight:GenerateEmbedUrlForRegisteredUser`。

您可以在 IAM 策略中创建一个条件，限制开发人员可以在 `GenerateEmbedUrlForRegisteredUser` API 操作的 `AllowedDomains` 参数中列出的域。`AllowedDomains` 参数是可选参数。作为开发者，它允许您选择覆盖在 “**管理 Amazon Quick Sight**” 菜单中配置的静态域。您最多可以列出三个可以访问生成的 URL 的域或子域。然后，此 URL 将嵌入您创建的网站。只有参数中列出的域才能访问嵌入式视觉对象。如果没有此条件，则可以在 `AllowedDomains` 参数中列出互联网上的任何域。

要限制开发人员可用于此参数的域，请在 IAM 策略中添加一个 `AllowedEmbeddingDomains` 条件。有关该`AllowedDomains`参数的更多信息，请参阅 *Amazon Quick Sight API 参考[GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)*中的。

**IAM 条件运算符的安全最佳实践**  
配置不当的 IAM 条件运算符可能会允许未经授权地通过 URL 变体访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用`quicksight:AllowedEmbeddingDomains`条件密钥时，请使用条件运算符，允许特定域名或拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息，请参阅 [IAM 用户指南中的 IAM JSON 策略元素：条件运算符](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
许多不同的网址变体可以指向同一个资源。例如，以下 URLs 所有内容都解析为相同的内容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的策略使用的运算符不考虑这些 URL 变体，则攻击者可以通过提供等效的 URL 变体来绕过您的限制。  
您必须验证您的 IAM 策略是否使用了适当的条件运算符来防止绕过漏洞，并确保只有您的目标域才能访问您的嵌入式资源。

以下示例策略提供了这些权限。

此外，如果您要创建将成为 Amazon Quick Sight 读者的首次用户，请务必在策略中添加`quicksight:RegisterUser`权限。

以下示例策略为即将成为 Amazon Quick Sight 读者的首次用户提供了检索嵌入网址的权限。

最后，您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，当用户访问您的应用程序时，您的应用程序可以代表用户担任该角色并在 Amazon Quick Sight 中配置用户。下面演示了一个示例信任策略。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowLambdaFunctionsToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        {
            "Sid": "AllowEC2InstancesToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

------

有关 OpenId Connect 或 SAML 身份验证的信任策略的更多信息，请参阅 *IAM 用户指南* 的以下部分：
+ [创建用于 Web 联合身份验证或 OpenID Connect 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [创建用于 SAML 2.0 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

## 步骤 2：生成附带身份验证代码的 URL
<a name="embedded-dashboards-for-authenticated-users-step-2"></a>

在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入控制面板 URL。如果您计划为 IAM 或 Amazon Quick Sight 身份类型嵌入控制面板，请与用户共享控制面板。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，它会将该用户添加到 Amazon Quick Sight 中（如果该用户尚不存在）。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

执行这些步骤可确保在 Amazon Quick Sight 中对控制面板的每个查看者进行唯一配置。它还实施每个用户的设置，例如，行级别安全性和参数的动态默认值。

以下示例展示了代表用户执行 IAM 身份验证。此代码在您的应用程序服务器上运行。

### Java
<a name="embedded-dashboards-for-authenticated-users-java"></a>

```
import com.amazonaws.auth.AWSCredentials;
    import com.amazonaws.auth.BasicAWSCredentials;
    import com.amazonaws.auth.AWSCredentialsProvider;
    import com.amazonaws.regions.Regions;
    import com.amazonaws.services.quicksight.AmazonQuickSight;
    import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
    import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserRequest;
    import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserResult;
    import com.amazonaws.services.quicksight.model.RegisteredUserEmbeddingExperienceConfiguration;
    import com.amazonaws.services.quicksight.model.RegisteredUserDashboardEmbeddingConfiguration;

    /**
    * Class to call QuickSight AWS SDK to get url for dashboard embedding.
    */
    public class GetQuicksightEmbedUrlRegisteredUserDashboardEmbedding {

        private final AmazonQuickSight quickSightClient;

        public GetQuicksightEmbedUrlRegisteredUserDashboardEmbedding() {
            this.quickSightClient = AmazonQuickSightClientBuilder
                    .standard()
                    .withRegion(Regions.US_EAST_1.getName())
                    .withCredentials(new AWSCredentialsProvider() {
                        @Override
                        public AWSCredentials getCredentials() {
                            // provide actual IAM access key and secret key here
                            return new BasicAWSCredentials("access-key", "secret-key");
                        }

                        @Override
                        public void refresh() {}
                        }
                    )
                    .build();
        }

        public String getQuicksightEmbedUrl(
                final String accountId, // AWS Account ID
                final String dashboardId, // Dashboard ID to embed
                final List<String> allowedDomains, // Runtime allowed domain for embedding
                final String userArn // Registered user arn to use for embedding. Refer to Get Embed Url section in developer portal to find out how to get user arn for a QuickSight user.
        ) throws Exception {
            final RegisteredUserEmbeddingExperienceConfiguration experienceConfiguration = new RegisteredUserEmbeddingExperienceConfiguration()
                    .withDashboard(new RegisteredUserDashboardEmbeddingConfiguration().withInitialDashboardId(dashboardId));
            final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest = new GenerateEmbedUrlForRegisteredUserRequest();
            generateEmbedUrlForRegisteredUserRequest.setAwsAccountId(accountId);
            generateEmbedUrlForRegisteredUserRequest.setUserArn(userArn);
            generateEmbedUrlForRegisteredUserRequest.setAllowedDomains(allowedDomains);
            generateEmbedUrlForRegisteredUserRequest.setExperienceConfiguration(experienceConfiguration);

            final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);

            return generateEmbedUrlForRegisteredUserResult.getEmbedUrl();
        }
    }
```

### JavaScript
<a name="embedded-dashboards-for-authenticated-users-js"></a>

```
global.fetch = require('node-fetch');
    const AWS = require('aws-sdk');

    function generateEmbedUrlForRegisteredUser(
        accountId,
        dashboardId,
        openIdToken, // Cognito-based token
        userArn, // registered user arn
        roleArn, // IAM user role to use for embedding
        sessionName, // Session name for the roleArn assume role
        allowedDomains, // Runtime allowed domain for embedding
        getEmbedUrlCallback, // GetEmbedUrl success callback method
        errorCallback // GetEmbedUrl error callback method
        ) {
        const stsClient = new AWS.STS();
        let stsParams = {
            RoleSessionName: sessionName,
            WebIdentityToken: openIdToken,
            RoleArn: roleArn
        }

        stsClient.assumeRoleWithWebIdentity(stsParams, function(err, data) {
            if (err) {
                console.log('Error assuming role');
                console.log(err, err.stack);
                errorCallback(err);
            } else {
                const getDashboardParams = {
                    "AwsAccountId": accountId,
                    "ExperienceConfiguration": {
                        "Dashboard": {
                            "InitialDashboardId": dashboardId
                        }
                    },
                    "UserArn": userArn,
                    "AllowedDomains": allowedDomains,
                    "SessionLifetimeInMinutes": 600
                };

                const quicksightClient = new AWS.QuickSight({
                    region: process.env.AWS_REGION,
                    credentials: {
                        accessKeyId: data.Credentials.AccessKeyId,
                        secretAccessKey: data.Credentials.SecretAccessKey,
                        sessionToken: data.Credentials.SessionToken,
                        expiration: data.Credentials.Expiration
                    }
                });

                quicksightClient.generateEmbedUrlForRegisteredUser(getDashboardParams, function(err, data) {
                    if (err) {
                        console.log(err, err.stack);
                        errorCallback(err);
                    } else {
                        const result = {
                            "statusCode": 200,
                            "headers": {
                                "Access-Control-Allow-Origin": "*", // Use your website domain to secure access to GetEmbedUrl API
                                "Access-Control-Allow-Headers": "Content-Type"
                            },
                            "body": JSON.stringify(data),
                            "isBase64Encoded": false
                        }
                        getEmbedUrlCallback(result);
                    }
                });
            }
        });
    }
```

### Python3
<a name="embedded-dashboards-for-authenticated-users-py"></a>

```
import json
import boto3
from botocore.exceptions import ClientError

sts = boto3.client('sts')

# Function to generate embedded URL  
# accountId: AWS account ID
# dashboardId: Dashboard ID to embed
# userArn: arn of registered user
# allowedDomains: Runtime allowed domain for embedding
# roleArn: IAM user role to use for embedding
# sessionName: session name for the roleArn assume role
def getEmbeddingURL(accountId, dashboardId, userArn, allowedDomains, roleArn, sessionName):
    try:
        assumedRole = sts.assume_role(
            RoleArn = roleArn,
            RoleSessionName = sessionName,
        )
    except ClientError as e:
        return "Error assuming role: " + str(e)
    else: 
        assumedRoleSession = boto3.Session(
            aws_access_key_id = assumedRole['Credentials']['AccessKeyId'],
            aws_secret_access_key = assumedRole['Credentials']['SecretAccessKey'],
            aws_session_token = assumedRole['Credentials']['SessionToken'],
        )
        try:
            quicksightClient = assumedRoleSession.client('quicksight', region_name='us-west-2')
            response = quicksightClient.generate_embed_url_for_registered_user(
                AwsAccountId=accountId,
                ExperienceConfiguration = {
                    "Dashboard": {
                        "InitialDashboardId": dashboardId
                    }
                },
                UserArn = userArn,
                AllowedDomains = allowedDomains,
                SessionLifetimeInMinutes = 600
            )
            
            return {
                'statusCode': 200,
                'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
                'body': json.dumps(response),
                'isBase64Encoded':  bool('false')
            }
        except ClientError as e:
            return "Error generating embedding url: " + str(e)
```

### Node.js
<a name="embedded-dashboards-for-authenticated-users-node"></a>

以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 URL 的 JavaScript (Node.js)。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
const AWS = require('aws-sdk');
    const https = require('https');

    var quicksightClient = new AWS.Service({
        apiConfig: require('./quicksight-2018-04-01.min.json'),
        region: 'us-east-1',
    });

    quicksightClient.generateEmbedUrlForRegisteredUser({
        'AwsAccountId': '111122223333',
        'ExperienceConfiguration': { 
            'Dashboard': {
                'InitialDashboardId': '1c1fe111-e2d2-3b30-44ef-a0e111111cde'
            }
        },
        'UserArn': 'REGISTERED_USER_ARN',
        'AllowedDomains': allowedDomains,
        'SessionLifetimeInMinutes': 100
    }, function(err, data) {
        console.log('Errors: ');
        console.log(err);
        console.log('Response: ');
        console.log(data);
    });
```

**Example**  

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
    //readability and added ellipsis to indicate that it's incomplete.
        { 
            Status: 200,
            EmbedUrl: 'https://quicksightdomain/embed/12345/dashboards/67890...'
            RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' 
        }
```

### .NET/C\$1
<a name="embedded-dashboards-for-authenticated-users-cs"></a>

以下示例演示了可以在应用程序服务器上使用以生成嵌入式控制面板 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
using System;
    using Amazon.QuickSight;
    using Amazon.QuickSight.Model;

    namespace GenerateDashboardEmbedUrlForRegisteredUser
    {
        class Program
        {
            static void Main(string[] args)
            {
                var quicksightClient = new AmazonQuickSightClient(
                    AccessKey,
                    SecretAccessKey,
                    SessionToken,
                    Amazon.RegionEndpoint.USEast1);
                try
                {
                    RegisteredUserDashboardEmbeddingConfiguration registeredUserDashboardEmbeddingConfiguration
                        = new RegisteredUserDashboardEmbeddingConfiguration
                        {
                            InitialDashboardId = "dashboardId"
                        };
                    RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                        = new RegisteredUserEmbeddingExperienceConfiguration
                        {
                            Dashboard = registeredUserDashboardEmbeddingConfiguration
                        };
                        
                    Console.WriteLine(
                        quicksightClient.GenerateEmbedUrlForRegisteredUserAsync(new GenerateEmbedUrlForRegisteredUserRequest
                        {
                            AwsAccountId = "111122223333",
                            ExperienceConfiguration = registeredUserEmbeddingExperienceConfiguration,
                            UserArn = "REGISTERED_USER_ARN",
                            AllowedDomains = allowedDomains,
                            SessionLifetimeInMinutes = 100
                        }).Result.EmbedUrl
                    );
                } catch (Exception ex) {
                    Console.WriteLine(ex.Message);
                }
            }
        }
    }
```

### AWS CLI
<a name="embedded-dashboards-for-authenticated-users-cli"></a>

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用 SAML 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GenerateEmbedUrlForRegisteredUser` 启用权限。如果您采用一种在用户首次打开仪表板时添加用户的 just-in-time方法，则该角色还需要为其启用权限`quicksight:RegisterUser`。

```
aws sts assume-role \
        --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
        --role-session-name john.doe@example.com
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。如果使用的是 Microsoft Windows 计算机，请使用 `set` 而非 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
    export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
    export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_dashboard_role/john.doe@example.com`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个用户设置相应的权限。此外，它还能避免任何用户访问限制。*限制*是一项安全功能，可防止同一个用户从多个位置访问 Amazon Quick Sight。

角色会话 ID 也将成为 Amazon Quick Sight 中的用户名。您可以使用此模式提前在 Amazon Quick Sight 中配置用户，或者在他们首次访问控制面板时对其进行配置。

以下示例显示了可用于预置用户的 CLI 命令。有关[RegisterUser[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html)](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、和其他 Amazon Quick Sight API 操作的更多信息，请参阅[亚马逊 Quick Sight API 参考](https://docs.aws.amazon.com/quicksight/latest/APIReference/Welcome.html)。

```
aws quicksight register-user \
        --aws-account-id 111122223333 \
        --namespace default \
        --identity-type IAM \
        --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
        --user-role READER \
        --user-name jhnd \
        --session-name "john.doe@example.com" \
        --email john.doe@example.com \
        --region us-east-1 \
        --custom-permissions-name TeamA1
```

如果用户通过 Microsoft AD 进行身份验证，则无需使用 `RegisterUser` 进行设置。相反，他们应该在首次访问 Amazon Quick Sight 时自动订阅。对于 Microsoft AD 用户，您可以使用 `DescribeUser` 获取用户 ARN。

用户首次访问 Amazon Quick Sight 时，您也可以将该用户添加到与之共享控制面板的群组中。以下示例显示了将用户添加到组的 CLI 命令。

```
aws quicksight create-group-membership \
    --aws-account-id=111122223333 \
    --namespace=default \
    --group-name=financeusers \
    --member-name="embedding_quicksight_dashboard_role/john.doe@example.com"
```

现在，您的应用程序的用户也是 Amazon Quick Sight 的用户，并且可以访问控制面板。

最后，要获取控制面板的签名 URL，请从应用程序服务器中调用 `generate-embed-url-for-registered-user`。这会返回可嵌入的控制面板 URL。以下示例说明如何使用服务器端调用为通过身份验证 AWS Managed Microsoft AD 或单点登录（IAM Identity Center）进行身份验证的用户生成嵌入式控制面板的 URL。

```
aws quicksight generate-embed-url-for-registered-user \
        --aws-account-id 111122223333 \
        --session-lifetime-in-minutes 600 \
        --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_visual_role/embeddingsession \
        --allowed-domains '["domain1","domain2"]' \
        --experience-configuration Dashboard={InitialDashboardId=1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89}
```

有关使用此操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在自己的代码中使用该 API 操作和其他操作。

## 步骤 3：嵌入控制面板 URL
<a name="embedded-dashboards-for-authenticated-users-step-3"></a>

在下一节中，您可以了解如何使用 [Amazon Quick Sight Embedging SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 将第 3 步中的控制面板网址嵌入到您的网站或应用程序页面中。通过使用该开发工具包，您可以执行以下操作：
+ 将控制面板放在 HTML 页面上。
+ 将参数传递到控制面板。
+ 使用为应用程序自定义的消息处理错误状态。

调用 `GenerateEmbedUrlForRegisteredUser` API 操作生成可嵌入应用的 URL。该 URL 的有效时间为 5 分钟，生成的会话有效时间为 10 个小时。该 API 操作为 URL 提供 `auth_code` 以启用单点登录会话。

下面显示了 `generate-embed-url-for-registered-user` 的示例响应：

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
    {
        "Status": "200",
        "EmbedUrl": "https://quicksightdomain/embed/12345/dashboards/67890..",
        "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
    }
```

使用 [Amazon Quick Sight Embedding SDK 或将此 URL 添加到 iframe 中，将此控制面板嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会在窗口大小调整时更改视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制控制面板中的参数并接收有关页面加载完成和错误的回调。

要托管嵌入式控制面板的域必须位于*允许列表*（为您的 Quick 订阅批准的域的列表）中。这一要求可阻止未经批准的域托管嵌入式控制面板，从而保护您的数据。有关为嵌入式控制面板添加域名的更多信息，请参阅[允许使用 Amazon Quick Sight API 在运行时列出域名](https://docs.aws.amazon.com/quicksight/latest/user/embedding-run-time.html)。

以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。

### SDK 2.0
<a name="embedded-dashboards-for-authenticated-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Dashboard Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedDashboard = async() => {
                const {
                    createEmbeddingContext,
                } = QuickSightEmbedding;

                const embeddingContext = await createEmbeddingContext({
                    onChange: (changeEvent, metadata) => {
                        console.log('Context received a change', changeEvent, metadata);
                    },
                });

                const frameOptions = {
                    url: '<YOUR_EMBED_URL>',
                    container: '#experience-container',
                    height: "700px",
                    width: "1000px",
                    onChange: (changeEvent, metadata) => {
                        switch (changeEvent.eventName) {
                            case 'FRAME_MOUNTED': {
                                console.log("Do something when the experience frame is mounted.");
                                break;
                            }
                            case 'FRAME_LOADED': {
                                console.log("Do something when the experience frame is loaded.");
                                break;
                            }
                        }
                    },
                };

                const contentOptions = {
                    parameters: [
                        {
                            Name: 'country',
                            Values: [
                                'United States'
                            ],
                        },
                        {
                            Name: 'states',
                            Values: [
                                'California',
                                'Washington'
                            ]
                        }
                    ],
                    locale: "en-US",
                    sheetOptions: {
                        initialSheetId: '<YOUR_SHEETID>',
                        singleSheet: false,                        
                        emitSizeChangedEventOnSheetChange: false,
                    },
                    toolbarOptions: {
                        export: false,
                        undoRedo: false,
                        reset: false
                    },
                    attributionOptions: {
                        overlayContent: false,
                    },
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'CONTENT_LOADED': {
                                console.log("All visuals are loaded. The title of the document:", messageEvent.message.title);
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Error occurred while rendering the experience. Error code:", messageEvent.message.errorCode);
                                break;
                            }
                            case 'PARAMETERS_CHANGED': {
                                console.log("Parameters changed. Changed parameters:", messageEvent.message.changedParameters);
                                break;
                            }
                            case 'SELECTED_SHEET_CHANGED': {
                                console.log("Selected sheet changed. Selected sheet:", messageEvent.message.selectedSheet);
                                break;
                            }
                            case 'SIZE_CHANGED': {
                                console.log("Size changed. New dimensions:", messageEvent.message);
                                break;
                            }
                            case 'MODAL_OPENED': {
                                window.scrollTo({
                                    top: 0 // iframe top position
                                });
                                break;
                            }
                        }
                    },
                };
                const embeddedDashboardExperience = await embeddingContext.embedDashboard(frameOptions, contentOptions);

                const selectCountryElement = document.getElementById('country');
                selectCountryElement.addEventListener('change', (event) => {
                    embeddedDashboardExperience.setParameters([
                        {
                            Name: 'country',
                            Values: event.target.value
                        }
                    ]);
                });
            };
        </script>
    </head>

    <body onload="embedDashboard()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="experience-container"></div>
    </body>

</html>
```

### SDK 1.0
<a name="embedded-dashboards-for-authenticated-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Basic Embed</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.0.15/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            var dashboard
            function onDashboardLoad(payload) {
                console.log("Do something when the dashboard is fully loaded.");
            }

            function onError(payload) {
                console.log("Do something when the dashboard fails loading");
            }

            function embedDashboard() {
                var containerDiv = document.getElementById("embeddingContainer");
                var options = {
                    // replace this dummy url with the one generated via embedding API
                    url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",
                    container: containerDiv,
                    parameters: {
                        country: "United States"
                    },
                    scrolling: "no",
                    height: "700px",
                    width: "1000px",
                    locale: "en-US",
                    footerPaddingEnabled: true
                };
                dashboard = QuickSightEmbedding.embedDashboard(options);
                dashboard.on("error", onError);
                dashboard.on("load", onDashboardLoad);
            }

            function onCountryChange(obj) {
                dashboard.setParameters({country: obj.value});
            }
        </script>
    </head>

    <body onload="embedDashboard()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country" onchange="onCountryChange(this)">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="embeddingContainer"></div>
    </body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 将嵌入式控制面板加载到您的网站上 JavaScript。要获取副本，请执行下列操作之一：
+ 从 GitHub中下载 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) 该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

# 为匿名（未注册）用户嵌入 Amazon Quick Sight 控制面板
<a name="embedded-analytics-dashboards-for-everyone"></a>

**重要**  
Amazon Quick Sight 推出了用于嵌入分析的新 API 操作：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` API 操作来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关使用旧 API 操作进行嵌入的更多信息，请参阅[使用GetDashboardEmbedURL和 GetSessionEmbedURL API 操作嵌入分析](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics-deprecated.html)。


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在以下各节中，您可以找到有关如何为匿名（未注册）用户设置嵌入式 Amazon Quick Sight 控制面板的详细信息。

**Topics**
+ [

## 步骤 1：设置权限
](#embedded-analytics-dashboards-with-anonymous-users-step-1)
+ [

## 步骤 2：生成附带身份验证代码的 URL
](#embedded-analytics-dashboards-with-anonymous-users-step-2)
+ [

## 步骤 3：嵌入控制面板 URL
](#embedded-analytics-dashboards-with-anonymous-users-step-3)

## 步骤 1：设置权限
<a name="embedded-analytics-dashboards-with-anonymous-users-step-1"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在下节中，您可以了解如何设置后端应用程序或 Web 服务器的权限。该任务需要具有 IAM 的管理访问权限。

每个访问控制面板的用户都扮演一个角色，授予他们 Amazon Quick Sight 访问控制面板的权限和权限。要实现这一点，请在您的中创建一个 IAM 角色 AWS 账户。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。

您可以在 IAM 策略中创建一个条件，限制开发人员可以在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 参数中列出的域。`AllowedDomains` 参数是可选参数。作为开发者，它允许您选择覆盖在 “**管理 Amazon Quick Sight**” 菜单中配置的静态域。您最多可以列出三个可以访问生成的 URL 的域或子域。然后，此 URL 将嵌入您创建的网站。只有参数中列出的域才能访问嵌入式控制面板。如果没有此条件，则可以在 `AllowedDomains` 参数中列出互联网上的任何域。

要限制开发人员可用于此参数的域，请在 IAM 策略中添加一个 `AllowedEmbeddingDomains` 条件。有关该`AllowedDomains`参数的更多信息，请参阅 *Amazon Quick Sight API 参考[GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)*中的。

**IAM 条件运算符的安全最佳实践**  
配置不当的 IAM 条件运算符可能会允许未经授权地通过 URL 变体访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用`quicksight:AllowedEmbeddingDomains`条件密钥时，请使用条件运算符，允许特定域名或拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息，请参阅 [IAM 用户指南中的 IAM JSON 策略元素：条件运算符](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
许多不同的网址变体可以指向同一个资源。例如，以下 URLs 所有内容都解析为相同的内容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的策略使用不考虑这些 URL 变体的运算符，则攻击者可以通过提供等效的 URL 变体来绕过您的限制。  
您必须验证您的 IAM 策略是否使用了适当的条件运算符来防止绕过漏洞，并确保只有您的目标域才能访问您的嵌入式资源。

以下示例策略提供了可用于 `GenerateEmbedUrlForAnonymousUser` 的这些权限。要让这种方法发挥作用，您的 AWS 账户还需要会话包或会话容量定价。否则，当用户尝试访问控制面板时，会返回 `UnsupportedPricingPlanException` 错误。

您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，在用户访问您的应用程序时，您的应用程序可以代表用户代入该角色打开控制面板。下面演示了一个示例信任策略。

------
#### [ JSON ]

****  

```
{
"Version":"2012-10-17",		 	 	 
"Statement": [
    {
        "Sid": "AllowLambdaFunctionsToAssumeThisRole",
        "Effect": "Allow",
        "Principal": {
            "Service": "lambda.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
    },
    {
        "Sid": "AllowEC2InstancesToAssumeThisRole",
        "Effect": "Allow",
        "Principal": {
            "Service": "ec2.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
    }
]
}
```

------

有关信任策略的更多信息，请参阅《IAM 用户指南》**中的 [IAM 临时安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。

## 步骤 2：生成附带身份验证代码的 URL
<a name="embedded-analytics-dashboards-with-anonymous-users-step-2"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在下节中，您可以了解如何代表匿名访问者进行身份验证，并获取应用程序服务器上的可嵌入控制面板 URL。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，它会将该用户添加到 Amazon Quick Sight（如果该用户尚不存在）。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

以下示例展示了代表用户执行 IAM 身份验证。将标识符作为唯一角色会话 ID 进行传递。此代码在您的应用程序服务器上运行。

### Java
<a name="embedded-analytics-dashboards-with-anonymous-users-java"></a>

```
import java.util.List;
    import com.amazonaws.auth.AWSCredentials;
    import com.amazonaws.auth.AWSCredentialsProvider;
    import com.amazonaws.auth.BasicAWSCredentials;
    import com.amazonaws.regions.Regions;
    import com.amazonaws.services.quicksight.AmazonQuickSight;
    import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
    import com.amazonaws.services.quicksight.model.RegisteredUserDashboardEmbeddingConfiguration;
    import com.amazonaws.services.quicksight.model.AnonymousUserEmbeddingExperienceConfiguration;
    import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserRequest;
    import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserResult;
    import com.amazonaws.services.quicksight.model.SessionTag;


    /**
    * Class to call QuickSight AWS SDK to generate embed url for anonymous user.
    */
    public class GenerateEmbedUrlForAnonymousUserExample {

        private final AmazonQuickSight quickSightClient;

        public GenerateEmbedUrlForAnonymousUserExample() {
            quickSightClient = AmazonQuickSightClientBuilder
                .standard()
                .withRegion(Regions.US_EAST_1.getName())
                .withCredentials(new AWSCredentialsProvider() {
                        @Override
                        public AWSCredentials getCredentials() {
                            // provide actual IAM access key and secret key here
                            return new BasicAWSCredentials("access-key", "secret-key");
                        }

                        @Override
                        public void refresh() {
                        }
                    }
                )
                .build();
        }

        public String GenerateEmbedUrlForAnonymousUser(
            final String accountId, // YOUR AWS ACCOUNT ID
            final String initialDashboardId, // DASHBOARD ID TO WHICH THE CONSTRUCTED URL POINTS.
            final String namespace, // ANONYMOUS EMBEDDING REQUIRES SPECIFYING A VALID NAMESPACE FOR WHICH YOU WANT THE EMBEDDING URL
            final List<String> authorizedResourceArns, // DASHBOARD ARN LIST TO EMBED
            final List<String> allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
            final List<SessionTag> sessionTags // SESSION TAGS USED FOR ROW-LEVEL SECURITY
        ) throws Exception {
            AnonymousUserEmbeddingExperienceConfiguration experienceConfiguration = new AnonymousUserEmbeddingExperienceConfiguration();
            AnonymousUserDashboardEmbeddingConfiguration dashboardConfiguration = new AnonymousUserDashboardEmbeddingConfiguration();
            dashboardConfiguration.setInitialDashboardId(initialDashboardId);
            experienceConfiguration.setDashboard(dashboardConfiguration);

            GenerateEmbedUrlForAnonymousUserRequest generateEmbedUrlForAnonymousUserRequest = new GenerateEmbedUrlForAnonymousUserRequest()
                .withAwsAccountId(accountId)
                .withNamespace(namespace)
                .withAuthorizedResourceArns(authorizedResourceArns)
                .withExperienceConfiguration(experienceConfiguration)
                .withSessionTags(sessionTags)
                .withSessionLifetimeInMinutes(600L); // OPTIONAL: VALUE CAN BE [15-600]. DEFAULT: 600
                .withAllowedDomains(allowedDomains);

            GenerateEmbedUrlForAnonymousUserResult dashboardEmbedUrl = quickSightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserRequest);

            return dashboardEmbedUrl.getEmbedUrl();
        }

    }
```

### JavaScript
<a name="embedded-analytics-dashboards-with-anonymous-users-js"></a>

```
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function generateEmbedUrlForAnonymousUser(
accountId, // YOUR AWS ACCOUNT ID
initialDashboardId, // DASHBOARD ID TO WHICH THE CONSTRUCTED URL POINTS
quicksightNamespace, // VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
authorizedResourceArns, // DASHBOARD ARN LIST TO EMBED
allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
sessionTags, // SESSION TAGS USED FOR ROW-LEVEL SECURITY
generateEmbedUrlForAnonymousUserCallback, // GENERATEEMBEDURLFORANONYMOUSUSER SUCCESS CALLBACK METHOD
errorCallback // GENERATEEMBEDURLFORANONYMOUSUSER ERROR CALLBACK METHOD
) {
const experienceConfiguration = {
    "DashboardVisual": {
        "InitialDashboardVisualId": {
            "DashboardId": "dashboard_id",
            "SheetId": "sheet_id",
            "VisualId": "visual_id"
        }
    }
};

const generateEmbedUrlForAnonymousUserParams = {
    "AwsAccountId": accountId,
    "Namespace": quicksightNamespace,
    "AuthorizedResourceArns": authorizedResourceArns,
    "AllowedDomains": allowedDomains,
    "ExperienceConfiguration": experienceConfiguration,
    "SessionTags": sessionTags,
    "SessionLifetimeInMinutes": 600
};

const quicksightClient = new AWS.QuickSight({
    region: process.env.AWS_REGION,
    credentials: {
        accessKeyId: AccessKeyId,
        secretAccessKey: SecretAccessKey,
        sessionToken: SessionToken,
        expiration: Expiration
    }
});

quicksightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserParams, function(err, data) {
    if (err) {
        console.log(err, err.stack);
        errorCallback(err);
    } else {
        const result = {
            "statusCode": 200,
            "headers": {
                "Access-Control-Allow-Origin": "*", // USE YOUR WEBSITE DOMAIN TO SECURE ACCESS TO THIS API
                "Access-Control-Allow-Headers": "Content-Type"
            },
            "body": JSON.stringify(data),
            "isBase64Encoded": false
        }
        generateEmbedUrlForAnonymousUserCallback(result);
    }
});
}
```

### Python3
<a name="embedded-analytics-dashboards-with-anonymous-users-py"></a>

```
import json
import boto3
from botocore.exceptions import ClientError
import time

# Create QuickSight and STS clients
quicksightClient = boto3.client('quicksight',region_name='us-west-2')
sts = boto3.client('sts')

# Function to generate embedded URL for anonymous user
# accountId: YOUR AWS ACCOUNT ID
# quicksightNamespace: VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
# authorizedResourceArns: DASHBOARD ARN LIST TO EMBED
# allowedDomains: RUNTIME ALLOWED DOMAINS FOR EMBEDDING
# dashboardId: DASHBOARD ID TO WHICH THE CONSTRUCTED URL POINTS
# sessionTags: SESSION TAGS USED FOR ROW-LEVEL SECURITY
def generateEmbedUrlForAnonymousUser(accountId, quicksightNamespace, authorizedResourceArns, allowedDomains, dashboardId, sessionTags):
try:
    response = quicksightClient.generate_embed_url_for_anonymous_user(
        AwsAccountId = accountId,
        Namespace = quicksightNamespace,
        AuthorizedResourceArns = authorizedResourceArns,
        AllowedDomains = allowedDomains,
            ExperienceConfiguration = {
                "Dashboard": {
                    "InitialDashboardId": dashboardId
                }
            },
        SessionTags = sessionTags,
        SessionLifetimeInMinutes = 600
    )
        
    return {
        'statusCode': 200,
        'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
        'body': json.dumps(response),
        'isBase64Encoded':  bool('false')
    }
except ClientError as e:
    print(e)
    return "Error generating embeddedURL: " + str(e)
```

### Node.js
<a name="embedded-analytics-dashboards-with-anonymous-users-node"></a>

以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 URL 的 JavaScript (Node.js)。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
const AWS = require('aws-sdk');
    const https = require('https');

    var quicksightClient = new AWS.Service({
        apiConfig: require('./quicksight-2018-04-01.min.json'),
        region: 'us-east-1',
    });

    quicksightClient.generateEmbedUrlForAnonymousUser({
        'AwsAccountId': '111122223333',
        'Namespace' : 'default',
        'AuthorizedResourceArns': authorizedResourceArns,
        'AllowedDomains': allowedDomains,
        'ExperienceConfiguration': experienceConfiguration,
        'SessionTags': sessionTags,
        'SessionLifetimeInMinutes': 600

    }, function(err, data) {
        console.log('Errors: ');
        console.log(err);
        console.log('Response: ');
        console.log(data);
    });
```

**Example**  

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
    //readability and added ellipsis to indicate that it's incomplete.
        { 
            Status: 200,
            EmbedUrl: 'https://quicksightdomain/embed/12345/dashboards/67890..',
            RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' 
        }
```

### .NET/C\$1
<a name="embedded-analytics-dashboards-with-anonymous-users-cs"></a>

以下示例演示了可以在应用程序服务器上使用以生成嵌入式控制面板 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
using System;
    using Amazon.QuickSight;
    using Amazon.QuickSight.Model;

    var quicksightClient = new AmazonQuickSightClient(
        AccessKey,
        SecretAccessKey,
        sessionToken,
        Amazon.RegionEndpoint.USEast1);
        
    try
    {
        Console.WriteLine(
            quicksightClient.GenerateEmbedUrlForAnonymousUserAsync(new GenerateEmbedUrlForAnonymousUserRequest
            {
                AwsAccountId = "111122223333",
                Namespace = default,
                AuthorizedResourceArns = authorizedResourceArns,
                AllowedDomains = allowedDomains,
                ExperienceConfiguration = experienceConfiguration,
                SessionTags = sessionTags,
                SessionLifetimeInMinutes = 600,
            }).Result.EmbedUrl
        );
    } catch (Exception ex) {
        Console.WriteLine(ex.Message);
    }
```

### AWS CLI
<a name="embedded-analytics-dashboards-with-anonymous-users-cli"></a>

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用安全断言标记语言 (SAML) 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GenerateEmbedUrlForAnonymousUser` 启用权限。

```
aws sts assume-role \
    --role-arn "arn:aws:iam::11112222333:role/QuickSightEmbeddingAnonymousPolicy" \
    --role-session-name anonymous caller
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。如果使用的是 Microsoft Windows 计算机，请使用 `set` 而非 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
    export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
    export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_dashboard_role/QuickSightEmbeddingAnonymousPolicy`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个访问用户设置相应的权限。其还能让每个会话保持独立性和独特性。如果您使用一组 Web 服务器（例如用于负载平衡），并且会话重新连接到其他服务器，则会开始新的会话。

要获取控制面板的签名 URL，请从应用程序服务器中调用 `generate-embed-url-for-anynymous-user`。这会返回可嵌入的控制面板 URL。以下示例演示了如何使用服务器端调用为匿名访问您 Web 门户或应用程序的用户生成嵌入式控制面板的 URL。

```
aws quicksight generate-embed-url-for-anonymous-user \
--aws-account-id 111122223333 \
--namespace default-or-something-else \
--session-lifetime-in-minutes 15 \
--authorized-resource-arns '["dashboard-arn-1","dashboard-arn-2"]' \
--allowed-domains '["domain1","domain2"]' \
--session-tags '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]' \
--experience-configuration 'DashboardVisual={InitialDashboardVisualId={DashboardId=dashboard_id,SheetId=sheet_id,VisualId=visual_id}}'
```

有关使用此操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)。您可以在自己的代码中使用该 API 操作和其他操作。

## 步骤 3：嵌入控制面板 URL
<a name="embedded-analytics-dashboards-with-anonymous-users-step-3"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在下一节中，您可以了解如何使用 [Amazon Quick Sight Embedging SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 将第 2 步中的控制面板网址嵌入到您的网站或应用程序页面中。通过使用该开发工具包，您可以执行以下操作：
+ 将控制面板放在 HTML 页面上。
+ 将参数传递到控制面板。
+ 使用为应用程序自定义的消息处理错误状态。

调用 `GenerateEmbedUrlForAnynymousUser` API 操作生成可嵌入应用的 URL。该 URL 的有效期为 5 分钟，生成的会话的有效期为 10 个小时。该 API 操作为 URL 提供 `auth_code` 以启用单点登录会话。

下面显示了 `generate-embed-url-for-anynymous-user` 的示例响应：

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
        {
            "Status": "200",
            "EmbedUrl": "https://quicksightdomain/embed/12345/dashboards/67890..",
            "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
        }
```

使用 [Amazon Quick Sight Embedding SDK 或将此 URL 添加到 iframe 中，将此控制面板嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会随着窗口大小调整而改变视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制控制面板中的参数并接收有关页面加载完成和错误的回调。

要托管嵌入式控制面板的域必须位于*允许列表*（为您的 Quick 订阅批准的域的列表）中。这一要求可阻止未经批准的域托管嵌入式控制面板，从而保护您的数据。有关为嵌入式控制面板添加域名的更多信息，请参阅[允许使用 Amazon Quick Sight API 在运行时列出域名](https://docs.aws.amazon.com/quicksight/latest/user/embedding-run-time.html)。

以下示例演示了如何使用生成的 URL。此代码位于您的应用程序服务器上。

### SDK 2.0
<a name="embedded-analytics-dashboards-with-anonymous-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

<head>
    <title>Dashboard Embedding Example</title>
    <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
    <script type="text/javascript">
        const embedDashboard = async() => {
            const {
                createEmbeddingContext,
            } = QuickSightEmbedding;

            const embeddingContext = await createEmbeddingContext({
                onChange: (changeEvent, metadata) => {
                    console.log('Context received a change', changeEvent, metadata);
                },
            });

            const frameOptions = {
                url: '<YOUR_EMBED_URL>',
                container: '#experience-container',
                height: "700px",
                width: "1000px",
                onChange: (changeEvent, metadata) => {
                    switch (changeEvent.eventName) {
                        case 'FRAME_MOUNTED': {
                            console.log("Do something when the experience frame is mounted.");
                            break;
                        }
                        case 'FRAME_LOADED': {
                            console.log("Do something when the experience frame is loaded.");
                            break;
                        }
                    }
                },
            };

            const contentOptions = {
                parameters: [
                    {
                        Name: 'country',
                        Values: [
                            'United States'
                        ],
                    },
                    {
                        Name: 'states',
                        Values: [
                            'California',
                            'Washington'
                        ]
                    }
                ],
                locale: "en-US",
                sheetOptions: {
                    initialSheetId: '<YOUR_SHEETID>',
                    singleSheet: false,                        
                    emitSizeChangedEventOnSheetChange: false,
                },
                toolbarOptions: {
                    export: false,
                    undoRedo: false,
                    reset: false
                },
                attributionOptions: {
                    overlayContent: false,
                },
                onMessage: async (messageEvent, experienceMetadata) => {
                    switch (messageEvent.eventName) {
                        case 'CONTENT_LOADED': {
                            console.log("All visuals are loaded. The title of the document:", messageEvent.message.title);
                            break;
                        }
                        case 'ERROR_OCCURRED': {
                            console.log("Error occurred while rendering the experience. Error code:", messageEvent.message.errorCode);
                            break;
                        }
                        case 'PARAMETERS_CHANGED': {
                            console.log("Parameters changed. Changed parameters:", messageEvent.message.changedParameters);
                            break;
                        }
                        case 'SELECTED_SHEET_CHANGED': {
                            console.log("Selected sheet changed. Selected sheet:", messageEvent.message.selectedSheet);
                            break;
                        }
                        case 'SIZE_CHANGED': {
                            console.log("Size changed. New dimensions:", messageEvent.message);
                            break;
                        }
                        case 'MODAL_OPENED': {
                            window.scrollTo({
                                top: 0 // iframe top position
                            });
                            break;
                        }
                    }
                },
            };
            const embeddedDashboardExperience = await embeddingContext.embedDashboard(frameOptions, contentOptions);

            const selectCountryElement = document.getElementById('country');
            selectCountryElement.addEventListener('change', (event) => {
                embeddedDashboardExperience.setParameters([
                    {
                        Name: 'country',
                        Values: event.target.value
                    }
                ]);
            });
        };
    </script>
</head>

<body onload="embedDashboard()">
    <span>
        <label for="country">Country</label>
        <select id="country" name="country">
            <option value="United States">United States</option>
            <option value="Mexico">Mexico</option>
            <option value="Canada">Canada</option>
        </select>
    </span>
    <div id="experience-container"></div>
</body>

</html>
```

### SDK 1.0
<a name="embedded-analytics-dashboards-with-anonymous-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

<head>
    <title>Basic Embed</title>
    <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.0.15/dist/quicksight-embedding-js-sdk.min.js"></script>
    <script type="text/javascript">
        var dashboard
        function onDashboardLoad(payload) {
            console.log("Do something when the dashboard is fully loaded.");
        }

        function onError(payload) {
            console.log("Do something when the dashboard fails loading");
        }

        function embedDashboard() {
            var containerDiv = document.getElementById("embeddingContainer");
            var options = {
                // replace this dummy url with the one generated via embedding API
                url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",
                container: containerDiv,
                parameters: {
                    country: "United States"
                },
                scrolling: "no",
                height: "700px",
                width: "1000px",
                locale: "en-US",
                footerPaddingEnabled: true
            };
            dashboard = QuickSightEmbedding.embedDashboard(options);
            dashboard.on("error", onError);
            dashboard.on("load", onDashboardLoad);
        }

        function onCountryChange(obj) {
            dashboard.setParameters({country: obj.value});
        }
    </script>
</head>

<body onload="embedDashboard()">
    <span>
        <label for="country">Country</label>
        <select id="country" name="country" onchange="onCountryChange(this)">
            <option value="United States">United States</option>
            <option value="Mexico">Mexico</option>
            <option value="Canada">Canada</option>
        </select>
    </span>
    <div id="embeddingContainer"></div>
</body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 将嵌入式控制面板加载到您的网站上 JavaScript。要获取副本，请执行下列操作之一：
+ 从 GitHub中下载 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) 该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从中下载最新的 Amazon Quick Sight Embedgin [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)g S
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

# 在嵌入式控制面板中启用执行摘要
<a name="embedded-analytics-genbi-executive-summaries-dashboard"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

您可以在嵌入式控制面板中启用执行摘要。启用后，注册用户可以生成执行摘要，摘要提供 Amazon Quick Sight 为控制面板生成的所有见解的摘要。执行摘要使读者更容易找到有关控制面板的关键见解和信息。有关用户如何生成控制面板执行摘要的更多信息，请参阅生成 [Amazon Quick Sight 控制面板的执行摘要](https://docs.aws.amazon.com/quicksight/latest/user/use-executive-summaries.html)。

**注意**  
执行摘要仅在注册用户的嵌入式控制面板中可用，并且无法在匿名或未注册用户的嵌入式控制面板中启用。

**为注册用户启用嵌入式控制面板中的执行摘要**
+ 按照[嵌入 Amazon Quick Sight 控制面板中的步骤，注册用户可以](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics-dashboards-for-authenticated-users.html)嵌入包含以下更改的控制面板：

  1. 在步骤 2 中生成 URL 时，`Enabled: true`请在[GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)或的`ExecutiveSummary`参数中进行设置 [GenerateEmbedUrlForRegisteredUserWithIdentity](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUserWithIdentity.html)，如以下示例所示：

     ```
     ExperienceConfiguration: {
             Dashboard: {
                 InitialDashboardId: dashboard_id,
                 FeatureConfigurations: {
                     AmazonQInQuickSight: {
                         ExecutiveSummary: {
                             Enabled: true
                         }
                     }
                 }
             }
         }
     }
     ```

  1. 在步骤 3 中使用 Amazon Quick Sight Embedding SDK 嵌入控制面板 URL 时`contentOptions`，请在中进行设置`executiveSummary: true`，如以下示例所示：

     ```
     const contentOptions = {
         toolbarOptions: {
             executiveSummary: true
         }
     };
     ```

# 将 Amazon Quick Sight 视觉效果嵌入到亚马逊快速瞄准器中 APIs
<a name="embedding-visuals"></a>

您可以使用 Amazon Quick Sight API 将作为已发布控制面板一部分的单个视觉效果嵌入到您的应用程序中。

**Topics**
+ [

# 为注册用户嵌入 Amazon Quick Sight 视觉效果
](embedded-analytics-visuals-for-authenticated-users.md)
+ [

# 为匿名（未注册）用户嵌入 Amazon Quick Sight 视觉效果
](embedded-analytics-visuals-for-everyone.md)

# 为注册用户嵌入 Amazon Quick Sight 视觉效果
<a name="embedded-analytics-visuals-for-authenticated-users"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在以下各节中，您可以找到有关如何为 Amazon Quick Sight 的注册用户设置嵌入式 Amazon Quick Sight 视觉效果的详细信息。

**Topics**
+ [

## 步骤 1：设置权限
](#embedded-visuals-for-authenticated-users-step-1)
+ [

## 步骤 2：生成附带身份验证代码的 URL
](#embedded-visuals-for-authenticated-users-step-2)
+ [

## 步骤 3：嵌入视觉对象 URL
](#embedded-visuals-for-authenticated-users-step-3)

## 步骤 1：设置权限
<a name="embedded-visuals-for-authenticated-users-step-1"></a>

在下节中，您可以了解如何设置后端应用程序或 Web 服务器的权限。该任务需要具有 IAM 的管理访问权限。

每个访问视觉对象的用户都扮演一个角色，该角色授予他们 Amazon Quick Sight 访问该视觉对象的权限和权限。要实现这一点，请在您的中创建一个 IAM 角色 AWS 账户。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。IAM 角色需要提供权限才能检索特定用户池 URLs 的嵌入内容。借助通配符 *\$1*，您可以授予为特定命名空间中的所有用户部分用户生成 URL 的权限。为此，请添加 `quicksight:GenerateEmbedUrlForRegisteredUser`。

您可以在 IAM 策略中创建一个条件，限制开发人员可以在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 参数中列出的域。`AllowedDomains` 参数是可选参数。作为开发者，它允许您选择覆盖在 “**管理 Amazon Quick Sight**” 菜单中配置的静态域。您最多可以列出三个可以访问生成的 URL 的域或子域。然后，此 URL 将嵌入您创建的网站。只有参数中列出的域才能访问嵌入式控制面板。如果没有此条件，则可以在 `AllowedDomains` 参数中列出互联网上的任何域。

要限制开发人员可用于此参数的域，请在 IAM 策略中添加一个 `AllowedEmbeddingDomains` 条件。有关该`AllowedDomains`参数的更多信息，请参阅 *Amazon Quick Sight API 参考[GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)*中的。

**IAM 条件运算符的安全最佳实践**  
配置不当的 IAM 条件运算符可能会允许未经授权地通过 URL 变体访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用`quicksight:AllowedEmbeddingDomains`条件密钥时，请使用条件运算符，允许特定域名或拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息，请参阅 [IAM 用户指南中的 IAM JSON 策略元素：条件运算符](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
许多不同的网址变体可以指向同一个资源。例如，以下 URLs 所有内容都解析为相同的内容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的策略使用的运算符不考虑这些 URL 变体，则攻击者可以通过提供等效的 URL 变体来绕过您的限制。  
您必须验证您的 IAM 策略是否使用了适当的条件运算符来防止绕过漏洞，并确保只有您的目标域才能访问您的嵌入式资源。

以下示例策略提供了这些权限。

此外，如果您要创建将成为 Amazon Quick Sight 读者的首次用户，请务必在策略中添加`quicksight:RegisterUser`权限。

以下示例策略为即将成为 Amazon Quick Sight 读者的首次用户提供了检索嵌入网址的权限。

最后，您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，当用户访问您的应用程序时，您的应用程序可以代表用户担任该角色并在 Amazon Quick Sight 中配置用户。下面演示了一个示例信任策略。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowLambdaFunctionsToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        {
            "Sid": "AllowEC2InstancesToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

------

有关 OpenId Connect 或 SAML 身份验证的信任策略的更多信息，请参阅 *IAM 用户指南* 的以下部分：
+ [创建用于 Web 联合身份验证或 OpenID Connect 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [创建用于 SAML 2.0 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

## 步骤 2：生成附带身份验证代码的 URL
<a name="embedded-visuals-for-authenticated-users-step-2"></a>

在下一节中，您可以了解如何对您的 Amazon Quick Sight 用户进行身份验证，并在应用程序服务器上获取可嵌入的可视化 URL。如果您计划为 IAM 或 Amazon Quick Sight 身份类型嵌入视觉效果，请与 Amazon Quick Sight 用户共享视觉效果。

当 Amazon Quick Sight 用户访问您的应用程序时，该应用程序将代表亚马逊 Quick Sight 用户担任 IAM 角色。然后，它会将该用户添加到 Amazon Quick Sight 中，前提是该 Amazon Quick Sight 用户还不存在。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

执行上述步骤可确保视觉对象的每位查看者在 Amazon Quick Sight 中获得唯一配置。它还实施每个用户的设置，例如，行级别安全性和参数的动态默认值。

以下示例代表 Amazon Quick Sight 用户执行 IAM 身份验证。此代码在您的应用程序服务器上运行。

### Java
<a name="embedded-visuals-for-authenticated-users-java"></a>

```
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.DashboardVisualId;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserResult;
import com.amazonaws.services.quicksight.model.RegisteredUserDashboardVisualEmbeddingConfiguration;
import com.amazonaws.services.quicksight.model.RegisteredUserEmbeddingExperienceConfiguration;

import java.util.List;

/**
 * Class to call QuickSight AWS SDK to get url for Visual embedding.
 */
public class GenerateEmbedUrlForRegisteredUserTest {

    private final AmazonQuickSight quickSightClient;

    public GenerateEmbedUrlForRegisteredUserTest() {
        this.quickSightClient = AmazonQuickSightClientBuilder
            .standard()
            .withRegion(Regions.US_EAST_1.getName())
            .withCredentials(new AWSCredentialsProvider() {
                    @Override
                    public AWSCredentials getCredentials() {
                        // provide actual IAM access key and secret key here
                        return new BasicAWSCredentials("access-key", "secret-key");
                    }

                    @Override
                    public void refresh() {                        
                    }
                }
            )
            .build();
    }

    public String getEmbedUrl(
            final String accountId, // AWS Account ID
            final String dashboardId, // Dashboard ID of the dashboard to embed
            final String sheetId, // Sheet ID of the sheet to embed
            final String visualId, // Visual ID of the visual to embed
            final List<String> allowedDomains, // Runtime allowed domains for embedding
            final String userArn // Registered user arn of the user that you want to provide embedded visual. Refer to Get Embed Url section in developer portal to find out how to get user arn for a QuickSight user.
    ) throws Exception {
        final DashboardVisualId dashboardVisual = new DashboardVisualId()
            .withDashboardId(dashboardId)
            .withSheetId(sheetId)
            .withVisualId(visualId);
        final RegisteredUserDashboardVisualEmbeddingConfiguration registeredUserDashboardVisualEmbeddingConfiguration
            = new RegisteredUserDashboardVisualEmbeddingConfiguration()
                .withInitialDashboardVisualId(dashboardVisual);
        final RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
            = new RegisteredUserEmbeddingExperienceConfiguration()
                .withDashboardVisual(registeredUserDashboardVisualEmbeddingConfiguration);
        final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest
            = new GenerateEmbedUrlForRegisteredUserRequest()
                .withAwsAccountId(accountId)
                .withUserArn(userArn)
                .withExperienceConfiguration(registeredUserEmbeddingExperienceConfiguration)
                .withAllowedDomains(allowedDomains);

        final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);

        return generateEmbedUrlForRegisteredUserResult.getEmbedUrl();
    }
}
```

### JavaScript
<a name="embedded-visuals-for-authenticated-users-js"></a>

```
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function generateEmbedUrlForRegisteredUser(
    accountId, // Your AWS account ID
    dashboardId, // Dashboard ID to which the constructed URL points
    sheetId, // Sheet ID to which the constructed URL points
    visualId, // Visual ID to which the constructed URL points
    openIdToken, // Cognito-based token
    userArn, // registered user arn
    roleArn, // IAM user role to use for embedding
    sessionName, // Session name for the roleArn assume role
    allowedDomains, // Runtime allowed domain for embedding
    getEmbedUrlCallback, // GetEmbedUrl success callback method
    errorCallback // GetEmbedUrl error callback method
    ) {
    const stsClient = new AWS.STS();
    let stsParams = {
        RoleSessionName: sessionName,
        WebIdentityToken: openIdToken,
        RoleArn: roleArn
    }

    stsClient.assumeRoleWithWebIdentity(stsParams, function(err, data) {
        if (err) {
            console.log('Error assuming role');
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const getDashboardParams = {
                "AwsAccountId": accountId,
                "ExperienceConfiguration": {
                    "DashboardVisual": {
                        "InitialDashboardVisualId": {
                            "DashboardId": dashboardId,
                            "SheetId": sheetId,
                            "VisualId": visualId
                        }
                    }
                },
                "UserArn": userArn,
                "AllowedDomains": allowedDomains,
                "SessionLifetimeInMinutes": 600
            };

            const quicksightGetDashboard = new AWS.QuickSight({
                region: process.env.AWS_REGION,
                credentials: {
                    accessKeyId: data.Credentials.AccessKeyId,
                    secretAccessKey: data.Credentials.SecretAccessKey,
                    sessionToken: data.Credentials.SessionToken,
                    expiration: data.Credentials.Expiration
                }
            });

            quicksightGetDashboard.generateEmbedUrlForRegisteredUser(getDashboardParams, function(err, data) {
                if (err) {
                    console.log(err, err.stack);
                    errorCallback(err);
                } else {
                    const result = {
                        "statusCode": 200,
                        "headers": {
                            "Access-Control-Allow-Origin": "*", // Use your website domain to secure access to GetEmbedUrl API
                            "Access-Control-Allow-Headers": "Content-Type"
                        },
                        "body": JSON.stringify(data),
                        "isBase64Encoded": false
                    }
                    getEmbedUrlCallback(result);
                }
            });
        }
    });
}
```

### Python3
<a name="embedded-visuals-for-authenticated-users-py"></a>

```
import json
import boto3
from botocore.exceptions import ClientError

sts = boto3.client('sts')

# Function to generate embedded URL  
# accountId: AWS account ID
# dashboardId: Dashboard ID to embed
# sheetId: SHEET ID to embed from the dashboard 
# visualId: Id for the Visual you want to embedded from the dashboard sheet. 
# userArn: arn of registered user
# allowedDomains: Runtime allowed domain for embedding
# roleArn: IAM user role to use for embedding
# sessionName: session name for the roleArn assume role
def getEmbeddingURL(accountId, dashboardId, sheetId, visualId, userArn, allowedDomains, roleArn, sessionName):
    try:
        assumedRole = sts.assume_role(
            RoleArn = roleArn,
            RoleSessionName = sessionName,
        )
    except ClientError as e:
        return "Error assuming role: " + str(e)
    else: 
        assumedRoleSession = boto3.Session(
            aws_access_key_id = assumedRole['Credentials']['AccessKeyId'],
            aws_secret_access_key = assumedRole['Credentials']['SecretAccessKey'],
            aws_session_token = assumedRole['Credentials']['SessionToken'],
        )
        try:
            quicksightClient = assumedRoleSession.client('quicksight', region_name='us-west-2')
            response = quicksightClient.generate_embed_url_for_registered_user(
                AwsAccountId=accountId,
                ExperienceConfiguration = {
                    'DashboardVisual': {
                        'InitialDashboardVisualId': {
                            'DashboardId': dashboardId,
                            'SheetId': sheetId,
                            'VisualId': visualId
                        }
                    },
                },
                UserArn = userArn,
                AllowedDomains = allowedDomains,
                SessionLifetimeInMinutes = 600
            )
            
            return {
                'statusCode': 200,
                'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
                'body': json.dumps(response),
                'isBase64Encoded':  bool('false')
            }
        except ClientError as e:
            return "Error generating embedding url: " + str(e)
```

### Node.js
<a name="embedded-visuals-for-authenticated-users-node"></a>

以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 URL 的 JavaScript (Node.js)。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
const AWS = require('aws-sdk');
const https = require('https');

var quicksightClient = new AWS.Service({
    apiConfig: require('./quicksight-2018-04-01.min.json'),
    region: 'us-east-1',
});

quicksightClient.generateEmbedUrlForRegisteredUser({
    'AwsAccountId': '111122223333',
    'ExperienceConfiguration': { 
        'DashboardVisual': {
            'InitialDashboardVisualId': {
                'DashboardId': 'dashboard_id',
                'SheetId': 'sheet_id',
                'VisualId': 'visual_id'
            }
        }
    },
    'UserArn': 'REGISTERED_USER_ARN',
    'AllowedDomains': allowedDomains,
    'SessionLifetimeInMinutes': 100
}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

**Example**  

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
    {
        "Status": "200",
        "EmbedUrl": "https://quicksightdomain/embed/12345/dashboards/67890/sheets/12345/visuals/67890...",
        "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
    }
```

### .NET/C\$1
<a name="embedded-visuals-for-authenticated-users-cs"></a>

以下示例演示了可以在应用程序服务器上使用以生成嵌入式控制面板 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
using System;
using Amazon.QuickSight;
using Amazon.QuickSight.Model;

namespace GenerateDashboardEmbedUrlForRegisteredUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                DashboardVisualId dashboardVisual = new DashboardVisualId
                {
                    DashboardId = "dashboard_id",
                    SheetId = "sheet_id",
                    VisualId = "visual_id"
                };

                RegisteredUserDashboardVisualEmbeddingConfiguration registeredUserDashboardVisualEmbeddingConfiguration
                    = new RegisteredUserDashboardVisualEmbeddingConfiguration
                    {
                        InitialDashboardVisualId = dashboardVisual                        
                    };               
                    
                RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                    = new RegisteredUserEmbeddingExperienceConfiguration
                    {
                        DashboardVisual = registeredUserDashboardVisualEmbeddingConfiguration
                    };
                    
                Console.WriteLine(
                    quicksightClient.GenerateEmbedUrlForRegisteredUserAsync(new GenerateEmbedUrlForRegisteredUserRequest
                    {
                        AwsAccountId = "111122223333",
                        ExperienceConfiguration = registeredUserEmbeddingExperienceConfiguration,
                        UserArn = "REGISTERED_USER_ARN",
                        AllowedDomains = allowedDomains,
                        SessionLifetimeInMinutes = 100
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
```

### AWS CLI
<a name="embedded-visuals-for-authenticated-users-cli"></a>

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用 SAML 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GenerateEmbedUrlForRegisteredUser` 启用权限。如果您采用一种在用户首次打开仪表板时添加用户的 just-in-time方法，则该角色还需要为其启用权限`quicksight:RegisterUser`。

```
aws sts assume-role \
    --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_visual_role" \
    --role-session-name john.doe@example.com
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。如果使用的是 Microsoft Windows 计算机，请使用 `set` 而非 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
    export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
    export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_visual_role/john.doe@example.com`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个用户设置相应的权限。此外，它还能避免任何用户访问限制。*限制*是一项安全功能，可防止同一个用户从多个位置访问 Amazon Quick Sight。

角色会话 ID 也将成为 Amazon Quick Sight 中的用户名。您可以使用此模式提前在 Amazon Quick Sight 中配置用户，或者在他们首次访问控制面板时对其进行配置。

以下示例显示了可用于预置用户的 CLI 命令。有关[RegisterUser[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html)](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、和其他 Amazon Quick Sight API 操作的更多信息，请参阅[亚马逊 Quick Sight API 参考](https://docs.aws.amazon.com/quicksight/latest/APIReference/Welcome.html)。

```
aws quicksight register-user \
    --aws-account-id 111122223333 \
    --namespace default \
    --identity-type IAM \
    --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_visual_role" \
    --user-role READER \
    --user-name jhnd \
    --session-name "john.doe@example.com" \
    --email john.doe@example.com \
    --region us-east-1 \
    --custom-permissions-name TeamA1
```

如果用户通过 Microsoft AD 进行身份验证，则无需使用 `RegisterUser` 进行设置。相反，他们应该在首次访问 Amazon Quick Sight 时自动订阅。对于 Microsoft AD 用户，您可以使用 `DescribeUser` 获取用户 ARN。

用户首次访问 Amazon Quick Sight 时，您也可以将该用户添加到与之共享视觉对象的群组中。以下示例显示了将用户添加到组的 CLI 命令。

```
aws quicksight create-group-membership \
    --aws-account-id=111122223333 \
    --namespace=default \
    --group-name=financeusers \
    --member-name="embedding_quicksight_visual_role/john.doe@example.com"
```

现在，您的应用程序的用户也是 Amazon Quick Sight 的用户，并且可以访问视觉对象。

最后，要获取视觉对象的签名 URL，请从应用服务器中调用 `generate-embed-url-for-registered-user`。这会返回可嵌入视觉对象 URL。以下示例说明如何使用服务器端调用为通过身份验证 AWS Managed Microsoft AD 或单点登录（IAM Identity Center）进行身份验证的用户生成嵌入式视觉对象的 URL。

```
aws quicksight generate-embed-url-for-registered-user \
    --aws-account-id 111122223333 \
    --session-lifetime-in-minutes 600 \
    --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_visual_role/embeddingsession \
    --allowed-domains '["domain1","domain2"]' \
    --experience-configuration 'DashboardVisual={InitialDashboardVisualId={DashboardId=dashboard_id,SheetId=sheet_id,VisualId=visual_id}}'
```

有关使用此操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在自己的代码中使用该 API 操作和其他操作。

## 步骤 3：嵌入视觉对象 URL
<a name="embedded-visuals-for-authenticated-users-step-3"></a>

在下一节中，您可以了解如何使用 [Amazon Quick Sight Embedging SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 将第 3 步中的可视网址嵌入到您的网站或应用程序页面中。通过使用该开发工具包，您可以执行以下操作：
+ 将视觉对象置于 HTML 页面上。
+ 将参数传入视觉对象。
+ 使用为应用程序自定义的消息处理错误状态。

调用 `GenerateEmbedUrlForRegisteredUser` API 操作生成可嵌入应用的 URL。该 URL 的有效时间为 5 分钟，生成的会话有效时间为 10 个小时。该 API 操作为 URL 提供 `auth_code` 以启用单点登录会话。

下面显示了 `generate-embed-url-for-registered-user` 的示例响应：此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
    {
        "Status": "200",
        "EmbedUrl": "https://quicksightdomain/embed/12345/dashboards/67890/sheets/12345/visuals/67890...",
        "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
    }
```

使用 [Amazon Quick Sight Embedding SDK 或将此 URL 添加到 iframe 中，将此视觉效果嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会在窗口大小调整时更改视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制视觉对象中的参数并接收有关页面加载完成和错误的回调。

要托管嵌入式视觉对象和仪表板的域名必须位于*允许列表中*，即允许订 Quick 阅的域名列表。这一要求可阻止未经批准的域托管嵌入式视觉对象和控制面板，从而保护您的数据。有关为嵌入式视觉对象和控制面板添加域名的更多信息，请参阅[允许使用 Amazon Quick Sight API 在运行时列出域名](https://docs.aws.amazon.com/quicksight/latest/user/embedding-run-time.html)。

以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。

### SDK 2.0
<a name="embedded-visuals-for-authenticated-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Visual Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedVisual = async() => {    
                const {
                    createEmbeddingContext,
                } = QuickSightEmbedding;

                const embeddingContext = await createEmbeddingContext({
                    onChange: (changeEvent, metadata) => {
                        console.log('Context received a change', changeEvent, metadata);
                    },
                });

                const frameOptions = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: '#experience-container',
                    height: "700px",
                    width: "1000px",
                    onChange: (changeEvent, metadata) => {
                        switch (changeEvent.eventName) {
                            case 'FRAME_MOUNTED': {
                                console.log("Do something when the experience frame is mounted.");
                                break;
                            }
                            case 'FRAME_LOADED': {
                                console.log("Do something when the experience frame is loaded.");
                                break;
                            }
                        }
                    },
                };

                const contentOptions = {
                    parameters: [
                        {
                            Name: 'country',
                            Values: ['United States'],
                        },
                        {
                            Name: 'states',
                            Values: [
                                'California',
                                'Washington'
                            ]
                        }
                    ],
                    locale: "en-US",
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'CONTENT_LOADED': {
                                console.log("All visuals are loaded. The title of the document:", messageEvent.message.title);
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Error occurred while rendering the experience. Error code:", messageEvent.message.errorCode);
                                break;
                            }
                            case 'PARAMETERS_CHANGED': {
                                console.log("Parameters changed. Changed parameters:", messageEvent.message.changedParameters);
                                break;
                            }
                            case 'SIZE_CHANGED': {
                                console.log("Size changed. New dimensions:", messageEvent.message);
                                break;
                            }
                        }
                    },
                };
                const embeddedVisualExperience = await embeddingContext.embedVisual(frameOptions, contentOptions);

                const selectCountryElement = document.getElementById('country');
                selectCountryElement.addEventListener('change', (event) => {
                    embeddedVisualExperience.setParameters([
                        {
                            Name: 'country',
                            Values: event.target.value
                        }
                    ]);
                });
            };
        </script>
    </head>

    <body onload="embedVisual()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="experience-container"></div>
    </body>

</html>
```

### SDK 1.0
<a name="embedded-visuals-for-authenticated-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Visual Embedding Example</title>
        <!-- You can download the latest QuickSight embedding SDK version from https://www.npmjs.com/package/amazon-quicksight-embedding-sdk -->
        <!-- Or you can do "npm install amazon-quicksight-embedding-sdk", if you use npm for javascript dependencies -->
        <script src="./quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            let embeddedVisualExperience;
            function onVisualLoad(payload) {
                console.log("Do something when the visual is fully loaded.");
            }

            function onError(payload) {
                console.log("Do something when the visual fails loading");
            }

            function embedVisual() {
                const containerDiv = document.getElementById("embeddingContainer");
                const options = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: containerDiv,
                    parameters: {
                        country: "United States"
                    },
                    height: "700px",
                    width: "1000px",
                    locale: "en-US"
                };
                embeddedVisualExperience = QuickSightEmbedding.embedVisual(options);
                embeddedVisualExperience.on("error", onError);
                embeddedVisualExperience.on("load", onVisualLoad);
            }

            function onCountryChange(obj) {
                embeddedVisualExperience.setParameters({country: obj.value});
            }
        </script>
    </head>

    <body onload="embedVisual()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country" onchange="onCountryChange(this)">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="embeddingContainer"></div>
    </body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 将嵌入式视觉效果加载到您的网站上 JavaScript。要获取副本，请执行下列操作之一：
+ 从 GitHub中下载 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) 该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

# 为匿名（未注册）用户嵌入 Amazon Quick Sight 视觉效果
<a name="embedded-analytics-visuals-for-everyone"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在以下各节中，您可以找到有关如何为匿名（未注册）用户设置嵌入式 Amazon Quick Sight 视觉效果的详细信息。

**Topics**
+ [

## 步骤 1：设置权限
](#embedded-analytics-visuals-with-anonymous-users-step-1)
+ [

## 步骤 2：生成附带身份验证代码的 URL
](#embedded-analytics-visuals-with-anonymous-users-step-2)
+ [

## 步骤 3：嵌入视觉对象 URL
](#embedded-analytics-visuals-with-anonymous-users-step-3)

## 步骤 1：设置权限
<a name="embedded-analytics-visuals-with-anonymous-users-step-1"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在下节中，您可以了解如何设置后端应用程序或 Web 服务器的权限。该任务需要具有 IAM 的管理访问权限。

每个访问视觉对象的用户都扮演一个角色，该角色授予他们 Amazon Quick Sight 访问该视觉对象的权限和权限。要实现这一点，请在您的中创建一个 IAM 角色 AWS 账户。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。

您可以在 IAM 策略中创建一个条件，限制开发人员可以在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 参数中列出的域。`AllowedDomains` 参数是可选参数。作为开发者，它允许您选择覆盖在 “**管理 Amazon Quick Sight**” 菜单中配置的静态域。您最多可以列出三个可以访问生成的 URL 的域或子域。然后，此 URL 将嵌入您创建的网站。只有参数中列出的域才能访问嵌入式控制面板。如果没有此条件，则可以在 `AllowedDomains` 参数中列出互联网上的任何域。

要限制开发人员可用于此参数的域，请在 IAM 策略中添加一个 `AllowedEmbeddingDomains` 条件。有关该`AllowedDomains`参数的更多信息，请参阅 *Amazon Quick Sight API 参考[GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)*中的。

**IAM 条件运算符的安全最佳实践**  
配置不当的 IAM 条件运算符可能会允许未经授权地通过 URL 变体访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用`quicksight:AllowedEmbeddingDomains`条件密钥时，请使用条件运算符，允许特定域名或拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息，请参阅 [IAM 用户指南中的 IAM JSON 策略元素：条件运算符](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
许多不同的网址变体可以指向同一个资源。例如，以下 URLs 所有内容都解析为相同的内容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的策略使用的运算符不考虑这些 URL 变体，则攻击者可以通过提供等效的 URL 变体来绕过您的限制。  
您必须验证您的 IAM 策略是否使用了适当的条件运算符来防止绕过漏洞，并确保只有您的目标域才能访问您的嵌入式资源。

您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，在用户访问您的应用程序时，您的应用程序可以代表用户代入该角色打开视觉对象。下面演示了一个示例信任策略。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowLambdaFunctionsToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        {
            "Sid": "AllowEC2InstancesToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

------

有关信任策略的更多信息，请参阅《IAM 用户指南》**中的 [IAM 临时安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。

## 步骤 2：生成附带身份验证代码的 URL
<a name="embedded-analytics-visuals-with-anonymous-users-step-2"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在下节中，您可以了解如何代表匿名访问者进行身份验证，并获取应用程序服务器上的可嵌入视觉对象 URL。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，它会将该用户添加到 Amazon Quick Sight（如果该用户尚不存在）。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

以下示例展示了代表用户执行 IAM 身份验证。将标识符作为唯一角色会话 ID 进行传递。此代码在您的应用程序服务器上运行。

### Java
<a name="embedded-analytics-visuals-with-anonymous-users-java"></a>

```
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.AnonymousUserDashboardVisualEmbeddingConfiguration;
import com.amazonaws.services.quicksight.model.AnonymousUserEmbeddingExperienceConfiguration;
import com.amazonaws.services.quicksight.model.DashboardVisualId;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserResult;
import com.amazonaws.services.quicksight.model.SessionTag;

import java.util.List;

/**
 * Class to call QuickSight AWS SDK to get url for Visual embedding.
 */
public class GenerateEmbedUrlForAnonymousUserTest {
    private final AmazonQuickSight quickSightClient;

    public GenerateEmbedUrlForAnonymousUserTest() {
        this.quickSightClient = AmazonQuickSightClientBuilder
            .standard()
            .withRegion(Regions.US_EAST_1.getName())
            .withCredentials(new AWSCredentialsProvider() {
                    @Override
                    public AWSCredentials getCredentials() {
                        // provide actual IAM access key and secret key here
                        return new BasicAWSCredentials("access-key", "secret-key");
                    }

                    @Override
                    public void refresh() {                           
                    }
                }
            )
            .build();
    }

    public String getEmbedUrl(
            final String accountId, // AWS Account ID
            final String namespace, // Anonymous embedding required specifying a valid namespace for which you want the enbedding URL
            final List<String> authorizedResourceArns, // Dashboard arn list of dashboard visuals to embed
            final String dashboardId, // Dashboard ID of the dashboard to embed
            final String sheetId, // Sheet ID of the sheet to embed
            final String visualId, // Visual ID of the visual to embed
            final List<String> allowedDomains, // Runtime allowed domains for embedding
            final List<SessionTag> sessionTags // Session tags used for row-level security
    ) throws Exception {
        final DashboardVisualId dashboardVisual = new DashboardVisualId()
            .withDashboardId(dashboardId)
            .withSheetId(sheetId)
            .withVisualId(visualId);
        final AnonymousUserDashboardVisualEmbeddingConfiguration anonymousUserDashboardVisualEmbeddingConfiguration
            = new AnonymousUserDashboardVisualEmbeddingConfiguration()
                .withInitialDashboardVisualId(dashboardVisual);
        final AnonymousUserEmbeddingExperienceConfiguration anonymousUserEmbeddingExperienceConfiguration
            = new AnonymousUserEmbeddingExperienceConfiguration()
                .withDashboardVisual(anonymousUserDashboardVisualEmbeddingConfiguration);
        final GenerateEmbedUrlForAnonymousUserRequest generateEmbedUrlForAnonymousUserRequest
            = new GenerateEmbedUrlForAnonymousUserRequest()
                .withAwsAccountId(accountId)
                .withNamespace(namespace)
                // authorizedResourceArns should contain ARN of dashboard used below in ExperienceConfiguration
                .withAuthorizedResourceArns(authorizedResourceArns)
                .withExperienceConfiguration(anonymousUserEmbeddingExperienceConfiguration)
                .withAllowedDomains(allowedDomains)
                .withSessionTags(sessionTags)
                .withSessionLifetimeInMinutes(600L);

        final GenerateEmbedUrlForAnonymousUserResult generateEmbedUrlForAnonymousUserResult
            = quickSightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserRequest);

        return generateEmbedUrlForAnonymousUserResult.getEmbedUrl();
    }
}
```

### JavaScript
<a name="embedded-analytics-visuals-with-anonymous-users-js"></a>

```
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function generateEmbedUrlForAnonymousUser(
    accountId, // Your AWS account ID
    dashboardId, // Dashboard ID to which the constructed url points
    sheetId, // Sheet ID to which the constructed url points
    visualId, // Visual ID to which the constructed url points
    quicksightNamespace, // valid namespace where you want to do embedding
    authorizedResourceArns, // dashboard arn list of dashboard visuals to embed
    allowedDomains, // runtime allowed domains for embedding
    sessionTags, // session tags used for row-level security
    generateEmbedUrlForAnonymousUserCallback, // success callback method
    errorCallback // error callback method
    ) {
    const experienceConfiguration = {
        "DashboardVisual": {
            "InitialDashboardVisualId": {
                "DashboardId": dashboardId,
                "SheetId": sheetId,
                "VisualId": visualId
            }
        }
    };
    
    const generateEmbedUrlForAnonymousUserParams = {
        "AwsAccountId": accountId,
        "Namespace": quicksightNamespace,
        // authorizedResourceArns should contain ARN of dashboard used below in ExperienceConfiguration
        "AuthorizedResourceArns": authorizedResourceArns,
        "AllowedDomains": allowedDomains,
        "ExperienceConfiguration": experienceConfiguration,
        "SessionTags": sessionTags,
        "SessionLifetimeInMinutes": 600
    };

    const quicksightClient = new AWS.QuickSight({
        region: process.env.AWS_REGION,
        credentials: {
            accessKeyId: AccessKeyId,
            secretAccessKey: SecretAccessKey,
            sessionToken: SessionToken,
            expiration: Expiration
        }
    });

    quicksightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserParams, function(err, data) {
        if (err) {
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const result = {
                "statusCode": 200,
                "headers": {
                    "Access-Control-Allow-Origin": "*", // USE YOUR WEBSITE DOMAIN TO SECURE ACCESS TO THIS API
                    "Access-Control-Allow-Headers": "Content-Type"
                },
                "body": JSON.stringify(data),
                "isBase64Encoded": false
            }
            generateEmbedUrlForAnonymousUserCallback(result);
        }
    });
}
```

### Python3
<a name="embedded-analytics-visuals-with-anonymous-users-py"></a>

```
import json
import boto3
from botocore.exceptions import ClientError
import time

# Create QuickSight and STS clients
quicksightClient = boto3.client('quicksight',region_name='us-west-2')
sts = boto3.client('sts')

# Function to generate embedded URL for anonymous user
# accountId: YOUR AWS ACCOUNT ID
# quicksightNamespace: VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
# authorizedResourceArns: DASHBOARD ARN LIST TO EMBED
# allowedDomains: RUNTIME ALLOWED DOMAINS FOR EMBEDDING
# experienceConfiguration: DASHBOARD ID, SHEET ID and VISUAL ID TO WHICH THE CONSTRUCTED URL POINTS
# Example experienceConfig -> 'DashboardVisual': {
#     'InitialDashboardVisualId': {
#         'DashboardId': 'dashboardId',
#         'SheetId': 'sheetId',
#         'VisualId': 'visualId'
#     }
# },
# sessionTags: SESSION TAGS USED FOR ROW-LEVEL SECURITY
def generateEmbedUrlForAnonymousUser(accountId, quicksightNamespace, authorizedResourceArns, allowedDomains, experienceConfiguration, sessionTags):
    try:
        response = quicksightClient.generate_embed_url_for_anonymous_user(
            AwsAccountId = accountId,
            Namespace = quicksightNamespace,
            AuthorizedResourceArns = authorizedResourceArns,
            AllowedDomains = allowedDomains,
            ExperienceConfiguration = experienceConfiguration,
            SessionTags = sessionTags,
            SessionLifetimeInMinutes = 600
        )
            
        return {
            'statusCode': 200,
            'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
            'body': json.dumps(response),
            'isBase64Encoded':  bool('false')
        }
    except ClientError as e:
        print(e)
        return "Error generating embeddedURL: " + str(e)
```

### Node.js
<a name="embedded-analytics-visuals-with-anonymous-users-node"></a>

以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 URL 的 JavaScript (Node.js)。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
const AWS = require('aws-sdk');
const https = require('https');

var quicksightClient = new AWS.Service({
    apiConfig: require('./quicksight-2018-04-01.min.json'),
    region: 'us-east-1',
});

quicksightClient.generateEmbedUrlForAnonymousUser({
    'AwsAccountId': '111122223333',
    'Namespace' : 'default',
    // authorizedResourceArns should contain ARN of dashboard used below in ExperienceConfiguration
    'AuthorizedResourceArns': authorizedResourceArns,
    'ExperienceConfiguration': { 
        'DashboardVisual': {
            'InitialDashboardVisualId': {
                'DashboardId': 'dashboard_id',
                'SheetId': 'sheet_id',
                'VisualId': 'visual_id'
            }
        }
    },
    'AllowedDomains': allowedDomains,    
    'SessionTags': sessionTags,
    'SessionLifetimeInMinutes': 600

}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

**Example**  

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
    {
        "Status": "200",
        "EmbedUrl": "https://quicksightdomain/embed/12345/dashboards/67890/sheets/12345/visuals/67890...",
        "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
    }
```

### .NET/C\$1
<a name="embedded-analytics-visuals-with-anonymous-users-cs"></a>

以下示例演示了可以在应用程序服务器上使用以生成嵌入式控制面板 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
using System;
using Amazon.QuickSight;
using Amazon.QuickSight.Model;

namespace GenerateDashboardEmbedUrlForAnonymousUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                DashboardVisualId dashboardVisual = new DashboardVisualId
                {
                    DashboardId = "dashboard_id",
                    SheetId = "sheet_id",
                    VisualId = "visual_id"
                };

                AnonymousUserDashboardVisualEmbeddingConfiguration anonymousUserDashboardVisualEmbeddingConfiguration
                    = new AnonymousUserDashboardVisualEmbeddingConfiguration
                    {
                        InitialDashboardVisualId = dashboardVisual                        
                    };               
                    
                AnonymousUserEmbeddingExperienceConfiguration anonymousUserEmbeddingExperienceConfiguration
                    = new AnonymousUserEmbeddingExperienceConfiguration
                    {
                        DashboardVisual = anonymousUserDashboardVisualEmbeddingConfiguration
                    }; 
                    
                Console.WriteLine(
                    quicksightClient.GenerateEmbedUrlForAnonymousUserAsync(new GenerateEmbedUrlForAnonymousUserRequest
                    {
                        AwsAccountId = "111222333444",
                        Namespace = default,
                        // authorizedResourceArns should contain ARN of dashboard used below in ExperienceConfiguration
                        AuthorizedResourceArns = { "dashboard_id" },
                        ExperienceConfiguration = anonymousUserEmbeddingExperienceConfiguration,
                        SessionTags = sessionTags,
                        SessionLifetimeInMinutes = 600,
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
```

### AWS CLI
<a name="embedded-analytics-visuals-with-anonymous-users-cli"></a>

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用安全断言标记语言 (SAML) 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GenerateEmbedUrlForAnonymousUser` 启用权限。

```
aws sts assume-role \
    --role-arn "arn:aws:iam::11112222333:role/QuickSightEmbeddingAnonymousPolicy" \
    --role-session-name anonymous caller
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。如果使用的是 Microsoft Windows 计算机，请使用 `set` 而非 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
        export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
        export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_visual_role/QuickSightEmbeddingAnonymousPolicy`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个访问用户设置相应的权限。其还能让每个会话保持独立性和独特性。如果您使用一组 Web 服务器（例如用于负载平衡），并且会话重新连接到其他服务器，则会开始新的会话。

要获取视觉对象的签名 URL，请从应用程序服务器中调用 `generate-embed-url-for-anynymous-user`。这会返回可嵌入视觉对象 URL。以下示例演示了如何使用服务器端调用为匿名访问您 Web 门户或应用的用户生成嵌入式视觉对象的 URL。

```
aws quicksight generate-embed-url-for-anonymous-user \
    --aws-account-id 111122223333 \
    --namespace default-or-something-else \
    --session-lifetime-in-minutes 15 \
    --authorized-resource-arns '["dashboard-arn-1","dashboard-arn-2"]' \
    --allowed-domains '["domain1","domain2"]' \
    --session-tags '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]' \
    --experience-configuration 'DashboardVisual={InitialDashboardVisualId={DashboardId=dashboard_id,SheetId=sheet_id,VisualId=visual_id}}'
```

有关使用此操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)。您可以在自己的代码中使用该 API 操作和其他操作。

## 步骤 3：嵌入视觉对象 URL
<a name="embedded-analytics-visuals-with-anonymous-users-step-3"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在下一节中，您可以了解如何使用 [Amazon Quick Sight Embedging SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 将第 2 步中的可视网址嵌入到您的网站或应用程序页面中。通过使用该开发工具包，您可以执行以下操作：
+ 将视觉对象置于 HTML 页面上。
+ 将参数传入视觉对象。
+ 使用为应用程序自定义的消息处理错误状态。

调用 `GenerateEmbedUrlForAnonymousUser` API 操作生成可嵌入应用的 URL。该 URL 的有效期为 5 分钟，生成的会话的有效期为 10 个小时。该 API 操作为 URL 提供授权（auth）代码以启用单点登录会话。

下面显示了 `generate-embed-url-for-anonymous-user` 的示例响应：此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
    {
        "Status": "200",
        "EmbedUrl": "https://quicksightdomain/embed/12345/dashboards/67890/sheets/12345/visuals/67890...",
        "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
    }
```

使用 Amazon Quick Sight Embedding [SDK 或将此 URL 添加到 iframe 中，将此视觉效果嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会随着窗口大小调整而改变视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制视觉对象中的参数并接收有关视觉加载完成和错误的回调。

要托管嵌入式视觉对象的域必须位于*允许列表*（为您的 Quick 订阅批准的域的列表）中。这一要求可阻止未经批准的域托管嵌入式视觉对象和控制面板，从而保护您的数据。有关为嵌入式视觉对象和控制面板添加域名的更多信息，请参阅[允许使用 Amazon Quick Sight API 在运行时列出域名](https://docs.aws.amazon.com/quicksight/latest/user/embedding-run-time.html)。

以下示例演示了如何使用生成的 URL。此代码位于您的应用程序服务器上。

### SDK 2.0
<a name="embedded-analytics-visuals-with-anonymous-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Visual Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedVisual = async() => {    
                const {
                    createEmbeddingContext,
                } = QuickSightEmbedding;

                const embeddingContext = await createEmbeddingContext({
                    onChange: (changeEvent, metadata) => {
                        console.log('Context received a change', changeEvent, metadata);
                    },
                });

                const frameOptions = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: '#experience-container',
                    height: "700px",
                    width: "1000px",
                    onChange: (changeEvent, metadata) => {
                        switch (changeEvent.eventName) {
                            case 'FRAME_MOUNTED': {
                                console.log("Do something when the experience frame is mounted.");
                                break;
                            }
                            case 'FRAME_LOADED': {
                                console.log("Do something when the experience frame is loaded.");
                                break;
                            }
                        }
                    },
                };

                const contentOptions = {
                    parameters: [
                        {
                            Name: 'country',
                            Values: ['United States'],
                        },
                        {
                            Name: 'states',
                            Values: [
                                'California',
                                'Washington'
                            ]
                        }
                    ],
                    locale: "en-US",
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'CONTENT_LOADED': {
                                console.log("All visuals are loaded. The title of the document:", messageEvent.message.title);
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Error occurred while rendering the experience. Error code:", messageEvent.message.errorCode);
                                break;
                            }
                            case 'PARAMETERS_CHANGED': {
                                console.log("Parameters changed. Changed parameters:", messageEvent.message.changedParameters);
                                break;
                            }
                            case 'SIZE_CHANGED': {
                                console.log("Size changed. New dimensions:", messageEvent.message);
                                break;
                            }
                        }
                    },
                };
                const embeddedVisualExperience = await embeddingContext.embedVisual(frameOptions, contentOptions);

                const selectCountryElement = document.getElementById('country');
                selectCountryElement.addEventListener('change', (event) => {
                    embeddedVisualExperience.setParameters([
                        {
                            Name: 'country',
                            Values: event.target.value
                        }
                    ]);
                });
            };
        </script>
    </head>

    <body onload="embedVisual()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="experience-container"></div>
    </body>

</html>
```

### SDK 1.0
<a name="embedded-analytics-visuals-with-anonymous-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Visual Embedding Example</title>
        <!-- You can download the latest QuickSight embedding SDK version from https://www.npmjs.com/package/amazon-quicksight-embedding-sdk -->
        <!-- Or you can do "npm install amazon-quicksight-embedding-sdk", if you use npm for javascript dependencies -->
        <script src="./quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            let embeddedVisualExperience;
            function onVisualLoad(payload) {
                console.log("Do something when the visual is fully loaded.");
            }

            function onError(payload) {
                console.log("Do something when the visual fails loading");
            }

            function embedVisual() {
                const containerDiv = document.getElementById("embeddingContainer");
                const options = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: containerDiv,
                    parameters: {
                        country: "United States"
                    },
                    height: "700px",
                    width: "1000px",
                    locale: "en-US"
                };
                embeddedVisualExperience = QuickSightEmbedding.embedVisual(options);
                embeddedVisualExperience.on("error", onError);
                embeddedVisualExperience.on("load", onVisualLoad);
            }

            function onCountryChange(obj) {
                embeddedVisualExperience.setParameters({country: obj.value});
            }
        </script>
    </head>

    <body onload="embedVisual()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country" onchange="onCountryChange(this)">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="embeddingContainer"></div>
    </body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 将嵌入式视觉效果加载到您的网站上 JavaScript。要获取副本，请执行下列操作之一：
+ 从 GitHub中下载 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) 该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的 QuickSight 嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

# 为注册用户嵌入 Amazon Quick Sight 控制台的全部功能
<a name="embedded-analytics-full-console-for-authenticated-users"></a>

**重要**  
Amazon Quick Sight 推出了用于嵌入分析的新 API 操作：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` API 操作来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关使用旧 API 操作进行嵌入的更多信息，请参阅[使用GetDashboardEmbedURL和 GetSessionEmbedURL API 操作嵌入分析](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics-deprecated.html)。


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

使用企业版，除了提供只读控制面板外，您还可以在自定义品牌的创作门户中提供 Amazon Quick Sight 控制台体验。您可以使用这种方法允许用户创建数据来源、数据集和分析。在同一个界面中，用户可以创建、发布和查看控制面板。如果您想限制其中的一些权限，也可以这样做。

通过嵌入式控制台访问 Amazon Quick Sight 的用户需要属于作者或管理员安全群组。无论是嵌入式还是其中的一部分，读者都没有足够的访问权限来使用 Amazon Quick Sight 控制台进行创作。 AWS 管理控制台不过，作者和管理员仍然可以访问嵌入式控制面板。如果您想限制某些创作功能的权限，可以通过 [UpdateUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_UpdateUser.html)API 操作向用户添加自定义权限配置文件。使用 [RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)API 操作添加附加了自定义权限配置文件的新用户。有关详细信息，请参阅以下章节：
+ 有关通过定义自定义控制台权限来创建自定义角色的信息，请参阅[自定义对 Amazon Quick Sight 控制台的访问](https://docs.aws.amazon.com/quicksight/latest/user/customizing-permissions-to-the-quicksight-console.html)权限。
+ [有关使用命名空间隔离多租户用户、群组和 Amazon Quick Sight 资产的信息，请参阅 Amazon Quick Sight 命名空间。](https://docs.aws.amazon.com/quicksight/latest/APIReference/controlling-access.html#namespaces.html)
+ 有关将自己的品牌添加到嵌入式 Amazon Quick Sight 控制台的信息，请参阅[在 Amazon Quick Sight 中使用QuickSight ](https://docs.aws.amazon.com/quicksight/latest/user/themes-in-quicksight.html)[主题和主题 API 操作](https://docs.aws.amazon.com/quicksight/latest/APIReference/qs-assets.html#themes)。

在以下各节中，您可以找到有关如何为注册用户设置嵌入式 Amazon Quick Sight 控制面板的详细信息。

**Topics**
+ [

## 步骤 1：设置权限
](#embedded-analytics-full-console-for-authenticated-users-step-1)
+ [

## 步骤 2：生成附带身份验证代码的 URL
](#embedded-analytics-full-console-for-authenticated-users-step-2)
+ [

## 步骤 3：嵌入控制台会话 URL
](#embedded-analytics-full-console-for-authenticated-users-step-3)
+ [

# 在嵌入式控制台中为注册用户启用生成式 BI 功能
](embedding-consoles-genbi.md)

## 步骤 1：设置权限
<a name="embedded-analytics-full-console-for-authenticated-users-step-1"></a>

在下节中，您可以了解如何设置后端应用程序或 Web 服务器的权限。该任务需要具有 IAM 的管理访问权限。

每个访问 Amazon Quick Sight 的用户都扮演一个角色，该角色授予他们 Amazon Quick Sight 访问权限和控制台会话权限。为此，请在您的 AWS 账户中创建一个 IAM 角色。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。添加`quicksight:RegisterUser`权限以确保读者能够以只读方式访问 Amazon Quick Sight，并且无法访问任何其他数据或创建功能。IAM 角色还需要提供检索控制台会话的权限 URLs。为此，请添加 `quicksight:GenerateEmbedUrlForRegisteredUser`。

您可以在 IAM 策略中创建一个条件，限制开发人员可以在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 参数中列出的域。`AllowedDomains` 参数是可选参数。作为开发者，它允许您选择覆盖在 “**管理 Amazon Quick Sight**” 菜单中配置的静态域。您最多可以列出三个可以访问生成的 URL 的域或子域。然后，此 URL 将嵌入您创建的网站。只有参数中列出的域才能访问嵌入式控制面板。如果没有此条件，则可以在 `AllowedDomains` 参数中列出互联网上的任何域。

**IAM 条件运算符的安全最佳实践**  
配置不当的 IAM 条件运算符可能会允许未经授权地通过 URL 变体访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用`quicksight:AllowedEmbeddingDomains`条件密钥时，请使用条件运算符，允许特定域名或拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息，请参阅 [IAM 用户指南中的 IAM JSON 策略元素：条件运算符](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
许多不同的网址变体可以指向同一个资源。例如，以下 URLs 所有内容都解析为相同的内容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的策略使用的运算符不考虑这些 URL 变体，则攻击者可以通过提供等效的 URL 变体来绕过您的限制。  
您必须验证您的 IAM 策略是否使用了适当的条件运算符来防止绕过漏洞，并确保只有您的目标域才能访问您的嵌入式资源。

以下示例策略提供了这些权限。

以下示例策略提供了检索控制台会话 URL 的权限。如果您在用户访问嵌入式会话之前创建用户，则可以使用不具有 `quicksight:RegisterUser` 的策略。

最后，您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，当用户访问您的应用程序时，您的应用程序可以代表用户担任该角色并在 Amazon Quick Sight 中配置用户。下面演示了一个示例信任策略。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowLambdaFunctionsToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        {
            "Sid": "AllowEC2InstancesToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

------

有关 OpenId Connect 或 SAML 身份验证的信任策略的更多信息，请参阅 *IAM 用户指南* 的以下部分：
+ [创建用于 Web 联合身份验证或 OpenID Connect 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [创建用于 SAML 2.0 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

## 步骤 2：生成附带身份验证代码的 URL
<a name="embedded-analytics-full-console-for-authenticated-users-step-2"></a>

在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入控制台会话 URL。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，它会将该用户添加到 Amazon Quick Sight 中（如果该用户尚不存在）。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

执行上述步骤可确保在 Amazon Quick Sight 中对控制台会话的每个查看者进行唯一的配置。它还实施每个用户的设置，例如，行级别安全性和参数的动态默认值。

以下示例展示了代表用户执行 IAM 身份验证。此代码在您的应用程序服务器上运行。

### Java
<a name="embedded-analytics-full-console-for-authenticated-users-java"></a>

```
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserResult;
import com.amazonaws.services.quicksight.model.RegisteredUserEmbeddingExperienceConfiguration;
import com.amazonaws.services.quicksight.model.RegisteredUserQuickSightConsoleEmbeddingConfiguration;

/**
 * Class to call QuickSight AWS SDK to get url for QuickSight console embedding.
 */
public class GetQuicksightEmbedUrlRegisteredUserQSConsoleEmbedding {

    private final AmazonQuickSight quickSightClient;

    public GetQuicksightEmbedUrlRegisteredUserQSConsoleEmbedding() {
        this.quickSightClient = AmazonQuickSightClientBuilder
                .standard()
                .withRegion(Regions.US_EAST_1.getName())
                .withCredentials(new AWSCredentialsProvider() {
                        @Override
                        public AWSCredentials getCredentials() {
                            // provide actual IAM access key and secret key here
                            return new BasicAWSCredentials("access-key", "secret-key");
                        }

                         @Override
                        public void refresh() {                           
                        }
                    }
                )
                .build();
    }

    public String getQuicksightEmbedUrl(
            final String accountId,
            final String userArn, // Registered user arn to use for embedding. Refer to Get Embed Url section in developer portal to find out how to get user arn for a QuickSight user.
            final List<String> allowedDomains, // Runtime allowed domain for embedding
            final String initialPath
    ) throws Exception {
        final RegisteredUserEmbeddingExperienceConfiguration experienceConfiguration = new RegisteredUserEmbeddingExperienceConfiguration()
                .withQuickSightConsole(new RegisteredUserQuickSightConsoleEmbeddingConfiguration().withInitialPath(initialPath));
        final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest = new GenerateEmbedUrlForRegisteredUserRequest();
        generateEmbedUrlForRegisteredUserRequest.setAwsAccountId(accountId);
        generateEmbedUrlForRegisteredUserRequest.setUserArn(userArn);
        generateEmbedUrlForRegisteredUserRequest.setAllowedDomains(allowedDomains);
        generateEmbedUrlForRegisteredUserRequest.setExperienceConfiguration(experienceConfiguration);

        final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);

        return generateEmbedUrlForRegisteredUserResult.getEmbedUrl();
    }
}
```

### JavaScript
<a name="embedded-analytics-full-console-for-authenticated-users-js"></a>

```
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function generateEmbedUrlForRegisteredUser(
    accountId,
    dashboardId,
    openIdToken, // Cognito-based token
    userArn, // registered user arn
    roleArn, // IAM user role to use for embedding
    sessionName, // Session name for the roleArn assume role
    allowedDomains, // Runtime allowed domain for embedding
    getEmbedUrlCallback, // GetEmbedUrl success callback method
    errorCallback // GetEmbedUrl error callback method
    ) {
    const stsClient = new AWS.STS();
    let stsParams = {
        RoleSessionName: sessionName,
        WebIdentityToken: openIdToken,
        RoleArn: roleArn
    }

    stsClient.assumeRoleWithWebIdentity(stsParams, function(err, data) {
        if (err) {
            console.log('Error assuming role');
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const getDashboardParams = {
                "AwsAccountId": accountId,
                "ExperienceConfiguration": {
                    "QuickSightConsole": {
                        "InitialPath": '/start'
                    }
                },
                "UserArn": userArn,
                "AllowedDomains": allowedDomains,
                "SessionLifetimeInMinutes": 600
            };

            const quicksightGetDashboard = new AWS.QuickSight({
                region: process.env.AWS_REGION,
                credentials: {
                    accessKeyId: data.Credentials.AccessKeyId,
                    secretAccessKey: data.Credentials.SecretAccessKey,
                    sessionToken: data.Credentials.SessionToken,
                    expiration: data.Credentials.Expiration
                }
            });

            quicksightGetDashboard.generateEmbedUrlForRegisteredUser(getDashboardParams, function(err, data) {
                if (err) {
                    console.log(err, err.stack);
                    errorCallback(err);
                } else {
                    const result = {
                        "statusCode": 200,
                        "headers": {
                            "Access-Control-Allow-Origin": "*", // Use your website domain to secure access to GetEmbedUrl API
                            "Access-Control-Allow-Headers": "Content-Type"
                        },
                        "body": JSON.stringify(data),
                        "isBase64Encoded": false
                    }
                    getEmbedUrlCallback(result);
                }
            });
        }
    });
}
```

### Python3
<a name="embedded-analytics-full-console-for-authenticated-users-py"></a>

```
import json
import boto3
from botocore.exceptions import ClientError

# Create QuickSight and STS clients
qs = boto3.client('quicksight', region_name='us-east-1')
sts = boto3.client('sts')

# Function to generate embedded URL  
# accountId: AWS account ID
# userArn: arn of registered user
# allowedDomains: Runtime allowed domain for embedding
# roleArn: IAM user role to use for embedding
# sessionName: session name for the roleArn assume role
def generateEmbeddingURL(accountId, userArn, allowedDomains, roleArn, sessionName):
    try:
        assumedRole = sts.assume_role(
            RoleArn = roleArn,
            RoleSessionName = sessionName,
        )
    except ClientError as e:
        return "Error assuming role: " + str(e)
    else: 
        assumedRoleSession = boto3.Session(
            aws_access_key_id = assumedRole['Credentials']['AccessKeyId'],
            aws_secret_access_key = assumedRole['Credentials']['SecretAccessKey'],
            aws_session_token = assumedRole['Credentials']['SessionToken'],
        )
        try:
            quickSightClient = assumedRoleSession.client('quicksight', region_name='us-east-1')
            
            experienceConfiguration = {
                "QuickSightConsole": {
                    "InitialPath": "/start"
                }
            }
            response = quickSightClient.generate_embed_url_for_registered_user(
                 AwsAccountId = accountId,
                 ExperienceConfiguration = experienceConfiguration,
                 UserArn = userArn,
                 AllowedDomains = allowedDomains,
                 SessionLifetimeInMinutes = 600
            )
            
            return {
                'statusCode': 200,
                'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
                'body': json.dumps(response),
                'isBase64Encoded':  bool('false')
            }
        except ClientError as e:
            return "Error generating embedding url: " + str(e)
```

### Node.js
<a name="embedded-analytics-full-console-for-authenticated-users-node"></a>

以下示例显示了可以在应用服务器上使用的 JavaScript (Node.js) 来生成嵌入式控制台会话的 URL。您可以在网站或应用程序中使用该 URL 来显示控制台会话。

**Example**  

```
const AWS = require('aws-sdk');
const https = require('https');

var quicksightClient = new AWS.Service({
    apiConfig: require('./quicksight-2018-04-01.min.json'),
    region: 'us-east-1',
});

quicksightClient.generateEmbedUrlForRegisteredUser({
    'AwsAccountId': '111122223333',
    'ExperienceConfiguration': {
        'QuickSightConsole': {
            'InitialPath': '/start'
        }
    },
    'UserArn': 'REGISTERED_USER_ARN',
    'AllowedDomains': allowedDomains,
    'SessionLifetimeInMinutes': 100
}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

**Example**  

```
// The URL returned is over 900 characters. For this example, we've shortened the string for
// readability and added ellipsis to indicate that it's incomplete.
    {
        Status: 200,
        EmbedUrl: 'https://quicksightdomain/embed/12345/dashboards/67890..,
        RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713'
    }
```

### .NET/C\$1
<a name="embedded-analytics-full-console-for-authenticated-users-cs"></a>

以下示例演示了可以在应用服务器上使用以生成嵌入式控制台会话 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用该 URL 来显示控制台。

**Example**  

```
using System;
using Amazon.QuickSight;
using Amazon.QuickSight.Model;

namespace GenerateDashboardEmbedUrlForRegisteredUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                RegisteredUserQuickSightConsoleEmbeddingConfiguration registeredUserQuickSightConsoleEmbeddingConfiguration
                    = new RegisteredUserQuickSightConsoleEmbeddingConfiguration
                    {
                        InitialPath = "/start"
                    };
                RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                    = new RegisteredUserEmbeddingExperienceConfiguration
                    {
                        QuickSightConsole = registeredUserQuickSightConsoleEmbeddingConfiguration
                    };
                
                Console.WriteLine(
                    quicksightClient.GenerateEmbedUrlForRegisteredUserAsync(new GenerateEmbedUrlForRegisteredUserRequest
                    {
                        AwsAccountId = "111122223333",
                        ExperienceConfiguration = registeredUserEmbeddingExperienceConfiguration,
                        UserArn = "REGISTERED_USER_ARN",
                        AllowedDomains = allowedDomains,
                        SessionLifetimeInMinutes = 100
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
```

### AWS CLI
<a name="embedded-analytics-full-console-for-authenticated-users-cli"></a>

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用 SAML 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GenerateEmbedUrlForRegisteredUser` 启用权限。如果您在用户首次打开 Amazon Quick Sight 时采用添加他们的 just-in-time方法，则还需要为该角色启用权限`quicksight:RegisterUser`。

```
aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
     --role-session-name john.doe@example.com
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。如果使用的是 Microsoft Windows 计算机，请使用 `set` 而非 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_console_session_role/john.doe@example.com`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个用户设置相应的权限。此外，它还能避免任何用户访问限制。限制是一项安全功能，可防止同一个用户从多个位置访问 Amazon Quick Sight。

角色会话 ID 也将成为 Amazon Quick Sight 中的用户名。您可以使用此模式提前在 Amazon Quick Sight 中配置用户，或者在他们首次访问控制台会话时对其进行配置。

以下示例显示了可用于预置用户的 CLI 命令。有关[RegisterUser[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html)](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、和其他 Amazon Quick Sight API 操作的更多信息，请参阅[亚马逊 Quick Sight API 参考](https://docs.aws.amazon.com/quicksight/latest/APIReference/Welcome.html)。

```
aws quicksight register-user \
     --aws-account-id 111122223333 \
     --namespace default \
     --identity-type IAM \
     --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
     --user-role READER \
     --user-name jhnd \
     --session-name "john.doe@example.com" \
     --email john.doe@example.com \
     --region us-east-1 \
     --custom-permissions-name TeamA1
```

如果用户通过 Microsoft AD 进行身份验证，则无需使用 `RegisterUser` 进行设置。相反，他们应该在首次访问 Amazon Quick Sight 时自动订阅。对于 Microsoft AD 用户，您可以使用 `DescribeUser` 获取用户 ARN。

当用户首次访问 Amazon Quick Sight 时，您也可以将该用户添加到相应的群组中。以下示例显示了将用户添加到组的 CLI 命令。

```
aws quicksight create-group-membership \
     --aws-account-id=111122223333 \
     --namespace=default \
     --group-name=financeusers \
     --member-name="embedding_quicksight_dashboard_role/john.doe@example.com"
```

现在，您的应用程序的用户也是 Amazon Quick Sight 的用户，并且可以访问 Amazon Quick Sight 控制台会话。

最后，要获取控制台会话的签名 URL，请从应用程序服务器中调用 `generate-embed-url-for-registered-user`。此操作会返回可嵌入控制台会话 URL。以下示例说明如何使用服务器端调用为通过身份验证 AWS Managed Microsoft AD 或单点登录（IAM Identity Center）进行身份验证的用户生成嵌入式控制台会话的 URL。

```
aws quicksight generate-embed-url-for-registered-user \
    --aws-account-id 111122223333 \
    --entry-point the-url-for--the-console-session \
    --session-lifetime-in-minutes 600 \
    --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_dashboard_role/embeddingsession
	--allowed-domains '["domain1","domain2"]' \
    --experience-configuration QuickSightConsole={InitialPath="/start"}
```

有关使用此操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在自己的代码中使用该 API 操作和其他操作。

## 步骤 3：嵌入控制台会话 URL
<a name="embedded-analytics-full-console-for-authenticated-users-step-3"></a>

在下一节中，您可以了解如何使用 [Amazon Quick Sight Embedding SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 将第 3 步中的控制台会话 URL 嵌入到您的网站或应用程序页面中。通过使用该开发工具包，您可以执行以下操作：
+ 将控制台会话置于 HTML 页面上。
+ 将参数传入控制台会话。
+ 使用为应用程序自定义的消息处理错误状态。

调用 `GenerateEmbedUrlForRegisteredUser` API 操作生成可嵌入应用的 URL。该 URL 的有效时间为 5 分钟，生成的会话有效时间为 10 个小时。该 API 操作为 URL 提供 `auth_code` 以启用单点登录会话。

下面显示了 `generate-embed-url-for-registered-user` 的示例响应：

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
{
     "Status": "200",
     "EmbedUrl": "https://quicksightdomain/embedding/12345/start...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 Amazon Quick Sight Embedding [SDK 或将此 URL 添加到 iframe 中，将此控制台会话嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会在窗口大小调整时更改视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制控制台会话中的参数，并接收有关页面加载完成和错误的回调。

要托管嵌入式仪表板的域名必须位于*允许列表中*，即订 Quick 阅的已批准域名列表。这一要求可阻止未经批准的域托管嵌入式控制面板，从而保护您的数据。有关为嵌入式控制台添加域名的更多信息，请参阅[允许在运行时使用 Amazon Quick Sight API 列出域名](https://docs.aws.amazon.com/quicksight/latest/user/embedding-run-time.html)。

以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。

### SDK 2.0
<a name="embedded-analytics-full-console-for-authenticated-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Console Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedSession = async() => {    
                const {
                    createEmbeddingContext,
                } = QuickSightEmbedding;

                const embeddingContext = await createEmbeddingContext({
                    onChange: (changeEvent, metadata) => {
                        console.log('Context received a change', changeEvent, metadata);
                    },
                });

                const frameOptions = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: '#experience-container',
                    height: "700px",
                    width: "1000px",
                    onChange: (changeEvent, metadata) => {
                        switch (changeEvent.eventName) {
                            case 'FRAME_MOUNTED': {
                                console.log("Do something when the experience frame is mounted.");
                                break;
                            }
                            case 'FRAME_LOADED': {
                                console.log("Do something when the experience frame is loaded.");
                                break;
                            }
                        }
                    },
                };

                const contentOptions = {
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'ERROR_OCCURRED': {
                                console.log("Do something when the embedded experience fails loading.");
                                break;
                            }
                        }
                    }
                };
                const embeddedConsoleExperience = await embeddingContext.embedConsole(frameOptions, contentOptions);
            };
        </script>
    </head>

    <body onload="embedSession()">
        <div id="experience-container"></div>
    </body>

</html>
```

### SDK 1.0
<a name="embedded-analytics-full-console-for-authenticated-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>QuickSight Console Embedding</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.0.15/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            var session

            function onError(payload) {
                console.log("Do something when the session fails loading");
            }

            function embedSession() {
                var containerDiv = document.getElementById("embeddingContainer");
                var options = {
                    // replace this dummy url with the one generated via embedding API
                    url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode", // replace this dummy url with the one generated via embedding API
                    container: containerDiv,
                    parameters: {
                        country: "United States"
                    },
                    scrolling: "no",
                    height: "700px",
                    width: "1000px",
                    locale: "en-US",
                    footerPaddingEnabled: true,
                    defaultEmbeddingVisualType: "TABLE", // this option only applies to QuickSight console embedding and is not used for dashboard embedding
                };
                session = QuickSightEmbedding.embedSession(options);
                session.on("error", onError);
            }

            function onCountryChange(obj) {
                session.setParameters({country: obj.value});
            }
        </script>
    </head>

    <body onload="embedSession()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country" onchange="onCountryChange(this)">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="embeddingContainer"></div>
    </body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 将嵌入式控制台会话加载到您的网站上 JavaScript。要获取副本，请执行下列操作之一：
+ 从 GitHub中下载 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) 该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

# 在嵌入式控制台中为注册用户启用生成式 BI 功能
<a name="embedding-consoles-genbi"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

您可以在嵌入式控制台中启用下列生成式 BI 功能：
+ 执行摘要：启用后，注册的 Author Pro 和 Reader Pro 用户可以生成执行摘要，摘要提供 Amazon Quick Sight 为控制面板生成的所有见解，以便轻松发现关键见解。
+ 创作：启用后，作者 Pro 用户可以使用生成式 BI 来构建计算字段以及构建和优化视觉对象。
+ 问答：启用后，作者 Pro 和读者 Pro 用户可以使用 AI 驱动的问答来建议和回答与其数据相关的问题。
+ 数据故事：启用后，作者 Pro 和读者 Pro 用户可以提供详细信息以快速生成其数据故事的初稿。

**在嵌入式控制台中为注册用户启用生成式 BI 功能**
+ 按照[嵌入 Amazon Quick Sight 控制台的全部功能中的步骤进行操作，以便注册用户](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics-full-console-for-authenticated-users.html)嵌入包含以下更改的主机：

  1. 在步骤 2 中生成 URL 时，请在要`Enabled: true`在[GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)或中启用的每个功能的`FeatureConfigurations`参数中进行设置 [GenerateEmbedUrlForRegisteredUserWithIdentity](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUserWithIdentity.html) APIs，如以下示例所示。如果没有提供配置，则默认禁用功能。

     ```
     ExperienceConfiguration: {
             QuickSightConsole: {
                 InitialPath: "initial_path",
                 AmazonQInQuickSight: {
                     FeatureConfigurations: { 
                         COMMENT: Enable executive summaries
                         ExecutiveSummary: {
                             Enabled: true
                         },
                         COMMENT: Enable Generative BI authoring
                         GenerativeAuthoring: {
                             Enabled: true
                         },
                         COMMENT: Enable Q&A
                         DataQnA: {
                             Enabled: true
                         },
                         COMMENT: Enable data stories
                         DataStories: {
                             Enabled: true
                         }       
                     }
                 }
             }
         }
     }
     ```

  1. 在步骤 3 中使用 Amazon Quick Sight Embedding SDK 嵌入控制台 URL 时，请根据需要设置以下示例中的值。如果没有提供配置，则默认禁用功能。
**注意**  
没有用于启用数据故事的 SDK 选项。如果按照上一步所示通过 API 启用数据故事，则注册用户将可以使用它们。

     ```
     const contentOptions = {
         toolbarOptions: {
             executiveSummary: true, // Enable executive summaries
             buildVisual: true, // Enable Generative BI authoring
             dataQnA: true // Enable Q&A
         }
     };
     ```

# 在 Amazon Quick Sight 生成问答体验中嵌入 Amazon Q
<a name="embedding-gen-bi"></a>


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在以下各节中，您可以找到有关如何设置嵌入式生成问答体验的详细信息，该体验使用由提供的增强的 NLQ 功能。 LLMs生成式问答体验是嵌入式 Q 搜索栏的推荐替代品，并为用户提供更新的 BI 体验。

**Topics**
+ [

## 将 Amazon Q 嵌入注册用户的 Amazon Quick Sight 生成问答体验中
](#embedded-analytics-gen-bi-authenticated-users)
+ [

## 将 Amazon Q 嵌入匿名（未注册）用户的快速生成问答体验中
](#embedded-analytics-gen-bi-anonymous-users)

## 将 Amazon Q 嵌入注册用户的 Amazon Quick Sight 生成问答体验中
<a name="embedded-analytics-gen-bi-authenticated-users"></a>

在以下各节中，您可以找到有关如何为 Amazon Quick Sight 的注册用户设置嵌入式生成问答体验的详细信息。

**Topics**
+ [

### 步骤 1：设置权限
](#embedded-analytics-gen-bi-authenticated-users-step-1)
+ [

### 步骤 2：生成附带身份验证代码的 URL
](#embedded-analytics-gen-bi-authenticated-users-step-2)
+ [

### 步骤 3：嵌入生成式问答体验 URL
](#embedded-analytics-gen-bi-authenticated-users-step-3)
+ [

### 可选的嵌入生成式问答体验功能
](#embedded-analytics-gen-bi-authenticated-users-step-4)

### 步骤 1：设置权限
<a name="embedded-analytics-gen-bi-authenticated-users-step-1"></a>

在以下部分中，您可以了解如何设置后端应用程序或 Web 服务器的权限来嵌入生成式问答体验。此任务需要对 AWS Identity and Access Management (IAM) 的管理权限。

每位访问生成式问答体验的用户都扮演一个角色，为他们授予 Amazon Quick Sight 访问权限和权限。要实现该目的，请在您的 AWS 账户中创建一个 IAM 角色。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。IAM 角色需要提供权限才能检索特定用户池 URLs 的嵌入内容。

借助通配符 *\$1*，您可以授予为特定命名空间中的所有用户生成 URL 的权限。您也可以授予为特定命名空间中的一部分用户生成 URL 的权限。为此，请添加 `quicksight:GenerateEmbedUrlForRegisteredUser`。

您可以在 IAM 策略中创建一个条件，限制开发人员可以在 `GenerateEmbedUrlForRegisteredUser` API 操作的 `AllowedDomains` 参数中列出的域。`AllowedDomains` 参数是可选参数。它允许开发者选择覆盖在 “**管理 Amazon Quick Sight**” 菜单中配置的静态域，而是列出最多三个可以访问生成的 URL 的域名或子域名。然后，此 URL 会嵌入开发人员的网站。只有参数中列出的域才能访问嵌入生成式问答体验。如果没有此条件，开发人员可以在 `AllowedDomains` 参数中列出互联网上的任何域。

要限制开发人员可用于此参数的域，请在 IAM 策略中添加一个 `AllowedEmbeddingDomains` 条件。有关该`AllowedDomains`参数的更多信息，请参阅 *Amazon Quick Sight API 参考[GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)*中的。

**IAM 条件运算符的安全最佳实践**  
配置不当的 IAM 条件运算符可能会允许未经授权地通过 URL 变体访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用`quicksight:AllowedEmbeddingDomains`条件密钥时，请使用条件运算符，允许特定域名或拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息，请参阅 [IAM 用户指南中的 IAM JSON 策略元素：条件运算符](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
许多不同的网址变体可以指向同一个资源。例如，以下 URLs 所有内容都解析为相同的内容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的策略使用的运算符不考虑这些 URL 变体，则攻击者可以通过提供等效的 URL 变体来绕过您的限制。  
您必须验证您的 IAM 策略是否使用了适当的条件运算符来防止绕过漏洞，并确保只有您的目标域才能访问您的嵌入式资源。

以下示例策略提供了这些权限。

此外，如果您要创建将成为 Amazon Quick Sight 读者的首次用户，请务必在策略中添加`quicksight:RegisterUser`权限。

以下示例策略为即将成为 Amazon Quick Sight 读者的首次用户提供了检索嵌入网址的权限。

最后，您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，当用户访问您的应用程序时，您的应用程序可以代表用户担任该角色并在 Amazon Quick Sight 中配置用户。

下面演示了一个示例信任策略。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
        "Statement": [
            {
    "Sid": "AllowLambdaFunctionsToAssumeThisRole",
                "Effect": "Allow",
                "Principal": {
    "Service": "lambda.amazonaws.com"
                },
                "Action": "sts:AssumeRole"
            },
            {
    "Sid": "AllowEC2InstancesToAssumeThisRole",
                "Effect": "Allow",
                "Principal": {
    "Service": "ec2.amazonaws.com"
                },
                "Action": "sts:AssumeRole"
            }
        ]
    }
```

------

有关 OpenID Connect 或安全断言标记语言（SAML）身份验证的信任策略的更多信息，请参阅《IAM 用户指南**》的以下章节：
+ [创建用于 Web 联合身份验证或 OpenID Connect 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [创建用于 SAML 2.0 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

### 步骤 2：生成附带身份验证代码的 URL
<a name="embedded-analytics-gen-bi-authenticated-users-step-2"></a>

在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入 Q 主题 URL。如果您计划为 IAM 或 Amazon Quick Sight 身份类型嵌入生成式问答体验，请与用户分享 Q 主题。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，如果该用户尚不存在，则该应用程序会将该用户添加到 Amazon Quick Sight。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

执行上述步骤可确保在 Amazon Quick Sight 中对 Q 主题的每个查看者进行唯一配置。它还实施每个用户的设置，例如，行级别安全性和参数的动态默认值。基于标签的行级别安全性可用于匿名用户嵌入 Q 栏。

以下示例展示了代表用户执行 IAM 身份验证。此代码在您的应用程序服务器上运行。

#### Java
<a name="embedded-analytics-gen-bi-authenticated-users-java"></a>

```
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserResult;
import com.amazonaws.services.quicksight.model.RegisteredUserEmbeddingExperienceConfiguration;
import com.amazonaws.services.quicksight.model.RegisteredUserGenerativeQnAEmbeddingConfiguration;

/**
 * Class to call QuickSight AWS SDK to get url for embedding Generative Q&A experience.
 */
public class RegisteredUserGenerativeQnAEmbeddingSample {

    private final AmazonQuickSight quickSightClient;

    public RegisteredUserGenerativeQnAEmbeddingSample() {
        this.quickSightClient = AmazonQuickSightClientBuilder
                    .standard()
                    .withRegion(Regions.US_EAST_1.getName())
                    .withCredentials(new AWS CredentialsProvider() {
                            @Override
                            public AWSCredentials getCredentials() {
                                // provide actual IAM access key and secret key here
                                return new BasicAWSCredentials("access-key", "secret-key");
                            }

                            @Override
                            public void refresh() {
                            }
                        }
                    )
                    .build();
            }

    public String getQuicksightEmbedUrl(
            final String accountId, // AWS Account ID
            final String topicId, // Topic ID to embed
            final List<String> allowedDomains, // Runtime allowed domain for embedding
            final String userArn // Registered user arn to use for embedding. Refer to Get Embed Url section in developer portal to find how to get user arn for a QuickSight user.
            ) throws Exception {

        final RegisteredUserEmbeddingExperienceConfiguration experienceConfiguration = new RegisteredUserEmbeddingExperienceConfiguration()
                .withGenerativeQnA(new RegisteredUserGenerativeQnAEmbeddingConfiguration().withInitialTopicId(topicId));
        final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest = new GenerateEmbedUrlForRegisteredUserRequest();
        generateEmbedUrlForRegisteredUserRequest.setAwsAccountId(accountId);
        generateEmbedUrlForRegisteredUserRequest.setUserArn(userArn);
        generateEmbedUrlForRegisteredUserRequest.setAllowedDomains(allowedDomains);
        generateEmbedUrlForRegisteredUserRequest.setExperienceConfiguration(experienceConfiguration);

        final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);

        return generateEmbedUrlForRegisteredUserResult.getEmbedUrl();
    }
}
```

#### JavaScript
<a name="embedded-analytics-gen-bi-authenticated-users-js"></a>

**注意**  
 APIs 不能直接从浏览器调用嵌入网址生成。请改为参考 Node.JS 示例。

#### Python3
<a name="embedded-analytics-gen-bi-authenticated-users-py"></a>

```
import json
import boto3
from botocore.exceptions import ClientError

sts = boto3.client('sts')

# Function to generate embedded URL  
# accountId: AWS account ID
# topicId: Topic ID to embed
# userArn: arn of registered user
# allowedDomains: Runtime allowed domain for embedding
# roleArn: IAM user role to use for embedding
# sessionName: session name for the roleArn assume role
def getEmbeddingURL(accountId, topicId, userArn, allowedDomains, roleArn, sessionName):
    try:
        assumedRole = sts.assume_role(
            RoleArn = roleArn,
            RoleSessionName = sessionName,
        )
    except ClientError as e:
        return "Error assuming role: " + str(e)
    else: 
        assumedRoleSession = boto3.Session(
            aws_access_key_id = assumedRole['Credentials']['AccessKeyId'],
            aws_secret_access_key = assumedRole['Credentials']['SecretAccessKey'],
            aws_session_token = assumedRole['Credentials']['SessionToken'],
        )
        try:
            quicksightClient = assumedRoleSession.client('quicksight', region_name='us-west-2')
            response = quicksightClient.generate_embed_url_for_registered_user(
                AwsAccountId=accountId,
                ExperienceConfiguration = {
                    'GenerativeQnA': {
                        'InitialTopicId': topicId
                    }
                },
                UserArn = userArn,
                AllowedDomains = allowedDomains,
                SessionLifetimeInMinutes = 600
            )
            
            return {
                'statusCode': 200,
                'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
                'body': json.dumps(response),
                'isBase64Encoded':  bool('false')
            }
        except ClientError as e:
            return "Error generating embedding url: " + str(e)
```

#### Node.js
<a name="embedded-analytics-gen-bi-authenticated-users-node"></a>

以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 URL 的 JavaScript (Node.js)。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
const AWS = require('aws-sdk');
const https = require('https');

var quicksightClient = new AWS.Service({
    region: 'us-east-1'
});

quicksightClient.generateEmbedUrlForRegisteredUser({
    'AwsAccountId': '111122223333',
    'ExperienceConfiguration': { 
        'GenerativeQnA': {
            'InitialTopicId': 'U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f'
        }
    },
    'UserArn': 'REGISTERED_USER_ARN',
    'AllowedDomains': allowedDomains,
    'SessionLifetimeInMinutes': 100
}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

#### .NET/C\$1
<a name="embedded-analytics-gen-bi-authenticated-users-cs"></a>

以下示例演示了可以在应用程序服务器上使用以生成嵌入式 Q 搜索栏 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用此 URL 以显示 Q 搜索栏。

**Example**  

```
using System;
using Amazon.QuickSight;
using Amazon.QuickSight.Model;

namespace GenerateGenerativeQnAEmbedUrlForRegisteredUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                RegisteredUserGenerativeQnAEmbeddingConfiguration registeredUserGenerativeQnAEmbeddingConfiguration
                    = new RegisteredUserGenerativeQnAEmbeddingConfiguration
                    {
                        InitialTopicId = "U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f"
                    };
                RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                    = new RegisteredUserEmbeddingExperienceConfiguration
                    {
                        GenerativeQnA = registeredUserGenerativeQnAEmbeddingConfiguration
                    }; 
                
                Console.WriteLine(
                    quicksightClient.GenerateEmbedUrlForRegisteredUserAsync(new GenerateEmbedUrlForRegisteredUserRequest
                    {
                        AwsAccountId = "111122223333",
                        ExperienceConfiguration = registeredUserEmbeddingExperienceConfiguration,
                        UserArn = "REGISTERED_USER_ARN",
                        AllowedDomains = allowedDomains,
                        SessionLifetimeInMinutes = 100
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
```

#### AWS CLI
<a name="embedded-analytics-gen-bi-authenticated-users-cli"></a>

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用 SAML 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GenerateEmbedUrlForRegisteredUser` 启用权限。如果您要在用户使用 Q 搜索栏中的主题时添加用户，则还需要为该角色启用权限`quicksight:RegisterUser`。 just-in-time

```
aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_generative_qna_role" \
     --role-session-name john.doe@example.com
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。对于 Microsoft Windows 计算机，请使用 `set` 而不是 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_q_search_bar_role/john.doe@example.com`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个用户设置相应的权限。此外，它还能避免任何用户访问限制。*限制*是一项安全功能，可防止同一个用户从多个位置访问 Amazon Quick Sight。

角色会话 ID 也成为 Amazon Quick Sight 中的用户名。您可以使用此模式提前在 Amazon Quick Sight 中配置用户，或者在他们首次访问生成问答体验时为他们进行配置。

以下示例显示了可用于预置用户的 CLI 命令。有关[RegisterUser[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html)](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、和其他 Amazon Quick Sight API 操作的更多信息，请参阅 [Amazon Quick Sight API 参考](https://docs.aws.amazon.com/quicksight/latest/APIReference/Welcome.html)。

```
aws quicksight register-user \
    --aws-account-id 111122223333 \
    --namespace default \
    --identity-type IAM\
    --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_generative_qna_role" \
    --user-role READER \
    --user-name jhnd \
    --session-name "john.doe@example.com" \
    --email john.doe@example.com \
    --region us-east-1 \
    --custom-permissions-name TeamA1
```

如果用户通过 Microsoft AD 进行身份验证，则无需使用 `RegisterUser` 进行设置。相反，他们应该在首次访问 Amazon Quick Sight 时自动订阅。对于 Microsoft AD 用户，您可以使用 `DescribeUser` 获取用户 Amazon 资源名称（ARN）。

用户首次访问 Amazon Quick Sight 时，您也可以将该用户添加到共享控制面板的群组中。以下示例显示了将用户添加到组的 CLI 命令。

```
aws quicksight create-group-membership \
    --aws-account-id 111122223333 \
    --namespace default \
    --group-name financeusers \
    --member-name "embedding_quicksight_q_generative_qna_role/john.doe@example.com"
```

现在，您的应用程序的用户也是 Amazon Quick Sight 的用户，并且可以访问控制面板。

最后，要获取控制面板的签名 URL，请从应用程序服务器中调用 `generate-embed-url-for-registered-user`。这会返回可嵌入的控制面板 URL。以下示例说明如何使用服务器端调用为通过身份验证 AWS Managed Microsoft AD 或单点登录（IAM Identity Center）进行身份验证的用户生成嵌入式控制面板的 URL。

```
aws quicksight generate-embed-url-for-anonymous-user \
--aws-account-id 111122223333 \
--namespace default-or-something-else \
--authorized-resource-arns '["topic-arn-topicId1","topic-arn-topicId2"]' \
--allowed-domains '["domain1","domain2"]' \
--experience-configuration 'GenerativeQnA={InitialTopicId="topicId1"}' \
--session-tags '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]' \
--session-lifetime-in-minutes 15
```

有关使用此操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在自己的代码中使用该 API 操作和其他操作。

### 步骤 3：嵌入生成式问答体验 URL
<a name="embedded-analytics-gen-bi-authenticated-users-step-3"></a>

在以下部分中，您可以了解如何将生成式问答体验嵌入网站或应用程序页面。你可以使用 [Amazon Quick Sight 嵌入式 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 来做到这一点。通过使用该开发工具包，您可以执行以下操作：
+ 将生成式问答体验放置到 HTML 页面上。
+ 自定义嵌入式体验的布局和外观以满足您的应用程序需求。
+ 使用为应用程序自定义的消息处理错误状态。

要生成可嵌入应用程序的 URL，请调用 `GenerateEmbedUrlForRegisteredUser` API 操作。该 URL 的有效时间为 5 分钟，生成的会话有效时间为 10 个小时。该 API 操作为 URL 提供 `auth_code` 值以启用单点登录会话。

下面显示了 `generate-embed-url-for-registered-user` 的示例响应：

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete. 
{
 "Status": "200",
"EmbedUrl": "https://quicksightdomain/embedding/12345/q/search...",
"RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 [Amazon Quick Sight 嵌入式 SDK 或将此 URL 添加到 iframe 中，将生成式问答体验嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会在窗口大小调整时更改视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。

确保用于托管嵌入式生成问答体验的域名位于*允许列表中*，这是您订阅 Amazon Quick Sight 的已批准域名列表。这一要求可阻止未经批准的域托管嵌入式控制面板，从而保护您的数据。有关为嵌入生成式问答体验添加域的更多信息，请参阅 [管理域名](manage-domains.md)。

您可以使用 Amazon Quick Sight Embedding SDK 自定义嵌入式生成问答体验的布局和外观，以适应您的应用程序。使用 `panelType` 属性配置生成式问答体验在您的应用程序中呈现时的着陆状态。将 `panelType` 属性设置为 `'FULL'` 以呈现完整的生成式问答体验面板。此面板类似于 Amazon Quick Sight 用户在 Amazon Quick Sight 控制台中的体验。面板的框架高度不会根据用户交互进行更改，并且会遵循您在 `frameOptions.height` 属性中设置的值。下图显示了当您将 `panelType` 值设置为 `'FULL'` 时呈现的生成式问答体验面板。

将 `panelType` 属性设置为 `'SEARCH_BAR'`，以将生成式问答体验呈现为搜索栏。该搜索栏类似于 Q 搜索栏嵌入到应用程序中时的呈现方式。生成式问答搜索栏扩展到更大的面板，其显示主题选择选项、问题建议列表、答案面板或 Pinboard。

当嵌入资产加载时，会呈现生成式问答搜索栏的默认最小高度。建议您将 `frameOptions.height` 值设置为 `"38px"`，以优化搜索栏体验。使用 `focusedHeight` 属性设置主题选择下拉列表和问题建议列表的最佳大小。使用 `expandedHeight` 属性设置答案面板和 Pinboard 的最佳大小。如果选择 `'SEARCH_BAR'` 选项，则建议您使用 position;absolute 设置父容器的样式，以避免应用程序中出现不必要的内容移动。下图显示了当您将 `panelType` 值设置为 `'SEARCH_BAR'` 时呈现的生成式问答体验搜索栏。

配置`panelType`属性后，使用 Amazon Quick Sight 嵌入式 SDK 自定义生成问答体验的以下属性。
+ 生成式问答面板的标题（仅适用于 `panelType: FULL` 选项）。
+ 搜索栏的占位符文本。
+ 是否允许选择主题。
+ 主题名称是显示还是隐藏。
+ Amazon Q 图标是显示还是隐藏（仅适用于 `panelType: FULL` 选项）。
+ Pinboard 是显示还是隐藏。
+ 用户是否可以将生成式问答面板最大化为全屏显示。
+ 生成式问答面板的主题。可以在 SDK 中传递自定义主题 ARN 来更改框架内容的外观。嵌入式生成式 BI 面板不支持 Amazon Quick Sight 入门主题。要使用 Amazon Quick Sight 入门主题，请将其另存为亚马逊 Quick Sight 中的自定义主题。

当您使用 Amazon Quick Sight Embedging SDK 时，页面上的生成式问答体验会根据状态动态调整大小。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制生成问答体验中的参数，并接收有关页面加载完成、状态更改和错误的回调。

以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。

#### SDK 2.0
<a name="collapsible-gen-bi-embedding-example"></a>

```
<!DOCTYPE html>
<html>
    <head>
        <title>Generative Q&A Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.7.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedGenerativeQnA = async() => {    
                const {createEmbeddingContext} = QuickSightEmbedding;

                const embeddingContext = await createEmbeddingContext({
                    onChange: (changeEvent, metadata) => {
                        console.log('Context received a change', changeEvent, metadata);
                    },
                });

                const frameOptions = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: '#experience-container',
                    height: "700px",
                    width: "1000px",
                    onChange: (changeEvent, metadata) => {
                        switch (changeEvent.eventName) {
                            case 'FRAME_MOUNTED': {
                                console.log("Do something when the experience frame is mounted.");
                                break;
                            }
                            case 'FRAME_LOADED': {
                                console.log("Do something when the experience frame is loaded.");
                                break;
                            }
                        }
                    },
                };

                const contentOptions = {
                    // Optional panel settings. Default behavior is equivalent to {panelType: 'FULL'}
                    panelOptions: {
                        panelType: 'FULL',
                        title: 'custom title', // Optional
                        showQIcon: false, // Optional, Default: true
                    },
                    // Use SEARCH_BAR panel type for the landing state to be similar to embedQSearchBar
                    // with generative capability enabled topics
                    /*
                    panelOptions: {
                        panelType: 'SEARCH_BAR',
                        focusedHeight: '250px',
                        expandedHeight: '500px',
                    },
                    */
                    showTopicName: false, // Optional, Default: true
                    showPinboard: false, // Optional, Default: true
                    allowTopicSelection: false, // Optional, Default: true
                    allowFullscreen: false, // Optional, Default: true
                    searchPlaceholderText: "custom search placeholder", // Optional
                    themeOptions: { // Optional
                        themeArn: 'arn:aws:quicksight:<Region>:<AWS-Account-ID>:theme/<Theme-ID>'
                    }
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'Q_SEARCH_OPENED': {
                                // called when pinboard is shown / visuals are rendered
                                console.log("Do something when SEARCH_BAR type panel is expanded");
                                break;
                            }
                            case 'Q_SEARCH_FOCUSED': {
                                // called when question suggestions or topic selection dropdown are shown
                                console.log("Do something when SEARCH_BAR type panel is focused");
                                break;
                            }
                            case 'Q_SEARCH_CLOSED': {
                                // called when shrinked to initial bar height
                                console.log("Do something when SEARCH_BAR type panel is collapsed");
                                break;
                            }
                            case 'Q_PANEL_ENTERED_FULLSCREEN': {
                                console.log("Do something when panel enters full screen mode");
                                break;
                            }
                            case 'Q_PANEL_EXITED_FULLSCREEN': {
                                console.log("Do something when panel exits full screen mode");
                                break;
                            }
                            case 'CONTENT_LOADED': {
                                console.log("Do something after experience is loaded");
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Do something when experience fails to load");
                                break;
                            }
                        }
                    }
                };
                const embeddedGenerativeQnExperience = await embeddingContext.embedGenerativeQnA(frameOptions, contentOptions);
            };
        </script>
    </head>

    <body onload="embedGenerativeQnA()">
        <div id="experience-container"></div>
    </body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 在您的网站上加载嵌入式生成问答体验 JavaScript。要获取副本，请执行下列操作之一：
+ 从中下载 [Amazon Quick Sight 嵌入 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) GitHub。该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

### 可选的嵌入生成式问答体验功能
<a name="embedded-analytics-gen-bi-authenticated-users-step-4"></a>

以下可选功能可用于使用 Embedding SDK 的嵌入生成式问答体验。

#### 调用生成式问答搜索栏操作
<a name="w2aac35c27c21c43c29b9c21b5"></a>
+ 设置问题 — 此功能将问题发送到生成式问答体验并立即查询问题。

  ```
  embeddedGenerativeQnExperience.setQuestion('show me monthly revenue');
  ```
+ 关闭答案面板（适用于生成式问答搜索栏选项）— 此功能将关闭答案面板并将 iframe 返回到原始搜索栏状态。

  ```
  embeddedGenerativeQnExperience.close();
  ```

有关更多信息，请参阅 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

## 将 Amazon Q 嵌入匿名（未注册）用户的快速生成问答体验中
<a name="embedded-analytics-gen-bi-anonymous-users"></a>


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在以下部分中，您可以了解有关如何为匿名（未注册）用户设置嵌入生成式问答体验的详细信息。

**Topics**
+ [

### 步骤 1：设置权限
](#embedded-analytics-gen-bi-anonymous-users-step-1)
+ [

### 步骤 2：生成附带身份验证代码的 URL
](#embedded-analytics-gen-bi-anonymous-users-step-2)
+ [

### 步骤 3：嵌入生成式问答体验 URL
](#embedded-analytics-gen-bi-anonymous-users-step-3)
+ [

### 可选的嵌入生成式问答体验功能
](#embedded-analytics-gen-bi-anonymous-users-step-4)

### 步骤 1：设置权限
<a name="embedded-analytics-gen-bi-anonymous-users-step-1"></a>

在以下部分中，您可以了解如何设置后端应用程序或 Web 服务器的权限来嵌入生成式问答体验。此任务需要对 AWS Identity and Access Management (IAM) 的管理权限。

每位访问生成式问答体验的用户都扮演一个角色，为他们授予 Amazon Quick Sight 访问权限和权限。要实现该目的，请在您的 AWS 账户中创建一个 IAM 角色。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。IAM 角色需要提供权限才能检索特定用户池 URLs 的嵌入内容。

借助通配符 *\$1*，您可以授予为特定命名空间中的所有用户生成 URL 的权限。您也可以授予为特定命名空间中的一部分用户生成 URL 的权限。为此，请添加 `quicksight:GenerateEmbedUrlForAnonymousUser`。

您可以在 IAM 策略中创建一个条件，限制开发人员可以在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 参数中列出的域。`AllowedDomains` 参数是可选参数。它允许开发者选择覆盖在 “**管理 Amazon Quick Sight**” 菜单中配置的静态域，而是列出最多三个可以访问生成的 URL 的域名或子域名。然后，此 URL 会嵌入开发人员的网站。只有参数中列出的域才能访问嵌入式 Q 搜索栏。如果没有此条件，开发人员可以在 `AllowedDomains` 参数中列出互联网上的任何域。

要限制开发人员可用于此参数的域，请在 IAM 策略中添加一个 `AllowedEmbeddingDomains` 条件。有关该`AllowedDomains`参数的更多信息，请参阅 *Amazon Quick Sight API 参考[GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)*中的。

**IAM 条件运算符的安全最佳实践**  
配置不当的 IAM 条件运算符可能会允许未经授权地通过 URL 变体访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用`quicksight:AllowedEmbeddingDomains`条件密钥时，请使用条件运算符，允许特定域名或拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息，请参阅 [IAM 用户指南中的 IAM JSON 策略元素：条件运算符](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
许多不同的网址变体可以指向同一个资源。例如，以下 URLs 所有内容都解析为相同的内容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的策略使用的运算符不考虑这些 URL 变体，则攻击者可以通过提供等效的 URL 变体来绕过您的限制。  
您必须验证您的 IAM 策略是否使用了适当的条件运算符来防止绕过漏洞，并确保只有您的目标域才能访问您的嵌入式资源。

您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，在用户访问您的应用程序时，您的应用程序可以代表用户代入该角色，以加载生成式问答体验。下面演示了一个示例信任策略。

------
#### [ JSON ]

****  

```
{
"Version":"2012-10-17",		 	 	 
    "Statement": [
        {
"Sid": "AllowLambdaFunctionsToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
"Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        {
"Sid": "AllowEC2InstancesToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
"Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

------

有关信任策略的更多信息，请参阅《IAM 用户指南》**中的 [IAM 临时安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)

### 步骤 2：生成附带身份验证代码的 URL
<a name="embedded-analytics-gen-bi-anonymous-users-step-2"></a>

在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入 Q 主题 URL。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，如果该用户尚不存在，则该应用程序会将该用户添加到 Amazon Quick Sight。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

#### Java
<a name="embedded-analytics-gen-bi-anonymous-users-java"></a>

```
import java.util.List;
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.AnonymousUserGenerativeQnAEmbeddingConfiguration;
import com.amazonaws.services.quicksight.model.AnonymousUserEmbeddingExperienceConfiguration;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserResult;
import com.amazonaws.services.quicksight.model.SessionTag;

/**
* Class to call QuickSight AWS SDK to generate embed url for anonymous user.
*/
public class GenerateEmbedUrlForAnonymousUserExample {

    private final AmazonQuickSight quickSightClient;

    public GenerateEmbedUrlForAnonymousUserExample() {
        quickSightClient = AmazonQuickSightClientBuilder
            .standard()
            .withRegion(Regions.US_EAST_1.getName())
            .withCredentials(new AWSCredentialsProvider() {
                    @Override
                    public AWSCredentials getCredentials() {
                        // provide actual IAM access key and secret key here
                        return new BasicAWSCredentials("access-key", "secret-key");
                    }

                    @Override
                    public void refresh() {
                    }
                }
            )
            .build();
    }

    public String GenerateEmbedUrlForAnonymousUser(
        final String accountId, // YOUR AWS ACCOUNT ID
        final String initialTopicId, // Q TOPIC ID TO WHICH THE CONSTRUCTED URL POINTS AND EXPERIENCE PREPOPULATES INITIALLY
        final String namespace, // ANONYMOUS EMBEDDING REQUIRES SPECIFYING A VALID NAMESPACE FOR WHICH YOU WANT THE EMBEDDING URL
        final List<String> authorizedResourceArns, // Q TOPIC ARN LIST TO EMBED
        final List<String> allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
        final List<SessionTag> sessionTags // SESSION TAGS USED FOR ROW-LEVEL SECURITY
    ) throws Exception {
        AnonymousUserEmbeddingExperienceConfiguration experienceConfiguration = new AnonymousUserEmbeddingExperienceConfiguration();
        AnonymousUserGenerativeQnAEmbeddingConfiguration generativeQnAConfiguration = new AnonymousUserGenerativeQnAEmbeddingConfiguration();
        generativeQnAConfiguration.setInitialTopicId(initialTopicId);
        experienceConfiguration.setGenerativeQnA(generativeQnAConfiguration);

        GenerateEmbedUrlForAnonymousUserRequest generateEmbedUrlForAnonymousUserRequest = new GenerateEmbedUrlForAnonymousUserRequest()
            .withAwsAccountId(accountId)
            .withNamespace(namespace)
            .withAuthorizedResourceArns(authorizedResourceArns)
            .withExperienceConfiguration(experienceConfiguration)
            .withSessionTags(sessionTags)
            .withSessionLifetimeInMinutes(600L); // OPTIONAL: VALUE CAN BE [15-600]. DEFAULT: 600
            .withAllowedDomains(allowedDomains);

        GenerateEmbedUrlForAnonymousUserResult result = quickSightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserRequest);

        return result.getEmbedUrl();
    }

}
```

#### JavaScript
<a name="embedded-analytics-gen-bi-anonymous-users-js"></a>

**注意**  
 APIs 不能直接从浏览器调用嵌入网址生成。请改为参考 Node.JS 示例。

#### Python3
<a name="embedded-analytics-gen-bi-anonymous-users-py"></a>

```
import json
import boto3
from botocore.exceptions import ClientError
import time

# Create QuickSight and STS clients
quicksightClient = boto3.client('quicksight',region_name='us-west-2')
sts = boto3.client('sts')

# Function to generate embedded URL for anonymous user
# accountId: YOUR AWS ACCOUNT ID
# topicId: Topic ID to embed
# quicksightNamespace: VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
# authorizedResourceArns: TOPIC ARN LIST TO EMBED
# allowedDomains: RUNTIME ALLOWED DOMAINS FOR EMBEDDING
# sessionTags: SESSION TAGS USED FOR ROW-LEVEL SECURITY
def generateEmbedUrlForAnonymousUser(accountId, quicksightNamespace, authorizedResourceArns, allowedDomains, sessionTags):
    try:
        response = quicksightClient.generate_embed_url_for_anonymous_user(
            AwsAccountId = accountId,
            Namespace = quicksightNamespace,
            AuthorizedResourceArns = authorizedResourceArns,
            AllowedDomains = allowedDomains,
            ExperienceConfiguration = {
                'GenerativeQnA': {
                        'InitialTopicId': topicId
                    }
            },
            SessionTags = sessionTags,
            SessionLifetimeInMinutes = 600
        )
            
        return {
            'statusCode': 200,
            'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
            'body': json.dumps(response),
            'isBase64Encoded':  bool('false')
        }
    except ClientError as e:
        print(e)
        return "Error generating embeddedURL: " + str(e)
```

#### Node.js
<a name="embedded-analytics-gen-bi-anonymous-users-node"></a>

以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 URL 的 JavaScript (Node.js)。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
const AWS = require('aws-sdk');
const https = require('https');

var quicksightClient = new AWS.Service({
    region: 'us-east-1',
});

quicksightClient.generateEmbedUrlForAnonymousUser({
    'AwsAccountId': '111122223333',
    'Namespace': 'DEFAULT'
    'AuthorizedResourceArns': '["topic-arn-topicId1","topic-arn-topicId2"]',
    'AllowedDomains': allowedDomains,
    'ExperienceConfiguration': { 
        'GenerativeQnA': {
            'InitialTopicId': 'U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f'
        }
    },
    'SessionTags': '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]',
    'SessionLifetimeInMinutes': 15
}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

#### .NET/C\$1
<a name="embedded-analytics-gen-bi-anonymous-users-cs"></a>

以下示例演示了可以在应用程序服务器上使用以生成嵌入式 Q 搜索栏 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用此 URL 以显示 Q 搜索栏。

**Example**  

```
using System;
using Amazon.QuickSight;
using Amazon.QuickSight.Model;

namespace GenerateGenerativeQnAEmbedUrlForAnonymousUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                AnonymousUserGenerativeQnAEmbeddingConfiguration anonymousUserGenerativeQnAEmbeddingConfiguration
                    = new AnonymousUserGenerativeQnAEmbeddingConfiguration
                    {
                        InitialTopicId = "U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f"
                    };
                AnonymousUserEmbeddingExperienceConfiguration anonymousUserEmbeddingExperienceConfiguration
                    = new AnonymousUserEmbeddingExperienceConfiguration
                    {
                        GenerativeQnA = anonymousUserGenerativeQnAEmbeddingConfiguration
                    }; 
                
                Console.WriteLine(
                    quicksightClient.GenerateEmbedUrlForAnonymousUserAsync(new GenerateEmbedUrlForAnonymousUserRequest
                    {
                        AwsAccountId = "111122223333",
                        Namespace = "DEFAULT",
                        AuthorizedResourceArns '["topic-arn-topicId1","topic-arn-topicId2"]',
                        AllowedDomains = allowedDomains,
                        ExperienceConfiguration = anonymousUserEmbeddingExperienceConfiguration,
                        SessionTags = '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]',
                        SessionLifetimeInMinutes = 15,
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
```

#### AWS CLI
<a name="embedded-analytics-gen-bi-anonymous-users-cli"></a>

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用 SAML 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GenerateEmbedUrlForAnonymousUser` 启用权限。

```
aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_generative_qna_role" \
     --role-session-name anonymous caller
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。对于 Microsoft Windows 计算机，请使用 `set` 而不是 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_q_search_bar_role/QuickSightEmbeddingAnonymousPolicy`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个用户设置相应的权限。此外，它还能避免任何用户访问限制。*限制*是一项安全功能，可防止同一个用户从多个位置访问 Amazon Quick Sight。它还能使每个会话保持独立和独特。如果您使用一组 Web 服务器（例如用于负载平衡），并且会话重新连接到其他服务器，则会开始新的会话。

要获取控制面板的签名 URL，请从应用程序服务器中调用 `generate-embed-url-for-anynymous-user`。这会返回可嵌入的控制面板 URL。以下示例演示了如何使用服务器端调用为匿名访问您 Web 门户或应用程序的用户生成嵌入式控制面板的 URL。

```
aws quicksight generate-embed-url-for-anonymous-user \
--aws-account-id 111122223333 \
--namespace default-or-something-else \
--authorized-resource-arns '["topic-arn-topicId","topic-arn-topicId2"]' \
--allowed-domains '["domain1","domain2"]' \
--experience-configuration 'GenerativeQnA={InitialTopicId="topicId1"}' \
--session-tags '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]' \
--session-lifetime-in-minutes 15
```

有关使用此操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)。您可以在自己的代码中使用该 API 操作和其他操作。

### 步骤 3：嵌入生成式问答体验 URL
<a name="embedded-analytics-gen-bi-anonymous-users-step-3"></a>

在以下部分中，您可以了解如何将生成式问答体验嵌入网站或应用程序页面。你可以使用 [Amazon Quick Sight 嵌入式 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 来做到这一点。通过使用该开发工具包，您可以执行以下操作：
+ 将生成式问答体验放置到 HTML 页面上。
+ 自定义嵌入式体验的布局和外观以满足您的应用程序需求。
+ 使用为应用程序自定义的消息处理错误状态。

要生成可嵌入应用程序的 URL，请调用 `GenerateEmbedUrlForAnonymousUser` API 操作。该 URL 的有效时间为 5 分钟，生成的会话有效时间为 10 个小时。该 API 操作为 URL 提供 `auth_code` 值以启用单点登录会话。

下面显示了 `generate-embed-url-for-anonymous-user` 的示例响应：

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.{
     "Status": "200",
     "EmbedUrl": "https://quicksightdomain/embedding/12345/q/search...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 [Amazon Quick Sight 嵌入式 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 或将此 URL 添加到 iframe 中，将生成式问答体验嵌入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会在窗口大小调整时更改视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。

确保托管生成问答体验的域名位于*允许列表中*，这是您订阅 Amazon Quick Sight 的已批准域名列表。此要求可阻止未经批准的域托管嵌入生成式问答体验，从而保护您的数据。有关为嵌入生成式问答体验添加域的更多信息，请参阅 [管理域名](manage-domains.md)。

您可以使用 Amazon Quick Sight Embedding SDK 自定义嵌入式生成问答体验的布局和外观，以适应您的应用程序。使用 `panelType` 属性配置生成式问答体验在您的应用程序中呈现时的着陆状态。将 `panelType` 属性设置为 `'FULL'` 以呈现完整的生成式问答体验面板。此面板类似于 Amazon Quick Sight 用户在 Amazon Quick Sight 控制台中的体验。面板的框架高度不会根据用户交互进行更改，并且会遵循您在 `frameOptions.height` 属性中设置的值。下图显示了当您将 `panelType` 值设置为 `'FULL'` 时呈现的生成式问答体验面板。

将 `panelType` 属性设置为 `'SEARCH_BAR'`，以将生成式问答体验呈现为搜索栏。该搜索栏类似于 Q 搜索栏嵌入到应用程序中时的呈现方式。生成式问答搜索栏扩展到更大的面板，其显示主题选择选项、问题建议列表、答案面板或 Pinboard。

当嵌入资产加载时，会呈现生成式问答搜索栏的默认最小高度。建议您将 `frameOptions.height` 值设置为 `"38px"`，以优化搜索栏体验。使用 `focusedHeight` 属性设置主题选择下拉列表和问题建议列表的最佳大小。使用 `expandedHeight` 属性设置答案面板和 Pinboard 的最佳大小。如果选择 `'SEARCH_BAR'` 选项，则建议您使用 position;absolute 设置父容器的样式，以避免应用程序中出现不必要的内容移动。下图显示了当您将 `panelType` 值设置为 `'SEARCH_BAR'` 时呈现的生成式问答体验搜索栏。

配置`panelType`属性后，使用 Amazon Quick Sight 嵌入式 SDK 自定义生成问答体验的以下属性。
+ 生成式问答面板的标题（仅适用于 `panelType: FULL` 选项）。
+ 搜索栏的占位符文本。
+ 是否允许选择主题。
+ 主题名称是显示还是隐藏。
+ Amazon Q 图标是显示还是隐藏（仅适用于 `panelType: FULL` 选项）。
+ Pinboard 是显示还是隐藏。
+ 用户是否可以将生成式问答面板最大化为全屏显示。
+ 生成式问答面板的主题。可以在 SDK 中传递自定义主题 ARN 来更改框架内容的外观。嵌入式生成式 BI 面板不支持 Amazon Quick Sight 入门主题。要使用 Amazon Quick Sight 入门主题，请将其另存为亚马逊 Quick Sight 中的自定义主题。

当您使用 Amazon Quick Sight Embedging SDK 时，页面上的生成式问答体验会根据状态动态调整大小。借助 Amazon Quick Sight Embedding SDK，您还可以控制生成问答体验中的参数，并接收有关页面加载完成、状态更改和错误的回调。

以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。

#### SDK 2.0
<a name="embedded-analytics-gen-bi-anonymous-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>
    <head>
        <title>Generative Q&A Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.7.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedGenerativeQnA = async() => {    
                const {createEmbeddingContext} = QuickSightEmbedding;

                const embeddingContext = await createEmbeddingContext({
                    onChange: (changeEvent, metadata) => {
                        console.log('Context received a change', changeEvent, metadata);
                    },
                });

                const frameOptions = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: '#experience-container',
                    height: "700px",
                    width: "1000px",
                    onChange: (changeEvent, metadata) => {
                        switch (changeEvent.eventName) {
                            case 'FRAME_MOUNTED': {
                                console.log("Do something when the experience frame is mounted.");
                                break;
                            }
                            case 'FRAME_LOADED': {
                                console.log("Do something when the experience frame is loaded.");
                                break;
                            }
                        }
                    },
                };

                const contentOptions = {
                    // Optional panel settings. Default behavior is equivalent to {panelType: 'FULL'}
                    panelOptions: {
                        panelType: 'FULL',
                        title: 'custom title', // Optional
                        showQIcon: false, // Optional, Default: true
                    },
                    // Use SEARCH_BAR panel type for the landing state to be similar to embedQSearchBar
                    // with generative capability enabled topics
                    /*
                    panelOptions: {
                        panelType: 'SEARCH_BAR',
                        focusedHeight: '250px',
                        expandedHeight: '500px',
                    },
                    */
                    showTopicName: false, // Optional, Default: true
                    showPinboard: false, // Optional, Default: true
                    allowTopicSelection: false, // Optional, Default: true
                    allowFullscreen: false, // Optional, Default: true
                    searchPlaceholderText: "custom search placeholder", // Optional
                    themeOptions: { // Optional
                        themeArn: 'arn:aws:quicksight:<Region>:<AWS-Account-ID>:theme/<Theme-ID>'
                    }
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'Q_SEARCH_OPENED': {
                                // called when pinboard is shown / visuals are rendered
                                console.log("Do something when SEARCH_BAR type panel is expanded");
                                break;
                            }
                            case 'Q_SEARCH_FOCUSED': {
                                // called when question suggestions or topic selection dropdown are shown
                                console.log("Do something when SEARCH_BAR type panel is focused");
                                break;
                            }
                            case 'Q_SEARCH_CLOSED': {
                                // called when shrinked to initial bar height
                                console.log("Do something when SEARCH_BAR type panel is collapsed");
                                break;
                            }
                            case 'Q_PANEL_ENTERED_FULLSCREEN': {
                                console.log("Do something when panel enters full screen mode");
                                break;
                            }
                            case 'Q_PANEL_EXITED_FULLSCREEN': {
                                console.log("Do something when panel exits full screen mode");
                                break;
                            }
                            case 'CONTENT_LOADED': {
                                console.log("Do something after experience is loaded");
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Do something when experience fails to load");
                                break;
                            }
                        }
                    }
                };
                const embeddedGenerativeQnExperience = await embeddingContext.embedGenerativeQnA(frameOptions, contentOptions);
            };
        </script>
    </head>

    <body onload="embedGenerativeQnA()">
        <div id="experience-container"></div>
    </body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 在您的网站上加载嵌入式生成问答体验 JavaScript。要获取副本，请执行下列操作之一：
+ 从中下载 [Amazon Quick Sight 嵌入 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) GitHub。该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

### 可选的嵌入生成式问答体验功能
<a name="embedded-analytics-gen-bi-anonymous-users-step-4"></a>

以下可选功能可用于使用 Embedding SDK 的嵌入生成式问答体验。

#### 调用生成式问答搜索栏操作
<a name="w2aac35c27c21c43c29c13c25b5"></a>
+ 设置问题 — 此功能将问题发送到生成式问答体验并立即查询问题。

  ```
  embeddedGenerativeQnExperience.setQuestion('show me monthly revenue');
  ```
+ 关闭答案面板（适用于生成式问答搜索栏选项）— 此功能将关闭答案面板并将 iframe 返回到原始搜索栏状态。

  ```
  embeddedGenerativeQnExperience.close();
  ```

有关更多信息，请参阅 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

# 嵌入 Amazon Quick Sight Q 搜索栏（经典版）
<a name="embedding-quicksight-q"></a>


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

使用以下主题了解如何将 Amazon Quick Sight Q 搜索栏嵌入 Amazon Quick Sight APIs。

**Topics**
+ [

# 为注册用户嵌入 Amazon Quick Sight Q 搜索栏
](embedded-analytics-q-search-bar-for-authenticated-users.md)
+ [

# 为匿名（未注册）用户嵌入 Amazon Quick Sight Q 搜索栏
](embedded-analytics-q-search-bar-for-anonymous-users.md)

# 为注册用户嵌入 Amazon Quick Sight Q 搜索栏
<a name="embedded-analytics-q-search-bar-for-authenticated-users"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在以下各节中，您可以找到有关如何为 Amazon Quick Sight 的注册用户设置嵌入式 Amazon Quick Sight Q 搜索栏的详细信息。

**Topics**
+ [

## 步骤 1：设置权限
](#embedded-q-bar-for-authenticated-users-step-1)
+ [

## 步骤 2：生成附带身份验证代码的 URL
](#embedded-q-bar-for-authenticated-users-step-2)
+ [

## 步骤 3：嵌入 Q 搜索栏 URL
](#embedded-q-bar-for-authenticated-users-step-3)
+ [

## 可选的 Amazon Quick Sight Q 搜索栏嵌入功能
](#embedded-q-bar-for-authenticated-users-step-4)

## 步骤 1：设置权限
<a name="embedded-q-bar-for-authenticated-users-step-1"></a>

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在以下部分中，您可以了解如何设置后端应用程序或 Web 服务器的权限来嵌入 Q 搜索栏。此任务需要对 AWS Identity and Access Management (IAM) 的管理权限。

每个访问控制面板的用户都扮演一个角色，授予他们 Amazon Quick Sight 访问控制面板的权限和权限。要实现这一点，请在您的中创建一个 IAM 角色 AWS 账户。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。IAM 角色需要提供权限才能检索特定用户池 URLs 的嵌入内容。

借助通配符 *\$1*，您可以授予为特定命名空间中的所有用户生成 URL 的权限。您也可以授予为特定命名空间中的一部分用户生成 URL 的权限。为此，请添加 `quicksight:GenerateEmbedUrlForRegisteredUser`。

您可以在 IAM 策略中创建一个条件，限制开发人员可以在 `GenerateEmbedUrlForRegisteredUser` API 操作的 `AllowedDomains` 参数中列出的域。`AllowedDomains` 参数是可选参数。它允许开发者选择覆盖在 “**管理 Amazon Quick Sight**” 菜单中配置的静态域，而是列出最多三个可以访问生成的 URL 的域名或子域名。然后，此 URL 会嵌入开发人员的网站。只有参数中列出的域才能访问嵌入式 Q 搜索栏。如果没有此条件，开发人员可以在 `AllowedDomains` 参数中列出互联网上的任何域。

要限制开发人员可用于此参数的域，请在 IAM 策略中添加一个 `AllowedEmbeddingDomains` 条件。有关该`AllowedDomains`参数的更多信息，请参阅 *Amazon Quick Sight API 参考[GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)*中的。

**IAM 条件运算符的安全最佳实践**  
配置不当的 IAM 条件运算符可能会允许未经授权地通过 URL 变体访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用`quicksight:AllowedEmbeddingDomains`条件密钥时，请使用条件运算符，允许特定域名或拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息，请参阅 [IAM 用户指南中的 IAM JSON 策略元素：条件运算符](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
许多不同的网址变体可以指向同一个资源。例如，以下 URLs 所有内容都解析为相同的内容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的策略使用的运算符不考虑这些 URL 变体，则攻击者可以通过提供等效的 URL 变体来绕过您的限制。  
您必须验证您的 IAM 策略是否使用了适当的条件运算符来防止绕过漏洞，并确保只有您的目标域才能访问您的嵌入式资源。

以下示例策略提供了这些权限。

此外，如果您要创建将成为 Amazon Quick Sight 读者的首次用户，请务必在策略中添加`quicksight:RegisterUser`权限。

以下示例策略为即将成为 Amazon Quick Sight 读者的首次用户提供了检索嵌入网址的权限。

最后，您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，当用户访问您的应用程序时，您的应用程序可以代表用户担任该角色并在 Amazon Quick Sight 中配置用户。

下面演示了一个示例信任策略。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowLambdaFunctionsToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        {
            "Sid": "AllowEC2InstancesToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

------

有关 OpenID Connect 或安全断言标记语言（SAML）身份验证的信任策略的更多信息，请参阅《IAM 用户指南**》的以下章节：
+ [创建用于 Web 联合身份验证或 OpenID Connect 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [创建用于 SAML 2.0 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

## 步骤 2：生成附带身份验证代码的 URL
<a name="embedded-q-bar-for-authenticated-users-step-2"></a>

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入 Q 主题 URL。如果您计划为 IAM 或 Amazon Quick Sight 身份类型嵌入 Q 栏，请与用户共享 Q 主题。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，如果该用户尚不存在，则该应用程序会将该用户添加到 Amazon Quick Sight。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

执行上述步骤可确保在 Amazon Quick Sight 中对 Q 主题的每位查看者进行唯一配置。它还实施每个用户的设置，例如，行级别安全性和参数的动态默认值。

以下示例展示了代表用户执行 IAM 身份验证。此代码在您的应用程序服务器上运行。

### Java
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-java"></a>

```
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
        import com.amazonaws.auth.AWSCredentialsProvider;
        import com.amazonaws.regions.Regions;
        import com.amazonaws.services.quicksight.AmazonQuickSight;
        import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserResult;
import com.amazonaws.services.quicksight.model.RegisteredUserEmbeddingExperienceConfiguration;
import com.amazonaws.services.quicksight.model.RegisteredUserQSearchBarEmbeddingConfiguration;

        /**
 * Class to call QuickSight AWS SDK to get url for embedding the Q search bar.
        */
public class RegisteredUserQSearchBarEmbeddingConfiguration {

            private final AmazonQuickSight quickSightClient;

    public RegisteredUserQSearchBarEmbeddingConfiguration() {
        this.quickSightClient = AmazonQuickSightClientBuilder
                    .standard()
                    .withRegion(Regions.US_EAST_1.getName())
                    .withCredentials(new AWSCredentialsProvider() {
                            @Override
                            public AWSCredentials getCredentials() {
                                // provide actual IAM access key and secret key here
                                return new BasicAWSCredentials("access-key", "secret-key");
                            }

                            @Override
                            public void refresh() {
                            }
                        }
                    )
                    .build();
            }

    public String getQuicksightEmbedUrl(
            final String accountId, // AWS Account ID
            final String topicId, // Topic ID to embed
            final List<String> allowedDomains, // Runtime allowed domain for embedding
            final String userArn // Registered user arn to use for embedding. Refer to Get Embed Url section in developer portal to find how to get user arn for a QuickSight user.
            ) throws Exception {
        final RegisteredUserEmbeddingExperienceConfiguration experienceConfiguration = new RegisteredUserEmbeddingExperienceConfiguration()
                .withQSearchBar(new RegisteredUserQSearchBarEmbeddingConfiguration().withInitialTopicId(topicId));
        final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest = new GenerateEmbedUrlForRegisteredUserRequest();
        generateEmbedUrlForRegisteredUserRequest.setAwsAccountId(accountId);
        generateEmbedUrlForRegisteredUserRequest.setUserArn(userArn);
        generateEmbedUrlForRegisteredUserRequest.setAllowedDomains(allowedDomains);
        generateEmbedUrlForRegisteredUserRequest.setExperienceConfiguration(QSearchBar);

        final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);

        return generateEmbedUrlForRegisteredUserResult.getEmbedUrl();
            }
        }
```

### JavaScript
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-js"></a>

```
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function generateEmbedUrlForRegisteredUser(
    accountId,
    topicId, // Topic ID to embed
    openIdToken, // Cognito-based token
    userArn, // registered user arn
    roleArn, // IAM user role to use for embedding
    sessionName, // Session name for the roleArn assume role
    allowedDomains, // Runtime allowed domain for embedding
    getEmbedUrlCallback, // GetEmbedUrl success callback method
    errorCallback // GetEmbedUrl error callback method
    ) {
    const stsClient = new AWS.STS();
    let stsParams = {
        RoleSessionName: sessionName,
        WebIdentityToken: openIdToken,
        RoleArn: roleArn
        }
    
    stsClient.assumeRoleWithWebIdentity(stsParams, function(err, data) {
        if (err) {
            console.log('Error assuming role');
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const getQSearchBarParams = {
        "AwsAccountId": accountId,
                "ExperienceConfiguration": {
                    "QSearchBar": {
                        "InitialTopicId": topicId
                    }
                },
                "UserArn": userArn,
        "AllowedDomains": allowedDomains,
        "SessionLifetimeInMinutes": 600
    };

            const quicksightGetQSearchBar = new AWS.QuickSight({
        region: process.env.AWS_REGION,
                credentials: {
                    accessKeyId: data.Credentials.AccessKeyId,
                    secretAccessKey: data.Credentials.SecretAccessKey,
                    sessionToken: data.Credentials.SessionToken,
                    expiration: data.Credentials.Expiration
                }
    });

            quicksightGetQSearchBar.generateEmbedUrlForRegisteredUser(getQSearchBarParams, function(err, data) {
        if (err) {
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const result = {
                "statusCode": 200,
                "headers": {
                            "Access-Control-Allow-Origin": "*", // Use your website domain to secure access to GetEmbedUrl API
                    "Access-Control-Allow-Headers": "Content-Type"
                },
                "body": JSON.stringify(data),
                "isBase64Encoded": false
            }
                    getEmbedUrlCallback(result);
                }
            });
        }
    });
}
```

### Python3
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-python"></a>

```
import json
import boto3
from botocore.exceptions import ClientError

sts = boto3.client('sts')

# Function to generate embedded URL  
# accountId: AWS account ID
# topicId: Topic ID to embed
# userArn: arn of registered user
# allowedDomains: Runtime allowed domain for embedding
# roleArn: IAM user role to use for embedding
# sessionName: session name for the roleArn assume role
def getEmbeddingURL(accountId, topicId, userArn, allowedDomains, roleArn, sessionName):
    try:
        assumedRole = sts.assume_role(
            RoleArn = roleArn,
            RoleSessionName = sessionName,
        )
    except ClientError as e:
        return "Error assuming role: " + str(e)
    else: 
        assumedRoleSession = boto3.Session(
            aws_access_key_id = assumedRole['Credentials']['AccessKeyId'],
            aws_secret_access_key = assumedRole['Credentials']['SecretAccessKey'],
            aws_session_token = assumedRole['Credentials']['SessionToken'],
        )
        try:
            quicksightClient = assumedRoleSession.client('quicksight', region_name='us-west-2')
            response = quicksightClient.generate_embed_url_for_registered_user(
                AwsAccountId=accountId,
                ExperienceConfiguration = {
                    "QSearchBar": {
                        "InitialTopicId": topicId
                    }
                },
                UserArn = userArn,
                AllowedDomains = allowedDomains,
                SessionLifetimeInMinutes = 600
            )
            
            return {
                'statusCode': 200,
                'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
                'body': json.dumps(response),
                'isBase64Encoded':  bool('false')
            }
        except ClientError as e:
            return "Error generating embedding url: " + str(e)
```

### Node.js
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-node"></a>

以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 URL 的 JavaScript (Node.js)。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
const AWS = require('aws-sdk');
const https = require('https');

var quicksightClient = new AWS.Service({
    apiConfig: require('./quicksight-2018-04-01.min.json'),
    region: 'us-east-1',
});

quicksightClient.generateEmbedUrlForRegisteredUser({
    'AwsAccountId': '111122223333',
    'ExperienceConfiguration': { 
        'QSearchBar': {
            'InitialTopicId': 'U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f'
        }
    },
    'UserArn': 'REGISTERED_USER_ARN',
    'AllowedDomains': allowedDomains,
    'SessionLifetimeInMinutes': 100
}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

**Example**  

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
    { 
        Status: 200,
        EmbedUrl: "https://quicksightdomain/embed/12345/dashboards/67890/sheets/12345/visuals/67890...",
        RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' 
    }
```

### .NET/C\$1
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-cs"></a>

以下示例演示了可以在应用程序服务器上使用以生成嵌入式 Q 搜索栏 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用此 URL 以显示 Q 搜索栏。

**Example**  

```
using System;
using Amazon.QuickSight;
using Amazon.QuickSight.Model;

namespace GenerateDashboardEmbedUrlForRegisteredUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                RegisteredUserQSearchBarEmbeddingConfiguration registeredUserQSearchBarEmbeddingConfiguration
                    = new RegisteredUserQSearchBarEmbeddingConfiguration
                    {
                        InitialTopicId = "U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f"
                    };
                RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                    = new RegisteredUserEmbeddingExperienceConfiguration
                    {
                        QSearchBar = registeredUserQSearchBarEmbeddingConfiguration
                    }; 
                
                Console.WriteLine(
                    quicksightClient.GenerateEmbedUrlForRegisteredUserAsync(new GenerateEmbedUrlForRegisteredUserRequest
                    {
                        AwsAccountId = "111122223333",
                        ExperienceConfiguration = registeredUserEmbeddingExperienceConfiguration,
                        UserArn = "REGISTERED_USER_ARN",
                        AllowedDomains = allowedDomains,
                        SessionLifetimeInMinutes = 100
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
```

### AWS CLI
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-cli"></a>

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用 SAML 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GenerateEmbedUrlForRegisteredUser` 启用权限。如果您要在用户使用 Q 搜索栏中的主题时添加用户，则还需要为该角色启用权限`quicksight:RegisterUser`。 just-in-time

```
aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_search_bar_role" \
     --role-session-name john.doe@example.com
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。对于 Microsoft Windows 计算机，请使用 `set` 而不是 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_q_search_bar_role/john.doe@example.com`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个用户设置相应的权限。此外，它还能避免任何用户访问限制。*限制*是一项安全功能，可防止同一个用户从多个位置访问 Amazon Quick Sight。

角色会话 ID 也将成为 Amazon Quick Sight 中的用户名。您可以使用此模式提前在 Amazon Quick Sight 中配置用户，或者在他们首次访问 Q 搜索栏时为他们进行配置。

以下示例显示了可用于预置用户的 CLI 命令。有关[RegisterUser[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html)](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、和其他 Amazon Quick Sight API 操作的更多信息，请参阅 [Amazon Quick Sight API 参考](https://docs.aws.amazon.com/quicksight/latest/APIReference/Welcome.html)。

```
aws quicksight register-user \
    --aws-account-id 111122223333 \
    --namespace default \
    --identity-type IAM \
    --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_search_bar_role" \
    --user-role READER \
    --user-name jhnd \
    --session-name "john.doe@example.com" \
    --email john.doe@example.com \
    --region us-east-1 \
    --custom-permissions-name TeamA1
```

如果用户通过 Microsoft AD 进行身份验证，则无需使用 `RegisterUser` 进行设置。相反，他们应该在首次访问 Amazon Quick Sight 时自动订阅。对于 Microsoft AD 用户，您可以使用 `DescribeUser` 获取用户 Amazon 资源名称（ARN）。

用户首次访问 Amazon Quick Sight 时，您也可以将该用户添加到与之共享控制面板的群组中。以下示例显示了将用户添加到组的 CLI 命令。

```
aws quicksight create-group-membership \
    --aws-account-id=111122223333 \
    --namespace=default \
    --group-name=financeusers \
    --member-name="embedding_quicksight_q_search_bar_role/john.doe@example.com"
```

现在，您的应用程序的用户也是 Amazon Quick Sight 的用户，并且可以访问控制面板。

最后，要获取控制面板的签名 URL，请从应用程序服务器中调用 `generate-embed-url-for-registered-user`。这会返回可嵌入的控制面板 URL。以下示例说明如何使用服务器端调用为通过身份验证 AWS Managed Microsoft AD 或单点登录（IAM Identity Center）进行身份验证的用户生成嵌入式控制面板的 URL。

```
aws quicksight generate-embed-url-for-registered-user \
--aws-account-id 111122223333 \
--session-lifetime-in-minutes 600 \
--user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_q_search_bar_role/embeddingsession
--allowed-domains '["domain1","domain2"]' \
--experience-configuration QSearchBar={InitialTopicId=U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f}
```

有关使用此操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在自己的代码中使用该 API 操作和其他操作。

## 步骤 3：嵌入 Q 搜索栏 URL
<a name="embedded-q-bar-for-authenticated-users-step-3"></a>

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在以下部分中，您可以了解如何将步骤 3 中的 Q 搜索栏 URL 嵌入网站或应用程序页面。你可以使用 [Amazon Quick Sight 嵌入式 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 来做到这一点。通过使用该开发工具包，您可以执行以下操作：
+ 将 Q 搜索栏放置到 HTML 页面上。
+ 将参数传递到 Q 搜索栏。
+ 使用为应用程序自定义的消息处理错误状态。

要生成可嵌入应用程序的 URL，请调用 `GenerateEmbedUrlForRegisteredUser` API 操作。该 URL 的有效时间为 5 分钟，生成的会话有效时间为 10 个小时。该 API 操作为 URL 提供 `auth_code` 值以启用单点登录会话。

下面显示了 `generate-embed-url-for-registered-user` 的示例响应：

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
{
     "Status": "200",
     "EmbedUrl": "https://quicksightdomain/embedding/12345/q/search...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 [Amazon Quick Sight 嵌入式 SDK 或将此 URL 添加到 iframe 中，将 Q 搜索栏嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会在窗口大小调整时更改视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。

为此，请确保托管嵌入式 Q 搜索栏的域名位于*允许列表中*，即您的 Amazon Quick Sight 订阅的已批准域名列表。这一要求可阻止未经批准的域托管嵌入式控制面板，从而保护您的数据。有关为嵌入式 Q 搜索栏添加域名的更多信息，请参阅[管理域和嵌入](https://docs.aws.amazon.com/quicksight/latest/user/manage-qs-domains-and-embedding.html)。

当您使用 Amazon Quick Sight Embedding SDK 时，页面上的 Q 搜索栏会根据状态动态调整大小。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制 Q 搜索栏中的参数，并接收有关页面加载完成和错误的回调。

以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。

### SDK 2.0
<a name="embedded-q-bar-for-authenticated-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Q Search Bar Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedQSearchBar = async() => {    
                const {
                    createEmbeddingContext,
                } = QuickSightEmbedding;

                const embeddingContext = await createEmbeddingContext({
                    onChange: (changeEvent, metadata) => {
                        console.log('Context received a change', changeEvent, metadata);
                    },
                });

                const frameOptions = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: '#experience-container',
                    height: "700px",
                    width: "1000px",
                    onChange: (changeEvent, metadata) => {
                        switch (changeEvent.eventName) {
                            case 'FRAME_MOUNTED': {
                                console.log("Do something when the experience frame is mounted.");
                                break;
                            }
                            case 'FRAME_LOADED': {
                                console.log("Do something when the experience frame is loaded.");
                                break;
                            }
                        }
                    },
                };

                const contentOptions = {
                    hideTopicName: false, 
                    theme: '<YOUR_THEME_ID>',
                    allowTopicSelection: true,
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'Q_SEARCH_OPENED': {
                                console.log("Do something when Q Search content expanded");
                                break;
                            }
                            case 'Q_SEARCH_CLOSED': {
                                console.log("Do something when Q Search content collapsed");
                                break;
                            }
                            case 'Q_SEARCH_SIZE_CHANGED': {
                                console.log("Do something when Q Search size changed");
                                break;
                            }
                            case 'CONTENT_LOADED': {
                                console.log("Do something when the Q Search is loaded.");
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Do something when the Q Search fails loading.");
                                break;
                            }
                        }
                    }
                };
                const embeddedDashboardExperience = await embeddingContext.embedQSearchBar(frameOptions, contentOptions);
            };
        </script>
    </head>

    <body onload="embedQSearchBar()">
        <div id="experience-container"></div>
    </body>

</html>
```

### SDK 1.0
<a name="embedded-q-bar-for-authenticated-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>QuickSight Q Search Bar Embedding</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.18.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            var session

            function onError(payload) {
                console.log("Do something when the session fails loading");
            }

            function onOpen() {
                console.log("Do something when the Q search bar opens");
            }

            function onClose() {
                console.log("Do something when the Q search bar closes");
            }

            function embedQSearchBar() {
                var containerDiv = document.getElementById("embeddingContainer");
                var options = {
                    url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode", // replace this dummy url with the one generated via embedding API
                    container: containerDiv,
                    width: "1000px",
                    locale: "en-US",
                    qSearchBarOptions: {
                        expandCallback: onOpen,
                        collapseCallback: onClose,
                        iconDisabled: false,
                        topicNameDisabled: false, 
                        themeId: 'bdb844d0-0fe9-4d9d-b520-0fe602d93639',
                        allowTopicSelection: true
                    }
                };
                session = QuickSightEmbedding.embedQSearchBar(options);
                session.on("error", onError);
            }

            function onCountryChange(obj) {
                session.setParameters({country: obj.value});
            }
        </script>
    </head>

    <body onload="embedQSearchBar()">
        <div id="embeddingContainer"></div>
    </body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 将嵌入式控制面板加载到您的网站上 JavaScript。要获取副本，请执行下列操作之一：
+ 从中下载 [Amazon Quick Sight 嵌入 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) GitHub。该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

## 可选的 Amazon Quick Sight Q 搜索栏嵌入功能
<a name="embedded-q-bar-for-authenticated-users-step-4"></a>

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

以下可选功能可用于使用嵌入开发工具包的嵌入式 Q 搜索栏。

### 调用 Q 搜索栏操作
<a name="w2aac35c27c21c43c31c15c21b7"></a>

以下选项仅支持嵌入 Q 搜索栏。
+ 设置 Q 搜索栏问题 – 此功能将问题发送到 Q 搜索栏并立即查询问题。它还可以自动打开 Q 弹出框。

  ```
  qBar.setQBarQuestion('show me monthly revenue');
  ```
+ 关闭 Q 弹出框 – 此功能将关闭 Q 弹出框并将 iframe 返回到原始 Q 搜索栏大小。

  ```
  qBar.closeQPopover();
  ```

有关更多信息，请参阅 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

# 为匿名（未注册）用户嵌入 Amazon Quick Sight Q 搜索栏
<a name="embedded-analytics-q-search-bar-for-anonymous-users"></a>


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在以下各节中，您可以找到有关如何为匿名（未注册）用户设置嵌入式 Amazon Quick Sight Q 搜索栏的详细信息。

**Topics**
+ [

## 步骤 1：设置权限
](#embedded-q-bar-for-anonymous-users-step-1)
+ [

## 步骤 2：生成附带身份验证代码的 URL
](#embedded-q-bar-for-anonymous-users-step-2)
+ [

## 步骤 3：嵌入 Q 搜索栏 URL
](#embedded-q-bar-for-anonymous-users-step-3)
+ [

## 可选的 Amazon Quick Sight Q 搜索栏嵌入功能
](#embedded-q-bar-for-anonymous-users-step-4)

## 步骤 1：设置权限
<a name="embedded-q-bar-for-anonymous-users-step-1"></a>

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在以下部分中，您可以了解如何设置后端应用程序或 Web 服务器的权限来嵌入 Q 搜索栏。此任务需要对 AWS Identity and Access Management (IAM) 的管理权限。

每个访问 Q 搜索栏的用户都扮演一个角色，该角色授予他们 Amazon Quick Sight 访问权限和访问 Q 搜索栏的权限。要实现这一点，请在您的中创建一个 IAM 角色 AWS 账户。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。IAM 角色需要提供权限才能检索特定用户池 URLs 的嵌入内容。

借助通配符 *\$1*，您可以授予为特定命名空间中的所有用户生成 URL 的权限。您也可以授予为特定命名空间中的一部分用户生成 URL 的权限。为此，请添加 `quicksight:GenerateEmbedUrlForAnonymousUser`。

您可以在 IAM 策略中创建一个条件，限制开发人员可以在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 参数中列出的域。`AllowedDomains` 参数是可选参数。它允许开发者选择覆盖在 “**管理 Amazon Quick Sight**” 菜单中配置的静态域，而是列出最多三个可以访问生成的 URL 的域名或子域名。然后，此 URL 会嵌入开发人员的网站。只有参数中列出的域才能访问嵌入式 Q 搜索栏。如果没有此条件，开发人员可以在 `AllowedDomains` 参数中列出互联网上的任何域。

要限制开发人员可用于此参数的域，请在 IAM 策略中添加一个 `AllowedEmbeddingDomains` 条件。有关该`AllowedDomains`参数的更多信息，请参阅《*Amazon Quick Sight API 参考*》[GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)中的。

**IAM 条件运算符的安全最佳实践**  
配置不当的 IAM 条件运算符可能会允许未经授权地通过 URL 变体访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用`quicksight:AllowedEmbeddingDomains`条件密钥时，请使用条件运算符，允许特定域名或拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息，请参阅 [IAM 用户指南中的 IAM JSON 策略元素：条件运算符](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
许多不同的网址变体可以指向同一个资源。例如，以下 URLs 所有内容都解析为相同的内容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的策略使用不考虑这些 URL 变体的运算符，则攻击者可以通过提供等效的 URL 变体来绕过您的限制。  
您必须验证您的 IAM 策略是否使用了适当的条件运算符来防止绕过漏洞，并确保只有您的目标域才能访问您的嵌入式资源。

您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，在用户访问您的应用程序时，您的应用程序可以代表用户代入该角色，以打开 Q 搜索栏。下面演示了一个示例信任策略。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowLambdaFunctionsToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        {
            "Sid": "AllowEC2InstancesToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

------

有关信任策略的更多信息，请参阅《IAM 用户指南》**中的 [IAM 临时安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)

## 步骤 2：生成附带身份验证代码的 URL
<a name="embedded-q-bar-for-anonymous-users-step-2"></a>

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入 Q 主题 URL。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，如果该用户尚不存在，则该应用程序会将该用户添加到 Amazon Quick Sight。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

有关更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/AnonymousUserQSearchBarEmbeddingConfiguration.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/AnonymousUserQSearchBarEmbeddingConfiguration.html)。

### Java
<a name="embedded-q-bar-for-anonymous-users-java"></a>

```
        import java.util.List;
        import com.amazonaws.auth.AWSCredentials;
        import com.amazonaws.auth.AWSCredentialsProvider;
        import com.amazonaws.auth.BasicAWSCredentials;
        import com.amazonaws.regions.Regions;
        import com.amazonaws.services.quicksight.AmazonQuickSight;
        import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
        import com.amazonaws.services.quicksight.model.AnonymousUserQSearchBarEmbeddingConfiguration;
        import com.amazonaws.services.quicksight.model.AnonymousUserEmbeddingExperienceConfiguration;
        import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserRequest;
        import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserResult;
        import com.amazonaws.services.quicksight.model.SessionTag;


        /**
        * Class to call QuickSight AWS SDK to generate embed url for anonymous user.
        */
        public class GenerateEmbedUrlForAnonymousUserExample {

            private final AmazonQuickSight quickSightClient;

            public GenerateEmbedUrlForAnonymousUserExample() {
                quickSightClient = AmazonQuickSightClientBuilder
                    .standard()
                    .withRegion(Regions.US_EAST_1.getName())
                    .withCredentials(new AWSCredentialsProvider() {
                            @Override
                            public AWSCredentials getCredentials() {
                                // provide actual IAM access key and secret key here
                                return new BasicAWSCredentials("access-key", "secret-key");
                            }

                            @Override
                            public void refresh() {
                            }
                        }
                    )
                    .build();
            }

            public String GenerateEmbedUrlForAnonymousUser(
                final String accountId, // YOUR AWS ACCOUNT ID
                final String initialTopicId, // Q TOPIC ID TO WHICH THE CONSTRUCTED URL POINTS AND SEARCHBAR PREPOPULATES INITIALLY
                final String namespace, // ANONYMOUS EMBEDDING REQUIRES SPECIFYING A VALID NAMESPACE FOR WHICH YOU WANT THE EMBEDDING URL
                final List<String> authorizedResourceArns, // Q SEARCHBAR TOPIC ARN LIST TO EMBED
                final List<String> allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
                final List<SessionTag> sessionTags // SESSION TAGS USED FOR ROW-LEVEL SECURITY
            ) throws Exception {
                AnonymousUserEmbeddingExperienceConfiguration experienceConfiguration = new AnonymousUserEmbeddingExperienceConfiguration();
                AnonymousUserQSearchBarEmbeddingConfiguration qSearchBarConfiguration = new AnonymousUserQSearchBarEmbeddingConfiguration();
                qSearchBarConfiguration.setInitialTopicId(initialTopicId);
                experienceConfiguration.setQSearchBar(qSearchBarConfiguration);

                GenerateEmbedUrlForAnonymousUserRequest generateEmbedUrlForAnonymousUserRequest = new GenerateEmbedUrlForAnonymousUserRequest()
                    .withAwsAccountId(accountId)
                    .withNamespace(namespace)
                    .withAuthorizedResourceArns(authorizedResourceArns)
                    .withExperienceConfiguration(experienceConfiguration)
                    .withSessionTags(sessionTags)
                    .withSessionLifetimeInMinutes(600L); // OPTIONAL: VALUE CAN BE [15-600]. DEFAULT: 600
                    .withAllowedDomains(allowedDomains);

                GenerateEmbedUrlForAnonymousUserResult qSearchBarEmbedUrl = quickSightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserRequest);

                return qSearchBarEmbedUrl.getEmbedUrl();
            }

        }
```

### JavaScript
<a name="embedded-q-bar-for-anonymous-users-js"></a>

```
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function generateEmbedUrlForAnonymousUser(
    accountId, // YOUR AWS ACCOUNT ID
    initialTopicId, // Q TOPIC ID TO WHICH THE CONSTRUCTED URL POINTS
    quicksightNamespace, // VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
    authorizedResourceArns, // Q SEARCHBAR TOPIC ARN LIST TO EMBED
    allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
    sessionTags, // SESSION TAGS USED FOR ROW-LEVEL SECURITY
    generateEmbedUrlForAnonymousUserCallback, // SUCCESS CALLBACK METHOD
    errorCallback // ERROR CALLBACK METHOD
    ) {
    const experienceConfiguration = {
        "QSearchBar": {
            "InitialTopicId": initialTopicId // TOPIC ID CAN BE FOUND IN THE URL ON THE TOPIC AUTHOR PAGE
        }
    };
    
    const generateEmbedUrlForAnonymousUserParams = {
        "AwsAccountId": accountId,
        "Namespace": quicksightNamespace,
        "AuthorizedResourceArns": authorizedResourceArns,
        "AllowedDomains": allowedDomains,
        "ExperienceConfiguration": experienceConfiguration,
        "SessionTags": sessionTags,
        "SessionLifetimeInMinutes": 600
    };

    const quicksightClient = new AWS.QuickSight({
        region: process.env.AWS_REGION,
        credentials: {
            accessKeyId: AccessKeyId,
            secretAccessKey: SecretAccessKey,
            sessionToken: SessionToken,
            expiration: Expiration
        }
    });

    quicksightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserParams, function(err, data) {
        if (err) {
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const result = {
                "statusCode": 200,
                "headers": {
                    "Access-Control-Allow-Origin": "*", // USE YOUR WEBSITE DOMAIN TO SECURE ACCESS TO THIS API
                    "Access-Control-Allow-Headers": "Content-Type"
                },
                "body": JSON.stringify(data),
                "isBase64Encoded": false
            }
            generateEmbedUrlForAnonymousUserCallback(result);
        }
    });
}
```

### Python3
<a name="embedded-q-bar-for-anonymous-users-py"></a>

```
import json
import boto3
from botocore.exceptions import ClientError
import time

# Create QuickSight and STS clients
quicksightClient = boto3.client('quicksight',region_name='us-west-2')
sts = boto3.client('sts')

# Function to generate embedded URL for anonymous user
# accountId: YOUR AWS ACCOUNT ID
# quicksightNamespace: VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
# authorizedResourceArns: TOPIC ARN LIST TO EMBED
# allowedDomains: RUNTIME ALLOWED DOMAINS FOR EMBEDDING
# experienceConfiguration: configuration which specifies the TOPIC ID to point URL to
# sessionTags: SESSION TAGS USED FOR ROW-LEVEL SECURITY
def generateEmbedUrlForAnonymousUser(accountId, quicksightNamespace, authorizedResourceArns, allowedDomains, experienceConfiguration, sessionTags):
    try:
        response = quicksightClient.generate_embed_url_for_anonymous_user(
            AwsAccountId = accountId,
            Namespace = quicksightNamespace,
            AuthorizedResourceArns = authorizedResourceArns,
            AllowedDomains = allowedDomains,
            ExperienceConfiguration = experienceConfiguration,
            SessionTags = sessionTags,
            SessionLifetimeInMinutes = 600
        )
            
        return {
            'statusCode': 200,
            'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
            'body': json.dumps(response),
            'isBase64Encoded':  bool('false')
        }
    except ClientError as e:
        print(e)
        return "Error generating embeddedURL: " + str(e)
```

### Node.js
<a name="embedded-q-bar-for-anonymous-users-nodejs"></a>

以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 URL 的 JavaScript (Node.js)。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
const AWS = require('aws-sdk');
const https = require('https');

var quicksightClient = new AWS.Service({
    apiConfig: require('./quicksight-2018-04-01.min.json'),
    region: 'us-east-1',
});

quicksightClient.generateEmbedUrlForAnonymousUser({
    'AwsAccountId': '111122223333',
    'Namespace': 'DEFAULT'
    'AuthorizedResourceArns': '["topic-arn-topicId1","topic-arn-topicId2"]',
    'AllowedDomains': allowedDomains,
    'ExperienceConfiguration': { 
        'QSearchBar': {
            'InitialTopicId': 'U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f'
        }
    },
    'SessionTags': '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]',
    'SessionLifetimeInMinutes': 15
}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

**Example**  

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
    { 
        Status: 200,
        EmbedUrl : 'https://quicksightdomain/embed/12345/dashboards/67890/sheets/12345/visuals/67890...',
        RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' 
    }
```

### .NET/C\$1
<a name="embedded-q-bar-for-anonymous-users-cs"></a>

以下示例演示了可以在应用程序服务器上使用以生成嵌入式 Q 搜索栏 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用此 URL 以显示 Q 搜索栏。

**Example**  

```
using System;
using Amazon.QuickSight;
using Amazon.QuickSight.Model;

namespace GenerateQSearchBarEmbedUrlForAnonymousUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                AnonymousUserQSearchBarEmbeddingConfiguration anonymousUserQSearchBarEmbeddingConfiguration
                    = new AnonymousUserQSearchBarEmbeddingConfiguration
                    {
                        InitialTopicId = "U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f"
                    };
                AnonymousUserEmbeddingExperienceConfiguration anonymousUserEmbeddingExperienceConfiguration
                    = new AnonymousUserEmbeddingExperienceConfiguration
                    {
                        QSearchBar = anonymousUserQSearchBarEmbeddingConfiguration
                    }; 
                
                Console.WriteLine(
                    quicksightClient.GenerateEmbedUrlForAnonymousUserAsync(new GenerateEmbedUrlForAnonymousUserRequest
                    {
                        AwsAccountId = "111122223333",
                        Namespace = "DEFAULT",
                        AuthorizedResourceArns '["topic-arn-topicId1","topic-arn-topicId2"]',
                        AllowedDomains = allowedDomains,
                        ExperienceConfiguration = anonymousUserEmbeddingExperienceConfiguration,
                        SessionTags = '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]',
                        SessionLifetimeInMinutes = 15,
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
```

### AWS CLI
<a name="embedded-q-bar-for-anonymous-users-cli"></a>

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用 SAML 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GenerateEmbedUrlForAnonymousUser` 启用权限。

```
aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_search_bar_role" \
     --role-session-name anonymous caller
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。对于 Microsoft Windows 计算机，请使用 `set` 而不是 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_q_search_bar_role/QuickSightEmbeddingAnonymousPolicy`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个用户设置相应的权限。此外，它还能避免任何用户访问限制。*限制*是一项安全功能，可防止同一个用户从多个位置访问 Amazon Quick Sight。它还能使每个会话保持独立和独特。如果您使用一组 Web 服务器（例如用于负载平衡），并且会话重新连接到其他服务器，则会开始新的会话。

要获取控制面板的签名 URL，请从应用程序服务器中调用 `generate-embed-url-for-anynymous-user`。这会返回可嵌入的控制面板 URL。以下示例演示了如何使用服务器端调用为匿名访问您 Web 门户或应用程序的用户生成嵌入式控制面板的 URL。

```
aws quicksight generate-embed-url-for-anonymous-user \
--aws-account-id 111122223333 \
--namespace default-or-something-else \
--authorized-resource-arns '["topic-arn-topicId1","topic-arn-topicId2"]' \
--allowed-domains '["domain1","domain2"]' \
--experience-configuration 'QSearchBar={InitialTopicId="topicId1"}' \
--session-tags '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]' \
--session-lifetime-in-minutes 15
```

有关使用此操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在自己的代码中使用该 API 操作和其他操作。

## 步骤 3：嵌入 Q 搜索栏 URL
<a name="embedded-q-bar-for-anonymous-users-step-3"></a>

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在以下部分中，您可以了解如何将步骤 3 中的 Q 搜索栏 URL 嵌入网站或应用程序页面。你可以使用 [Amazon Quick Sight 嵌入式 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 来做到这一点。通过使用该开发工具包，您可以执行以下操作：
+ 将 Q 搜索栏放置到 HTML 页面上。
+ 将参数传递到 Q 搜索栏。
+ 使用为应用程序自定义的消息处理错误状态。

要生成可嵌入应用程序的 URL，请调用 `GenerateEmbedUrlForAnonymousUser` API 操作。该 URL 的有效时间为 5 分钟，生成的会话有效时间为 10 个小时。该 API 操作为 URL 提供 `auth_code` 值以启用单点登录会话。

下面显示了 `generate-embed-url-for-anonymous-user` 的示例响应：

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
{
     "Status": "200",
     "EmbedUrl": "https://quicksightdomain/embedding/12345/q/search...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 [Amazon Quick Sight 嵌入式 SDK 或将此 URL 添加到 iframe 中，将 Q 搜索栏嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会在窗口大小调整时更改视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。

为此，请确保托管嵌入式 Q 搜索栏的域名位于*允许列表中*，即您的 Amazon Quick Sight 订阅的已批准域名列表。这一要求可阻止未经批准的域托管嵌入式 Q 搜索栏，从而保护您的数据。有关为嵌入式 Q 搜索栏添加域名的更多信息，请参阅[管理域和嵌入](https://docs.aws.amazon.com/quicksight/latest/user/manage-qs-domains-and-embedding.html)。

当您使用 Amazon Quick Sight Embedding SDK 时，页面上的 Q 搜索栏会根据状态动态调整大小。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制 Q 搜索栏中的参数，并接收有关页面加载完成和错误的回调。

以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。

### SDK 2.0
<a name="embedded-q-bar-for-anonymous-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Q Search Bar Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedQSearchBar = async() => {    
                const {
                    createEmbeddingContext,
                } = QuickSightEmbedding;

                const embeddingContext = await createEmbeddingContext({
                    onChange: (changeEvent, metadata) => {
                        console.log('Context received a change', changeEvent, metadata);
                    },
                });

                const frameOptions = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: '#experience-container',
                    height: "700px",
                    width: "1000px",
                    onChange: (changeEvent, metadata) => {
                        switch (changeEvent.eventName) {
                            case 'FRAME_MOUNTED': {
                                console.log("Do something when the experience frame is mounted.");
                                break;
                            }
                            case 'FRAME_LOADED': {
                                console.log("Do something when the experience frame is loaded.");
                                break;
                            }
                        }
                    },
                };

                const contentOptions = {
                    hideTopicName: false, 
                    theme: '<YOUR_THEME_ID>',
                    allowTopicSelection: true,
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'Q_SEARCH_OPENED': {
                                console.log("Do something when Q Search content expanded");
                                break;
                            }
                            case 'Q_SEARCH_CLOSED': {
                                console.log("Do something when Q Search content collapsed");
                                break;
                            }
                            case 'Q_SEARCH_SIZE_CHANGED': {
                                console.log("Do something when Q Search size changed");
                                break;
                            }
                            case 'CONTENT_LOADED': {
                                console.log("Do something when the Q Search is loaded.");
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Do something when the Q Search fails loading.");
                                break;
                            }
                        }
                    }
                };
                const embeddedDashboardExperience = await embeddingContext.embedQSearchBar(frameOptions, contentOptions);
            };
        </script>
    </head>

    <body onload="embedQSearchBar()">
        <div id="experience-container"></div>
    </body>

</html>
```

### SDK 1.0
<a name="embedded-q-bar-for-anonymous-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>QuickSight Q Search Bar Embedding</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.18.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            var session

            function onError(payload) {
                console.log("Do something when the session fails loading");
            }

            function onOpen() {
                console.log("Do something when the Q search bar opens");
            }

            function onClose() {
                console.log("Do something when the Q search bar closes");
            }

            function embedQSearchBar() {
                var containerDiv = document.getElementById("embeddingContainer");
                var options = {
                    url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode", // replace this dummy url with the one generated via embedding API
                    container: containerDiv,
                    width: "1000px",
                    locale: "en-US",
                    qSearchBarOptions: {
                        expandCallback: onOpen,
                        collapseCallback: onClose,
                        iconDisabled: false,
                        topicNameDisabled: false, 
                        themeId: 'bdb844d0-0fe9-4d9d-b520-0fe602d93639',
                        allowTopicSelection: true
                    }
                };
                session = QuickSightEmbedding.embedQSearchBar(options);
                session.on("error", onError);
            }

            function onCountryChange(obj) {
                session.setParameters({country: obj.value});
            }
        </script>
    </head>

    <body onload="embedQSearchBar()">
        <div id="embeddingContainer"></div>
    </body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 将嵌入式 Q 搜索栏加载到您的网站上 JavaScript。要获取副本，请执行下列操作之一：
+ 从中下载 [Amazon Quick Sight 嵌入 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) GitHub。该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

## 可选的 Amazon Quick Sight Q 搜索栏嵌入功能
<a name="embedded-q-bar-for-anonymous-users-step-4"></a>

**注意**  
嵌入式的 Amazon Quick Sight Q 搜索栏提供经典的 Amazon Quick Sight 问答体验。Amazon Quick Sight 与 Amazon Q Business 集成，推出全新的生成问答体验。建议开发人员使用全新的生成式问答体验。有关嵌入式生成问答体验的更多信息，请参阅在 [Amazon Quick Sight 生成问答体验中嵌入 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

以下可选功能可用于使用嵌入开发工具包的嵌入式 Q 搜索栏。

### 调用 Q 搜索栏操作
<a name="w2aac35c27c21c43c31c17c21b7"></a>

以下选项仅支持嵌入 Q 搜索栏。
+ 设置 Q 搜索栏问题 – 此功能将问题发送到 Q 搜索栏并立即查询问题。它还可以自动打开 Q 弹出框。

  ```
  qBar.setQBarQuestion('show me monthly revenue');
  ```
+ 关闭 Q 弹出框 – 此功能将关闭 Q 弹出框并将 iframe 返回到原始 Q 搜索栏大小。

  ```
  qBar.closeQPopover();
  ```

有关更多信息，请参阅 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

# 使用 GetDashboardEmbedURL 和 GetSessionEmbedURL API 操作嵌入分析
<a name="embedded-analytics-deprecated"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

以下用于嵌入 Amazon Quick Sight 仪表板和 Amazon Quick Sight 控制台的 API 操作已被GenerateEmbedUrlForAnonymousUser和 GenerateEmbedUrlForRegisteredUser API 操作所取代。您仍然可以使用它们在应用程序中嵌入分析，但它们不再受到维护，且不包含最新的嵌入特性或功能。要了解最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中
+ [GetDashboardEmbedUrl](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetDashboardEmbedUrl.html)API 操作嵌入了交互式仪表板。
+ [GetSessionEmbedUrl](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetSessionEmbedUrl.html)API 操作嵌入了 Amazon Quick Sight 控制台。

**Topics**
+ [

# 使用 GetDashboardEmbedURL（旧 API）为所有人嵌入控制面板
](embedded-analytics-dashboards-with-anonymous-users-get.md)
+ [

# 使用 GetDashboardEmbedUrl（旧 API）为注册用户嵌入控制面板
](embedded-analytics-dashboards-for-authenticated-users-get.md)
+ [

# 使用GetSessionEmbedUrl（旧 API）嵌入 Amazon Quick Sight 控制台
](embedded-analytics-full-console-for-authenticated-users-get.md)

# 使用 GetDashboardEmbedURL（旧 API）为所有人嵌入控制面板
<a name="embedded-analytics-dashboards-with-anonymous-users-get"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在以下各节中，您可以找到有关如何使用 GetDashboardEmbed URL 为所有人（未经身份验证的用户）设置嵌入式 Amazon Quick Sight 控制面板的详细信息。

**Topics**
+ [

# 步骤 1：设置权限
](embedded-analytics-dashboards-with-anonymous-users-get-step-1.md)
+ [

# 步骤 2：获取附带身份验证代码的 URL
](embedded-analytics-dashboards-with-anonymous-users-get-step-2.md)
+ [

# 步骤 3：嵌入控制面板 URL
](embedded-analytics-dashboards-with-anonymous-users-get-step-3.md)

# 步骤 1：设置权限
<a name="embedded-analytics-dashboards-with-anonymous-users-get-step-1"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在下节中，您可以了解如何设置后端应用程序或 Web 服务器的权限。该任务需要具有 IAM 的管理访问权限。

每个访问控制面板的用户都扮演一个角色，授予他们 Amazon Quick Sight 访问控制面板的权限和权限。为此，请在您的 AWS 账户中创建一个 IAM 角色。将一个 IAM policy 与该角色相关联，以便为担任该角色的任何用户提供权限。

以下示例策略提供了可用于 `IdentityType=ANONYMOUS` 的这些权限。要使这种方法发挥作用，您还需要在自己的 AWS 账户中使用会话包或会话容量定价。否则，当用户尝试访问控制面板时，会返回 `UnsupportedPricingPlanException` 错误。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
              "quicksight:GetDashboardEmbedUrl",
              "quickSight:GetAnonymousUserEmbedUrl"
            ],
            "Resource": "*"
        }
    ]
}
```

------

您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，在用户访问您的应用程序时，您的应用程序可以代表用户代入该角色打开控制面板。以下示例显示了一个名为 `QuickSightEmbeddingAnonymousPolicy` 的角色，该角色将前面的示例策略作为其资源。

有关信任策略的更多信息，请参阅《IAM 用户指南》**中的 [IAM 临时安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。

# 步骤 2：获取附带身份验证代码的 URL
<a name="embedded-analytics-dashboards-with-anonymous-users-get-step-2"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在下节中，您可以了解如何代表匿名访问者进行身份验证，并获取应用程序服务器上的可嵌入控制面板 URL。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，它会将该用户添加到 Amazon Quick Sight（如果该用户尚不存在）。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

以下示例展示了代表用户执行 IAM 身份验证。将标识符作为唯一角色会话 ID 进行传递。此代码在您的应用程序服务器上运行。

------
#### [ Java ]

```
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.GetDashboardEmbedUrlRequest;
import com.amazonaws.services.quicksight.model.GetDashboardEmbedUrlResult;

/**
 * Class to call QuickSight AWS SDK to get url for dashboard embedding.
 */
public class GetQuicksightEmbedUrlNoAuth {

    private static String ANONYMOUS = "ANONYMOUS";

    private final AmazonQuickSight quickSightClient;

    public GetQuicksightEmbedUrlNoAuth() {
        this.quickSightClient = AmazonQuickSightClientBuilder
                .standard()
                .withRegion(Regions.US_EAST_1.getName())
                .withCredentials(new AWSCredentialsProvider() {
                                     @Override
                                     public AWSCredentials getCredentials() {
                                         // provide actual IAM access key and secret key here
                                         return new BasicAWSCredentials("access-key", "secret-key");
                                     }

                                     @Override
                                     public void refresh() {}
                                 }
                )
                .build();
    }

    public String getQuicksightEmbedUrl(
            final String accountId, // YOUR AWS ACCOUNT ID
            final String dashboardId, // YOUR DASHBOARD ID TO EMBED
            final String addtionalDashboardIds, // ADDITIONAL DASHBOARD-1 ADDITIONAL DASHBOARD-2
            final boolean resetDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
            final boolean undoRedoDisabled // OPTIONAL PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
    ) throws Exception {
        GetDashboardEmbedUrlRequest getDashboardEmbedUrlRequest = new GetDashboardEmbedUrlRequest()
                .withDashboardId(dashboardId)
                .withAdditionalDashboardIds(addtionalDashboardIds)
                .withAwsAccountId(accountId)
                .withNamespace("default") // Anonymous embedding requires specifying a valid namespace for which you want the embedding url
                .withIdentityType(ANONYMOUS)
                .withResetDisabled(resetDisabled)
                .withUndoRedoDisabled(undoRedoDisabled);

        GetDashboardEmbedUrlResult dashboardEmbedUrl = quickSightClient.getDashboardEmbedUrl(getDashboardEmbedUrlRequest);

        return dashboardEmbedUrl.getEmbedUrl();
    }
}
```

------
#### [ JavaScript ]

```
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function getDashboardEmbedURL(
    accountId, // YOUR AWS ACCOUNT ID
    dashboardId, // YOUR DASHBOARD ID TO EMBED
    additionalDashboardIds, // ADDITIONAL DASHBOARD-1 ADDITIONAL DASHBOARD-2
    quicksightNamespace, // VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
    resetDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
    undoRedoDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
    getEmbedUrlCallback, // GETEMBEDURL SUCCESS CALLBACK METHOD
    errorCallback // GETEMBEDURL ERROR CALLBACK METHOD
    ) {
    const getDashboardParams = {
        AwsAccountId: accountId,
        DashboardId: dashboardId,
        AdditionalDashboardIds: additionalDashboardIds,
        Namespace: quicksightNamespace,
        IdentityType: 'ANONYMOUS',
        ResetDisabled: resetDisabled,
        SessionLifetimeInMinutes: 600,
        UndoRedoDisabled: undoRedoDisabled
    };

    const quicksightGetDashboard = new AWS.QuickSight({
        region: process.env.AWS_REGION,
    });

    quicksightGetDashboard.getDashboardEmbedUrl(getDashboardParams, function(err, data) {
        if (err) {
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const result = {
                "statusCode": 200,
                "headers": {
                    "Access-Control-Allow-Origin": "*", // USE YOUR WEBSITE DOMAIN TO SECURE ACCESS TO GETEMBEDURL API
                    "Access-Control-Allow-Headers": "Content-Type"
                },
                "body": JSON.stringify(data),
                "isBase64Encoded": false
            }
            getEmbedUrlCallback(result);
        }
    });
}
```

------
#### [ Python3 ]

```
import json
import boto3
from botocore.exceptions import ClientError
import time

# Create QuickSight and STS clients
qs = boto3.client('quicksight',region_name='us-east-1')
sts = boto3.client('sts')

# Function to generate embedded URL
# accountId: YOUR AWS ACCOUNT ID
# dashboardId: YOUR DASHBOARD ID TO EMBED
# additionalDashboardIds: ADDITIONAL DASHBOARD-1 ADDITIONAL DASHBOARD-2 WITHOUT COMMAS
# quicksightNamespace: VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
# resetDisabled: PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
# undoRedoDisabled: OPTIONAL PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
def getDashboardURL(accountId, dashboardId, quicksightNamespace, resetDisabled, undoRedoDisabled):
    try:
        response = qs.get_dashboard_embed_url(
            AwsAccountId = accountId,
            DashboardId = dashboardId,
            AdditionalDashboardIds = additionalDashboardIds,
            Namespace = quicksightNamespace,
            IdentityType = 'ANONYMOUS',
            SessionLifetimeInMinutes = 600,
            UndoRedoDisabled = undoRedoDisabled,
            ResetDisabled = resetDisabled
        )
            
        return {
            'statusCode': 200,
            'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
            'body': json.dumps(response),
            'isBase64Encoded':  bool('false')
        }
    except ClientError as e:
        print(e)
        return "Error generating embeddedURL: " + str(e)
```

------
#### [ Node.js ]

以下示例显示了可以在应用服务器上使用的 JavaScript (Node.js) 来获取嵌入式仪表板的 URL。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
const AWS = require('aws-sdk');
            const https = require('https');
            
            var quicksight = new AWS.Service({
                apiConfig: require('./quicksight-2018-04-01.min.json'),
                region: 'us-east-1',
            });
            
            quicksight.getDashboardEmbedUrl({
                'AwsAccountId': '111122223333',
                'DashboardId': 'dashboard-id',
                'AdditionalDashboardIds': 'added-dashboard-id-1 added-dashboard-id-2 added-dashboard-id-3'
                'Namespace' : 'default',
                'IdentityType': 'ANONYMOUS',
                'SessionLifetimeInMinutes': 100,
                'UndoRedoDisabled': false,
                'ResetDisabled': true
            
            }, function(err, data) {
                console.log('Errors: ');
                console.log(err);
                console.log('Response: ');
                console.log(data);
            });
```

**Example**  

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
            //readability and added ellipsis to indicate that it's incomplete.
                                { Status: 200,
              EmbedUrl: 'https://dashboards.example.com/embed/620bef10822743fab329fb3751187d2d…
              RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' }
```

------
#### [ .NET/C\$1 ]

以下示例显示了可以在应用程序服务器上使用以获取嵌入式控制面板 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
            var client = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                sessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                Console.WriteLine(
                    client.GetDashboardEmbedUrlAsync(new GetDashboardEmbedUrlRequest
                    {
                        AwsAccountId = “111122223333”,
                        DashboardId = "dashboard-id",
                        AdditionalDashboardIds = "added-dashboard-id-1 added-dashboard-id-2 added-dashboard-id-3",
                        Namespace = default,
                        IdentityType = IdentityType.ANONYMOUS,
                        SessionLifetimeInMinutes = 600,
                        UndoRedoDisabled = false,
                        ResetDisabled = true
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
```

------
#### [ AWS CLI ]

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用安全断言标记语言 (SAML) 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GetDashboardEmbedURL` 启用权限。

```
aws sts assume-role \
     --role-arn "arn:aws:iam::11112222333:role/QuickSightEmbeddingAnonymousPolicy" \
     --role-session-name anonymous caller
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。如果您使用 Microsoft Windows 计算机，请使用 `set` 而不是 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_dashboard_role/QuickSightEmbeddingAnonymousPolicy`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个访问用户设置相应的权限。其还能让每个会话保持独立性和独特性。如果您使用一组 Web 服务器（例如用于负载平衡），并且会话重新连接到其他服务器，则会开始新的会话。

要获取控制面板的签名 URL，请从应用程序服务器中调用 `get-dashboard-embed-url`。这会返回可嵌入的控制面板 URL。以下示例演示了如何使用服务器端调用为匿名访问您 Web 门户或应用程序的用户获取嵌入式控制面板的 URL。

```
aws quicksight get-dashboard-embed-url \
     --aws-account-id 111122223333 \
     --dashboard-id dashboard-id \
     --additional-dashboard-ids added-dashboard-id-1 added-dashboard-id-2 added-dashboard-id-3
     --namespace default-or-something-else \
     --identity-type ANONYMOUS \
     --session-lifetime-in-minutes 30 \
     --undo-redo-disabled true \
     --reset-disabled true \
     --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/QuickSightEmbeddingAnonymousPolicy/embeddingsession
```

有关使用该操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetDashboardEmbedUrl.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetDashboardEmbedUrl.html)。您可以在自己的代码中使用该 API 操作和其他操作。

------

# 步骤 3：嵌入控制面板 URL
<a name="embedded-analytics-dashboards-with-anonymous-users-get-step-3"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在下一节中，您可以了解如何使用 [Amazon Quick Sight 嵌入软件开发工具包](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 将第 2 步中的控制面板网址嵌入到您的网站或应用程序页面中。通过使用该开发工具包，您可以执行以下操作：
+ 将控制面板放在 HTML 页面上。
+ 将参数传递到控制面板。
+ 使用为应用程序自定义的消息处理错误状态。

调用 `GetDashboardEmbedUrl` API 操作获取可嵌入应用程序的 URL。该 URL 的有效期为 5 分钟，生成的会话的有效期为 10 个小时。该 API 操作为 URL 提供 `auth_code` 以启用单点登录会话。

下面显示了 `get-dashboard-embed-url` 的示例响应：

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
{
     "Status": "200",
     "EmbedUrl": "https: //dashboards.example.com/embed/620bef10822743fab329fb3751187d2d...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 Amazon Quick Sight Embedding [SDK 或将此 URL 添加到 iframe 中，将此控制面板嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会在窗口大小调整时更改视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制控制面板中的参数并接收有关页面加载完成和错误的回调。

以下示例演示了如何使用生成的 URL。此代码位于您的应用程序服务器上。

```
<!DOCTYPE html>
<html>

<head>
    <title>Basic Embed</title>
    <!-- You can download the latest QuickSight embedding SDK version from https://www.npmjs.com/package/amazon-quicksight-embedding-sdk -->
    <!-- Or you can do "npm install amazon-quicksight-embedding-sdk", if you use npm for javascript dependencies -->
    <script src="./quicksight-embedding-js-sdk.min.js"></script>
    <script type="text/javascript">
        var dashboard;

        function embedDashboard() {
            var containerDiv = document.getElementById("embeddingContainer");
            var options = {
                // replace this dummy url with the one generated via embedding API
                url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",  
                container: containerDiv,
                scrolling: "no",
                height: "700px",
                width: "1000px",
                footerPaddingEnabled: true
            };
            dashboard = QuickSightEmbedding.embedDashboard(options);
        }
    </script>
</head>

<body onload="embedDashboard()">
    <div id="embeddingContainer"></div>
</body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 将嵌入式控制面板加载到您的网站上 JavaScript。要获取副本，请执行下列操作之一：
+ 从中下载 [Amazon Quick Sight 嵌入 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) GitHub。该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的 QuickSight 嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

# 使用 GetDashboardEmbedUrl（旧 API）为注册用户嵌入控制面板
<a name="embedded-analytics-dashboards-for-authenticated-users-get"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。

在以下各节中，您可以找到有关如何使用为注册用户设置嵌入式 Amazon Quick Sight 控制面板的详细信息`GetDashboardEmbedUrl`。

**Topics**
+ [

# 步骤 1：设置权限
](embedded-dashboards-for-authenticated-users-get-step-1.md)
+ [

# 步骤 2：获取附带身份验证代码的 URL
](embedded-dashboards-for-authenticated-users-get-step-2.md)
+ [

# 步骤 3：嵌入控制面板 URL
](embedded-dashboards-for-authenticated-users-get-step-3.md)

# 步骤 1：设置权限
<a name="embedded-dashboards-for-authenticated-users-get-step-1"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。

在下节中，您可以了解如何设置后端应用程序或 Web 服务器的权限。该任务需要具有 IAM 的管理访问权限。

每个访问控制面板的用户都扮演一个角色，授予他们 Amazon Quick Sight 访问控制面板的权限和权限。为此，请在您的 AWS 账户中创建一个 IAM 角色。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。IAM 角色需要提供检索控制面板的权限 URLs。为此，请添加 `quicksight:GetDashboardEmbedUrl`。

以下示例策略提供了可用于 `IdentityType=IAM` 的这些权限。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "quicksight:GetDashboardEmbedUrl"
            ],
            "Resource": "*"
        }
    ]
}
```

------

以下示例策略提供了检索控制面板 URL 的权限。`quicksight:RegisterUser`如果您要创建的首次用户将成为 Amazon Quick Sight 读者，则可以使用该政策。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Action": "quicksight:RegisterUser",
      "Resource": "*",
      "Effect": "Allow"
    },
    {
      "Action": "quicksight:GetDashboardEmbedUrl",
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}
```

------

如果您使用 `QUICKSIGHT` 作为您的 `identityType`，并提供用户的 Amazon 资源名称（ARN），则还需要在策略中允许 `quicksight:GetAuthCode` 操作。以下示例策略提供了此权限。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "quicksight:GetDashboardEmbedUrl",
        "quicksight:GetAuthCode"
      ],
      "Resource": "*"
    }
  ]
}
```

------

您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，当用户访问您的应用程序时，您的应用程序可以代表用户担任该角色并在 Amazon Quick Sight 中配置用户。以下示例显示了一个名为 `embedding_quicksight_dashboard_role` 的角色，该角色将前面的示例策略作为其资源。

有关 OpenId Connect 或 SAML 身份验证的信任策略的更多信息，请参阅 *IAM 用户指南* 的以下部分：
+ [创建用于 Web 联合身份验证或 OpenID Connect 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [创建用于 SAML 2.0 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

# 步骤 2：获取附带身份验证代码的 URL
<a name="embedded-dashboards-for-authenticated-users-get-step-2"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。

在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入控制面板 URL。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，它会将该用户添加到 Amazon Quick Sight 中（如果该用户尚不存在）。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

执行上述步骤可确保在 Amazon Quick Sight 中对控制面板的每个查看者进行唯一配置。它还实施每个用户的设置，例如，行级别安全性和参数的动态默认值。

以下示例展示了代表用户执行 IAM 身份验证。此代码在您的应用程序服务器上运行。

------
#### [ Java ]

```
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicSessionCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.GetDashboardEmbedUrlRequest;
import com.amazonaws.services.quicksight.model.GetDashboardEmbedUrlResult;
import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
import com.amazonaws.services.securitytoken.model.AssumeRoleRequest;
import com.amazonaws.services.securitytoken.model.AssumeRoleResult;

/**
 * Class to call QuickSight AWS SDK to get url for dashboard embedding.
 */
public class GetQuicksightEmbedUrlIAMAuth {

    private static String IAM = "IAM";

    private final AmazonQuickSight quickSightClient;

    private final AWSSecurityTokenService awsSecurityTokenService;

    public GetQuicksightEmbedUrlIAMAuth(final AWSSecurityTokenService awsSecurityTokenService) {
        this.quickSightClient = AmazonQuickSightClientBuilder
                .standard()
                .withRegion(Regions.US_EAST_1.getName())
                .withCredentials(new AWSCredentialsProvider() {
                                     @Override
                                     public AWSCredentials getCredentials() {
                                         // provide actual IAM access key and secret key here
                                         return new BasicAWSCredentials("access-key", "secret-key");
                                     }

                                     @Override
                                     public void refresh() {}
                                 }
                )
                .build();
        this.awsSecurityTokenService = awsSecurityTokenService;
    }

    public String getQuicksightEmbedUrl(
            final String accountId, // YOUR AWS ACCOUNT ID
            final String dashboardId, // YOUR DASHBOARD ID TO EMBED
            final String openIdToken, // TOKEN TO ASSUME ROLE WITH ROLEARN
            final String roleArn, // IAM USER ROLE TO USE FOR EMBEDDING
            final String sessionName, // SESSION NAME FOR THE ROLEARN ASSUME ROLE
            final boolean resetDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
            final boolean undoRedoDisabled // OPTIONAL PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
    ) throws Exception {
        AssumeRoleRequest request = new AssumeRoleRequest()
                .withRoleArn(roleArn)
                .withRoleSessionName(sessionName)
                .withTokenCode(openIdToken)
                .withDurationSeconds(3600);
        AssumeRoleResult assumeRoleResult = awsSecurityTokenService.assumeRole(request);

        AWSCredentials temporaryCredentials = new BasicSessionCredentials(
                assumeRoleResult.getCredentials().getAccessKeyId(),
                assumeRoleResult.getCredentials().getSecretAccessKey(),
                assumeRoleResult.getCredentials().getSessionToken());
        AWSStaticCredentialsProvider awsStaticCredentialsProvider = new AWSStaticCredentialsProvider(temporaryCredentials);

        GetDashboardEmbedUrlRequest getDashboardEmbedUrlRequest = new GetDashboardEmbedUrlRequest()
                .withDashboardId(dashboardId)
                .withAwsAccountId(accountId)
                .withIdentityType(IAM)
                .withResetDisabled(resetDisabled)
                .withUndoRedoDisabled(undoRedoDisabled)
                .withRequestCredentialsProvider(awsStaticCredentialsProvider);

        GetDashboardEmbedUrlResult dashboardEmbedUrl = quickSightClient.getDashboardEmbedUrl(getDashboardEmbedUrlRequest);

        return dashboardEmbedUrl.getEmbedUrl();
    }
}
```

------
#### [ JavaScript ]

```
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function getDashboardEmbedURL(
    accountId, // YOUR AWS ACCOUNT ID
    dashboardId, // YOUR DASHBOARD ID TO EMBED
    openIdToken, // TOKEN TO ASSUME ROLE WITH ROLEARN
    roleArn, // IAM USER ROLE TO USE FOR EMBEDDING
    sessionName, // SESSION NAME FOR THE ROLEARN ASSUME ROLE
    resetDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
    undoRedoDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
    getEmbedUrlCallback, // GETEMBEDURL SUCCESS CALLBACK METHOD
    errorCallback // GETEMBEDURL ERROR CALLBACK METHOD
    ) {
    const stsClient = new AWS.STS();
    let stsParams = {
        RoleSessionName: sessionName,
        WebIdentityToken: openIdToken,
        RoleArn: roleArn
    }

    stsClient.assumeRoleWithWebIdentity(stsParams, function(err, data) {
        if (err) {
            console.log('Error assuming role');
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const getDashboardParams = {
                AwsAccountId: accountId,
                DashboardId: dashboardId,
                IdentityType: 'IAM',
                ResetDisabled: resetDisabled,
                SessionLifetimeInMinutes: 600,
                UndoRedoDisabled: undoRedoDisabled
            };

            const quicksightGetDashboard = new AWS.QuickSight({
                region: process.env.AWS_REGION,
                credentials: {
                    accessKeyId: data.Credentials.AccessKeyId,
                    secretAccessKey: data.Credentials.SecretAccessKey,
                    sessionToken: data.Credentials.SessionToken,
                    expiration: data.Credentials.Expiration
                }
            });

            quicksightGetDashboard.getDashboardEmbedUrl(getDashboardParams, function(err, data) {
                if (err) {
                    console.log(err, err.stack);
                    errorCallback(err);
                } else {
                    const result = {
                        "statusCode": 200,
                        "headers": {
                            "Access-Control-Allow-Origin": "*", // USE YOUR WEBSITE DOMAIN TO SECURE ACCESS TO GETEMBEDURL API
                            "Access-Control-Allow-Headers": "Content-Type"
                        },
                        "body": JSON.stringify(data),
                        "isBase64Encoded": false
                    }
                    getEmbedUrlCallback(result);
                }
            });
        }
    });
}
```

------
#### [ Python3 ]

```
import json
import boto3
from botocore.exceptions import ClientError

# Create QuickSight and STS clients
qs = boto3.client('quicksight',region_name='us-east-1')
sts = boto3.client('sts')

# Function to generate embedded URL  
# accountId: YOUR AWS ACCOUNT ID
# dashboardId: YOUR DASHBOARD ID TO EMBED
# openIdToken: TOKEN TO ASSUME ROLE WITH ROLEARN
# roleArn: IAM USER ROLE TO USE FOR EMBEDDING
# sessionName: SESSION NAME FOR THE ROLEARN ASSUME ROLE
# resetDisabled: PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
# undoRedoDisabled: PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
def getDashboardURL(accountId, dashboardId, openIdToken, roleArn, sessionName, resetDisabled, undoRedoDisabled):
    try:
        assumedRole = sts.assume_role(
            RoleArn = roleArn,
            RoleSessionName = sessionName,
            WebIdentityToken = openIdToken
        )
    except ClientError as e:
        return "Error assuming role: " + str(e)
    else: 
        assumedRoleSession = boto3.Session(
            aws_access_key_id = assumedRole['Credentials']['AccessKeyId'],
            aws_secret_access_key = assumedRole['Credentials']['SecretAccessKey'],
            aws_session_token = assumedRole['Credentials']['SessionToken'],
        )
        try:
            quickSight = assumedRoleSession.client('quicksight',region_name='us-east-1')
            
            response = quickSight.get_dashboard_embed_url(
                 AwsAccountId = accountId,
                 DashboardId = dashboardId,
                 IdentityType = 'IAM',
                 SessionLifetimeInMinutes = 600,
                 UndoRedoDisabled = undoRedoDisabled,
                 ResetDisabled = resetDisabled
            )
            
            return {
                'statusCode': 200,
                'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
                'body': json.dumps(response),
                'isBase64Encoded':  bool('false')
            }
        except ClientError as e:
            return "Error generating embeddedURL: " + str(e)
```

------
#### [ Node.js ]

以下示例显示了可以在应用服务器上使用的 JavaScript (Node.js) 来获取嵌入式仪表板的 URL。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
const AWS = require('aws-sdk');
            const https = require('https');
            
            var quicksight = new AWS.Service({
                apiConfig: require('./quicksight-2018-04-01.min.json'),
                region: 'us-east-1',
            });
            
            quicksight.getDashboardEmbedUrl({
                'AwsAccountId': '111122223333',
                'DashboardId': '1c1fe111-e2d2-3b30-44ef-a0e111111cde',
                'IdentityType': 'IAM',
                'ResetDisabled': true,
                'SessionLifetimeInMinutes': 100,
                'UndoRedoDisabled': false,
                'StatePersistenceEnabled': true
            
            }, function(err, data) {
                console.log('Errors: ');
                console.log(err);
                console.log('Response: ');
                console.log(data);
            });
```

**Example**  

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
            //readability and added ellipsis to indicate that it's incomplete.
                                { Status: 200,
              EmbedUrl: 'https://dashboards.example.com/embed/620bef10822743fab329fb3751187d2d…
              RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' }
```

------
#### [ .NET/C\$1 ]

以下示例显示了可以在应用程序服务器上使用以获取嵌入式控制面板 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用该 URL 以显示控制面板。

**Example**  

```
            var client = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                sessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                Console.WriteLine(
                    client.GetDashboardEmbedUrlAsync(new GetDashboardEmbedUrlRequest
                    {
                        AwsAccountId = “111122223333”,
                        DashboardId = "1c1fe111-e2d2-3b30-44ef-a0e111111cde",
                        IdentityType = EmbeddingIdentityType.IAM,
                        ResetDisabled = true,
                        SessionLifetimeInMinutes = 100,
                        UndoRedoDisabled = false,
                        StatePersistenceEnabled = true
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
```

------
#### [ AWS CLI ]

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用 SAML 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GetDashboardEmbedURL` 启用权限。如果您采用一种在用户首次打开仪表板时添加用户的 just-in-time方法，则该角色还需要为其启用权限`quicksight:RegisterUser`。

```
aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
     --role-session-name john.doe@example.com
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。如果您使用 Microsoft Windows 计算机，请使用 `set` 而不是 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_dashboard_role/john.doe@example.com`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个用户设置相应的权限。此外，它还能避免任何用户访问限制。*限制*是一项安全功能，可防止同一个用户从多个位置访问 Amazon Quick Sight。

角色会话 ID 也将成为 Amazon Quick Sight 中的用户名。您可以使用此模式提前在 Amazon Quick Sight 中配置用户，或者在他们首次访问控制面板时对其进行配置。

以下示例显示了可用于预置用户的 CLI 命令。有关[RegisterUser[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html)](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、和其他 Amazon Quick Sight API 操作的更多信息，请参阅 [Amazon Quick Sight API 参考](https://docs.aws.amazon.com/quicksight/latest/APIReference/Welcome.html)。

```
aws quicksight register-user \
     --aws-account-id 111122223333 \
     --namespace default \
     --identity-type IAM \
     --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
     --user-role READER \
     --user-name jhnd \
     --session-name "john.doe@example.com" \
     --email john.doe@example.com \
     --region us-east-1 \
     --custom-permissions-name TeamA1
```

如果用户通过 Microsoft AD 进行身份验证，则无需使用 `RegisterUser` 进行设置。相反，他们应该在首次访问 Amazon Quick Sight 时自动订阅。对于 Microsoft AD 用户，您可以使用 `DescribeUser` 获取用户 ARN。

用户首次访问 Amazon Quick Sight 时，您也可以将该用户添加到与之共享控制面板的群组中。以下示例显示了将用户添加到组的 CLI 命令。

```
aws quicksight create-group-membership \
     --aws-account-id=111122223333 \
     --namespace=default \
     --group-name=financeusers \
     --member-name="embedding_quicksight_dashboard_role/john.doe@example.com"
```

现在，您的应用程序的用户也是 Amazon Quick Sight 的用户，并且可以访问控制面板。

最后，要获取控制面板的签名 URL，请从应用程序服务器中调用 `get-dashboard-embed-url`。这会返回可嵌入的控制面板 URL。以下示例说明如何通过 AWS Managed Microsoft AD 或 IAM Identity Center 进行身份验证的用户通过服务器端调用获取嵌入式控制面板的 URL。

```
aws quicksight get-dashboard-embed-url \
     --aws-account-id 111122223333 \
     --dashboard-id 1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89 \
     --identity-type IAM \
     --session-lifetime-in-minutes 30 \
     --undo-redo-disabled true \
     --reset-disabled true \
     --state-persistence-enabled true \
     --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_dashboard_role/embeddingsession
```

有关使用该操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetDashboardEmbedUrl.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetDashboardEmbedUrl.html)。您可以在自己的代码中使用该 API 操作和其他操作。

------

# 步骤 3：嵌入控制面板 URL
<a name="embedded-dashboards-for-authenticated-users-get-step-3"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。

在下一节中，您可以了解如何使用 [Amazon Quick Sight 嵌入软件开发工具包](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 将第 3 步中的控制面板网址嵌入到您的网站或应用程序页面中。通过使用该开发工具包，您可以执行以下操作：
+ 将控制面板放在 HTML 页面上。
+ 将参数传递到控制面板。
+ 使用为应用程序自定义的消息处理错误状态。

调用 `GetDashboardEmbedUrl` API 操作获取可嵌入应用程序的 URL。该 URL 的有效期为 5 分钟，生成的会话的有效期为 10 个小时。该 API 操作为 URL 提供 `auth_code` 以启用单点登录会话。

下面显示了 `get-dashboard-embed-url` 的示例响应：

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
{
     "Status": "200",
     "EmbedUrl": "https: //dashboards.example.com/embed/620bef10822743fab329fb3751187d2d...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 [Amazon Quick Sight 嵌入软件开发工具包](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)或将此 URL 添加到 iframe 中，将此控制面板嵌入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会随着窗口大小调整而改变视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制控制面板中的参数并接收有关页面加载完成和错误的回调。

以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。

```
<!DOCTYPE html>
<html>

<head>
    <title>Basic Embed</title>

    <script src="./quicksight-embedding-js-sdk.min.js"></script>
    <script type="text/javascript">
        var dashboard;

        function embedDashboard() {
            var containerDiv = document.getElementById("embeddingContainer");
            var options = {
                // replace this dummy url with the one generated via embedding API
                url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",  
                container: containerDiv,
                scrolling: "no",
                height: "700px",
                width: "1000px",
                footerPaddingEnabled: true
            };
            dashboard = QuickSightEmbedding.embedDashboard(options);
        }
    </script>
</head>

<body onload="embedDashboard()">
    <div id="embeddingContainer"></div>
</body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 将嵌入式控制面板加载到您的网站上 JavaScript。要获取副本，请执行下列操作之一：
+ 从中下载 [Amazon Quick Sight 嵌入 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) GitHub。该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

# 使用GetSessionEmbedUrl（旧 API）嵌入 Amazon Quick Sight 控制台
<a name="embedded-analytics-full-console-for-authenticated-users-get"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 开发者  | 

在以下各节中，您可以找到有关如何在自定义品牌创作门户中为使用 API 的注册用户提供 Amazon Quick Sight 控制台体验的`GetSessionEmbedUrl`详细信息。

**Topics**
+ [

# 步骤 1：设置权限
](embedded-analytics-full-console-for-authenticated-users-get-step-1.md)
+ [

# 步骤 2：获取附带身份验证代码的 URL
](embedded-analytics-full-console-for-authenticated-users-get-step-2.md)
+ [

# 步骤 3：嵌入控制台会话 URL
](embedded-analytics-full-console-for-authenticated-users-get-step-3.md)

# 步骤 1：设置权限
<a name="embedded-analytics-full-console-for-authenticated-users-get-step-1"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。

在下节中，您可以了解如何设置后端应用程序或 Web 服务器的权限。该任务需要具有 IAM 的管理访问权限。

每个访问 Amazon Quick Sight 的用户都扮演一个角色，该角色授予他们 Amazon Quick Sight 访问权限和控制台会话权限。为此，请在您的 AWS 账户中创建一个 IAM 角色。将一个 IAM 策略与该角色相关联，以便为担任该角色的任何用户提供权限。添加`quicksight:RegisterUser`权限以确保读者能够以只读方式访问 Amazon Quick Sight，并且无法访问任何其他数据或创建功能。IAM 角色还需要提供检索控制台会话的权限 URLs。为此，请添加 `quicksight:GetSessionEmbedUrl`。

以下示例策略提供了可用于 `IdentityType=IAM` 的这些权限。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Action": "quicksight:RegisterUser",
      "Resource": "*",
      "Effect": "Allow"
    },
    {
      "Action": "quicksight:GetSessionEmbedUrl",
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}
```

------

以下示例策略提供了检索控制台会话 URL 的权限。如果您在用户访问嵌入式会话之前创建用户，则可以使用不具有 `quicksight:RegisterUser` 的策略。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "quicksight:GetSessionEmbedUrl"
            ],
            "Resource": "*"
        }
    ]
}
```

------

如果您使用 `QUICKSIGHT` 作为您的 `identityType`，并提供用户的 Amazon 资源名称（ARN），则还需要在策略中允许 `quicksight:GetAuthCode` 操作。以下示例策略提供了此权限。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "quicksight:GetSessionEmbedUrl",
        "quicksight:GetAuthCode"
      ],
      "Resource": "*"
    }
  ]
}
```

------

您应用程序的 IAM 身份必须具有关联的信任策略，才允许访问您刚创建的角色。这意味着，当用户访问您的应用程序时，您的应用程序可以代表用户担任该角色并在 Amazon Quick Sight 中配置用户。以下示例显示了一个名为 `embedding_quicksight_console_session_role` 的角色，该角色将前面的示例策略作为其资源。

有关 OpenId Connect 或 SAML 身份验证的信任策略的更多信息，请参阅 *IAM 用户指南* 的以下部分：
+ [创建用于 Web 联合身份验证或 OpenID Connect 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [创建用于 SAML 2.0 联合身份验证的角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

# 步骤 2：获取附带身份验证代码的 URL
<a name="embedded-analytics-full-console-for-authenticated-users-get-step-2"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。

在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入控制台会话 URL。

用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，它会将该用户添加到 Amazon Quick Sight（如果该用户尚不存在）。接下来，其会将标识符作为唯一角色会话 ID 进行传递。

执行上述步骤可确保在 Amazon Quick Sight 中对控制台会话的每个查看者进行唯一的配置。它还实施每个用户的设置，例如，行级别安全性和参数的动态默认值。

以下示例展示了代表用户执行 IAM 身份验证。此代码在您的应用程序服务器上运行。

------
#### [ Java ]

```
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.GetSessionEmbedUrlRequest;
import com.amazonaws.services.quicksight.model.GetSessionEmbedUrlResult;

/**
 * Class to call QuickSight AWS SDK to get url for session embedding.
 */
public class GetSessionEmbedUrlQSAuth {

    private final AmazonQuickSight quickSightClient;

    public GetSessionEmbedUrlQSAuth() {
        this.quickSightClient = AmazonQuickSightClientBuilder
                .standard()
                .withRegion(Regions.US_EAST_1.getName())
                .withCredentials(new AWSCredentialsProvider() {
                                     @Override
                                     public AWSCredentials getCredentials() {
                                         // provide actual IAM access key and secret key here
                                         return new BasicAWSCredentials("access-key", "secret-key");
                                     }

                                     @Override
                                     public void refresh() {}
                                 }
                )
                .build();
    }

    public String getQuicksightEmbedUrl(
            final String accountId, // YOUR AWS ACCOUNT ID
            final String userArn // REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
    ) throws Exception {
        GetSessionEmbedUrlRequest getSessionEmbedUrlRequest = new GetSessionEmbedUrlRequest()
                .withAwsAccountId(accountId)
                .withEntryPoint("/start")
                .withUserArn(userArn);

        GetSessionEmbedUrlResult sessionEmbedUrl = quickSightClient.getSessionEmbedUrl(getSessionEmbedUrlRequest);

        return sessionEmbedUrl.getEmbedUrl();
    }
}
```

------
#### [ JavaScript ]

```
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function getSessionEmbedURL(
    accountId, // YOUR AWS ACCOUNT ID
    userArn, // REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
    getEmbedUrlCallback, // GETEMBEDURL SUCCESS CALLBACK METHOD
    errorCallback // GETEMBEDURL ERROR CALLBACK METHOD
    ) {
    const getSessionParams = {
        AwsAccountId: accountId,
        EntryPoint: "/start",
        UserArn: userArn,
        SessionLifetimeInMinutes: 600,
    };

    const quicksightGetSession = new AWS.QuickSight({
        region: process.env.AWS_REGION,
    });

    quicksightGetSession.getSessionEmbedUrl(getSessionParams, function(err, data) {
        if (err) {
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const result = {
                "statusCode": 200,
                "headers": {
                    "Access-Control-Allow-Origin": "*", // USE YOUR WEBSITE DOMAIN TO SECURE ACCESS TO GETEMBEDURL API
                    "Access-Control-Allow-Headers": "Content-Type"
                },
                "body": JSON.stringify(data),
                "isBase64Encoded": false
            }
            getEmbedUrlCallback(result);
        }
    });
}
```

------
#### [ Python3 ]

```
import json
import boto3
from botocore.exceptions import ClientError
import time

# Create QuickSight and STS clients
qs = boto3.client('quicksight',region_name='us-east-1')
sts = boto3.client('sts')

# Function to generate embedded URL
# accountId: YOUR AWS ACCOUNT ID
# userArn: REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
def getSessionEmbedURL(accountId, userArn):
    try:
        response = qs.get_session_embed_url(
            AwsAccountId = accountId,
            EntryPoint = "/start",
            UserArn = userArn,
            SessionLifetimeInMinutes = 600
        )
            
        return {
            'statusCode': 200,
            'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
            'body': json.dumps(response),
            'isBase64Encoded':  bool('false')
        }
    except ClientError as e:
        print(e)
        return "Error generating embeddedURL: " + str(e)
```

------
#### [ Node.js ]

以下示例显示了可以在应用服务器上使用的 JavaScript (Node.js) 来获取嵌入式控制台会话的 URL。您可以在网站或应用程序中使用该 URL 来显示控制台会话。

**Example**  

```
const AWS = require('aws-sdk');
            const https = require('https');
            
            var quicksight = new AWS.Service({
                apiConfig: require('./quicksight-2018-04-01.min.json'),
                region: 'us-east-1',
            });
            
            quicksight.GetSessionEmbedUrl({
                'AwsAccountId': '111122223333',
                'EntryPoint': 'https://url-for-console-page-to-open',
                'SessionLifetimeInMinutes': 600,
                'UserArn': 'USER_ARN'
            
            }, function(err, data) {
                console.log('Errors: ');
                console.log(err);
                console.log('Response: ');
                console.log(data);
            });
```

**Example**  

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
            //readability and added ellipsis to indicate that it's incomplete.
                                { Status: 200,
              EmbedUrl: 'https://dashboards.example.com/embed/620bef10822743fab329fb3751187d2d…
              RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' }
```

------
#### [ .NET/C\$1 ]

以下示例演示了可以在应用程序服务器上使用以获取嵌入式控制台会话 URL 的 .NET/C\$1 代码。您可以在网站或应用程序中使用该 URL 来显示控制台。

**Example**  

```
            var client = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                sessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                Console.WriteLine(
                    client.GetSessionEmbedUrlAsync(new GetSessionEmbedUrlRequest
                    {
                'AwsAccountId': '111122223333',
                'EntryPoint': 'https://url-for-console-page-to-open',
                'SessionLifetimeInMinutes': 600,
                'UserArn': 'USER_ARN'
                        AwsAccountId = 111122223333,
                        EntryPoint = https://url-for-console-page-to-open,
                        SessionLifetimeInMinutes = 600,
                        UserArn = 'USER_ARN'
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
```

------
#### [ AWS CLI ]

要代入该角色，请选择以下 AWS Security Token Service (AWS STS) API 操作之一：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— 当您使用 IAM 身份代入角色时，请使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— 当您使用 Web 身份提供商对用户进行身份验证时，请使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— 当您使用 SAML 对用户进行身份验证时，请使用此操作。

以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 `quicksight:GetSessionEmbedUrl` 启用权限。如果您在用户首次打开 Amazon Quick Sight 时采用添加他们的 just-in-time方法，则还需要为该角色启用权限`quicksight:RegisterUser`。

```
aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
     --role-session-name john.doe@example.com
```

`assume-role` 操作返回三个输出参数：访问密钥、私有密钥和会话令牌。

**注意**  
如果在调用 `AssumeRole` 操作时遇到 `ExpiredToken` 错误，可能是因为之前的 `SESSION TOKEN` 仍在环境变量中。通过设置以下变量可以解决这一问题：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1访问密钥* 
*AWS\$1SESSION\$1代币* 

以下示例说明了如何在 CLI 中设置这三个参数。如果您使用 Microsoft Windows 计算机，请使用 `set` 而不是 `export`。

```
export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"
```

如果运行这些命令，则会将访问您的网站的用户的角色会话 ID 设置为 `embedding_quicksight_console_session_role/john.doe@example.com`。角色会话 ID 由 `role-arn` 中的角色名称和 `role-session-name` 值组成。每个用户使用唯一的角色会话 ID 可以确保为每个用户设置相应的权限。此外，它还能避免任何用户访问限制。限制是一项安全功能，可防止同一个用户从多个位置访问 Amazon Quick Sight。

角色会话 ID 也将成为 Amazon Quick Sight 中的用户名。您可以使用此模式提前在 Amazon Quick Sight 中配置用户，或者在他们首次访问控制台会话时对其进行配置。

以下示例显示了可用于预置用户的 CLI 命令。有关[RegisterUser[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html)](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、和其他 Amazon Quick Sight API 操作的更多信息，请参阅 [Amazon Quick Sight API 参考](https://docs.aws.amazon.com/quicksight/latest/APIReference/Welcome.html)。

```
aws quicksight register-user \
     --aws-account-id 111122223333 \
     --namespace default \
     --identity-type IAM \
     --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
     --user-role READER \
     --user-name jhnd \
     --session-name "john.doe@example.com" \
     --email john.doe@example.com \
     --region us-east-1 \
     --custom-permissions-name TeamA1
```

如果用户通过 Microsoft AD 进行身份验证，则无需使用 `RegisterUser` 进行设置。相反，他们应该在首次访问 Amazon Quick Sight 时自动订阅。对于 Microsoft AD 用户，您可以使用 `DescribeUser` 获取用户 ARN。

当用户首次访问 Amazon Quick Sight 时，您也可以将该用户添加到相应的群组中。以下示例显示了将用户添加到组的 CLI 命令。

```
aws quicksight create-group-membership \
     --aws-account-id=111122223333 \
     --namespace=default \
     --group-name=financeusers \
     --member-name="embedding_quicksight_dashboard_role/john.doe@example.com"
```

现在，您的应用程序的用户也是 Amazon Quick Sight 的用户，并且可以访问 Amazon Quick Sight 控制台会话。

最后，要获取控制台会话的签名 URL，请从应用程序服务器中调用 `get-session-embed-url`。此操作会返回可嵌入控制台会话 URL。以下示例说明如何通过服务器端调用 AWS Managed Microsoft AD 或单点登录（IAM Identity Center）进行身份验证的用户获取嵌入式控制台会话的网址。

```
aws quicksight get-dashboard-embed-url \
     --aws-account-id 111122223333 \
     --entry-point the-url-for--the-console-session \
     --session-lifetime-in-minutes 600 \
     --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_dashboard_role/embeddingsession
```

有关使用该操作的更多信息，请参阅 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetSessionEmbedUrl.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetSessionEmbedUrl.html)。您可以在自己的代码中使用该 API 操作和其他操作。

------

# 步骤 3：嵌入控制台会话 URL
<a name="embedded-analytics-full-console-for-authenticated-users-get-step-3"></a>

**重要**  
Amazon Quick Sight 推出了嵌入分析的新 APIs 功能：`GenerateEmbedUrlForAnonymousUser`和`GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用`GetDashboardEmbedUrl`和`GetSessionEmbedUrl` APIs 来嵌入仪表板和 Amazon Quick Sight 控制台，但它们不包含最新的嵌入功能。有关最新的 up-to-date嵌入体验，请参阅将 [Amazon Quick Sight 分析嵌入到您的应用程序](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)中。

在下一节中，您可以了解如何使用 [Amazon Quick Sight 嵌入软件开发工具包](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 将第 3 步中的控制台会话 URL 嵌入到您的网站或应用程序页面中。通过使用该开发工具包，您可以执行以下操作：
+ 将控制台会话置于 HTML 页面上。
+ 将参数传入控制台会话。
+ 使用为应用程序自定义的消息处理错误状态。

调用 `GetSessionEmbedUrl` API 操作获取可嵌入应用程序的 URL。该 URL 的有效期为 5 分钟，生成的会话的有效期为 10 个小时。该 API 操作为 URL 提供 `auth_code` 以启用单点登录会话。

下面显示了 `get-dashboard-embed-url` 的示例响应：

```
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
{
     "Status": "200",
     "EmbedUrl": "https: //dashboards.example.com/embed/620bef10822743fab329fb3751187d2d...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 Amazon Quick Sight Embedding [SDK 或将此 URL 添加到 iframe 中，将此控制台会话嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），Amazon Quick Sight 会使用这些数字，并且不会随着窗口大小调整而改变视觉效果。如果您设置相对的百分比高度和宽度，Amazon Quick Sight 会提供响应式布局，该布局会随着窗口大小的变化而进行修改。通过使用 Amazon Quick Sight Embedding SDK，您还可以控制控制台会话中的参数，并接收有关页面加载完成和错误的回调。

以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。

```
<!DOCTYPE html>
<html>

<head>
    <title>Basic Embed</title>

    <script src="./quicksight-embedding-js-sdk.min.js"></script>
    <script type="text/javascript">
        var dashboard;

        function embedDashboard() {
            var containerDiv = document.getElementById("embeddingContainer");
            var options = {
                // replace this dummy url with the one generated via embedding API
                url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",  
                container: containerDiv,
                scrolling: "no",
                height: "700px",
                width: "1000px",
                footerPaddingEnabled: true
            };
            dashboard = QuickSightEmbedding.embedDashboard(options);
        }
    </script>
</head>

<body onload="embedDashboard()">
    <div id="embeddingContainer"></div>
</body>

</html>
```

要使此示例起作用，请务必使用 Amazon Quick Sight Embedding SDK 将嵌入式控制台会话加载到您的网站上 JavaScript。要获取副本，请执行下列操作之一：
+ 从中下载 [Amazon Quick Sight 嵌入 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) GitHub。该存储库由一组 Amazon Quick Sight 开发人员维护。
+ 从下载最新的嵌入式 SDK 版本[https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)。
+ 如果您使用`npm` JavaScript 依赖关系，请通过运行以下命令下载并安装它。

  ```
  npm install amazon-quicksight-embedding-sdk
  ```