`。
```
aws quicksight register-user --aws-account-id 111222333 --namespace default --email cognito-user@amazon.com --user-role ADMIN --identity-type IAM
--iam-arn arn:aws:iam::111222333:role/CognitoQuickSightRole
--session-name cognito-user --external-login-federation-provider-type COGNITO
--external-login-id us-east-1:12345678-1234-1234-abc1-a1b1234567 --region us-east-1
```
如果外部登录提供程序是自定义 OpenID Connect（OIDC）提供程序，请使用以下 CLI 代码创建用户。
```
aws quicksight register-user --aws-account-id account-id --namespace namespace
--email user-email --user-role user-role --identity-type IAM
--iam-arn arn:aws:iam::account-id:role/identity-provider-associated-iam-role
--session-name identity-username --external-login-federation-provider-type CUSTOM_OIDC
--custom-federation-provider-url custom-identity-provider-url
--external-login-id custom-provider-identity-id --region identity-region
```
示例如下：
```
aws quicksight register-user --aws-account-id 111222333 --namespace default
--email identity-user@amazon.com --user-role ADMIN --identity-type IAM
--iam-arn arn:aws:iam::111222333:role/CustomIdentityQuickSightRole
--session-name identity-user --external-login-federation-provider-type CUSTOM_OIDC
--custom-federation-provider-url idp.us-east-1.amazonaws.com/us-east-1_ABCDE
--external-login-id 12345678-1234-1234-abc1-a1b1234567 --region us-east-1
```
要了解有关在 CLI `RegisterUser` 中使用的更多信息，请参阅 *Amazon Quick API 参考[RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)*中的。
### DescribeUser 用于检查用户的外部登录信息
如果用户是来自外部登录提供程序的基于角色的联合用户，请使用 `DescribeUser` API 操作查看其外部登录信息，如以下代码所示。
```
aws quicksight describe-user --aws-account-id account-id --namespace namespace
--user-name identity-provider-associated-iam-role/identity-username
--region identity-region
```
示例如下：
```
aws quicksight describe-user --aws-account-id 111222333 --namespace default --user-name IdentityQuickSightRole/user --region us-west-2
```
结果包含外部登录信息字段（如果有）。以下为示例。
```
{
"Status": 200,
"User": {
"Arn": "arn:aws:quicksight:us-east-1:111222333:user-default-IdentityQuickSightRole-user",
"UserName": "IdentityQuickSightRole-user",
"Email": "user@amazon.com",
"Role": "ADMIN",
"IdentityType": "IAM",
"Active": true,
"PrincipalId": "federated-iam-AROAAAAAAAAAAAAAA:user",
"ExternalLoginFederationProviderType": "COGNITO",
"ExternalLoginFederationProviderUrl": "cognito-identity.amazonaws.com",
"ExternalLoginId": "us-east-1:123abc-1234-123a-b123-12345678a"
},
"RequestId": "12345678-1234-1234-abc1-a1b1234567"
}
```
要了解有关在 CLI `DescribeUser` 中使用的更多信息，请参阅 *Amazon Quick API 参考[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html)*中的。
### UpdateUser 用于更新用户的外部登录信息
在某些情况下，您可能会发现 `DescribeUser` 结果中为用户保存的外部登录信息不正确或缺少外部登录信息。如果是这样，您可以使用 `UpdateUser` API 操作对其进行更新。使用以下示例。
对于 Amazon Cognito 用户，请使用以下示例。
```
aws quicksight update-user --aws-account-id account-id --namespace namespace
--user-name cognito-associated-iam-role/cognito-username
--email user-email --role user-role
--external-login-federation-provider-type COGNITO
--external-login-id cognito-identity-id --region identity-region
```
示例如下：
```
aws quicksight update-user --aws-account-id 111222333 --namespace default
--user-name CognitoQuickSightRole/cognito-user --email cognito-user@amazon.com
--role ADMIN --external-login-federation-provider-type COGNITO
--external-login-id us-east-1:12345678-1234-1234-abc1-a1b1234567 --region us-west-2
```
对于自定义 OIDC 提供程序用户，请使用以下示例。
```
aws quicksight update-user --aws-account-id account-id --namespace namespace
--user-name identity-provider-associated-iam-role/identity-username
--email user-email --role user-role
--external-login-federation-provider-type CUSTOM_OIDC
--custom-federation-provider-url custom-identity-provider-url
--external-login-id custom-provider-identity-id --region identity-region
```
示例如下：
```
aws quicksight update-user --aws-account-id 111222333 --namespace default
--user-name IdentityQuickSightRole/user --email user@amazon.com --role ADMIN
--external-login-federation-provider-type CUSTOM_OIDC
--custom-federation-provider-url idp.us-east-1.amazonaws.com/us-east-1_ABCDE
--external-login-id 123abc-1234-123a-b123-12345678a --region us-west-2
```
如果要删除用户的外部登录信息，请使用 `NONE` `external login federation provider type`。使用以下 CLI 命令删除外部登录信息。
```
aws quicksight update-user --aws-account-id account-id --namespace namespace
--user-name identity-provider-associated-iam-role/identity-username
--email user-email --role user-role
--external-login-federation-provider-type NONE --region identity-region
```
示例如下：
```
aws quicksight update-user --aws-account-id 111222333 --namespace default
--user-name CognitoQuickSightRole/cognito-user --email cognito-user@amazon.com --role ADMIN --external-login-federation-provider-type NONE --region us-west-2
```
要了解有关在 CLI `UpdateUser` 中使用的更多信息，请参阅 *Amazon Quick API 参考[UpdateUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_UpdateUser.html)*中的。
# 我的电子邮件登录停止工作
目前，电子邮件区分大小写。如果您的电子邮件不工作，请向您的管理员核实它是否为大小写字母混合。使用您所输入的电子邮件。
# Quick Sight 的视觉问题
参阅下节内容帮助您排查视觉对象及其格式设置问题。
**Topics**
+ [无法看到我的视觉对象](troubleshoot-adding-visuals.md)
+ [打印文档上出现反馈栏](troubleshoot-printing-docs.md)
+ [地图不显示位置](troubleshoot-geocoding.md)
+ [数据透视表停止工作](troubleshoot-pivot-tables.md)
+ [我的视觉对象找不到缺失的列](troubleshooting-dataset-changed-columns.md)
+ [我的视觉对象无法找到查询表](troubleshooting-dataset-changed-tables.md)
+ [更改计算字段后视觉对象未更新](troubleshooting-visual-refresh.md)
+ [在 Quick Sight 中，带有科学记数法的 Microsoft Excel 文件中的值格式不正确](troubleshooting-number-formatting.md)
# 无法看到我的视觉对象
参阅下节内容帮助您排查缺少视觉对象的问题。在继续之前，请检查以确保您仍然可以访问自己的数据来源。如果您无法连接到自己的数据来源，请参阅 [Amazon Quick Sight 的数据源连接问题](troubleshoot-connect-to-datasources.md)。
+ 如果您在向分析中添加视觉对象时遇到问题，请尝试以下方法：
+ 检查您的连接并确认您有权访问 Quick Sight 用于访问的所有域名。要查看所有 URLs Quick Sight 使用情况的列表，请参阅 Qu [ick Sight 访问的域名](https://docs.aws.amazon.com//quicksight/latest/developerguide/vpc-interface-endpoints.html#vpc-interface-endpoints-restrictvpc-interface-endpoints-supported-domains)。
+ 检查您尝试添加的对象是否超过限额允许的数量。Amazon Quick Sight 在一次分析中支持多达 30 个数据集，在单个工作表中支持多达 30 个视觉对象，每次分析最多支持 20 个工作表。
+ 假设您正在编辑选定数据来源的分析，但与该数据来源的连接意外终止。由此产生的错误状态可能会阻止对分析进行进一步更改。这种情况下，将无法在分析中添加更多视觉对象。检查此状态。
+ 如果您的视觉对象无法加载，请尝试以下操作：
+ 如果使用的是企业网络，请向网络管理员寻求帮助，并验证网络的防火墙设置是否允许来自 `*.aws.amazon.com`、`amazonaws.com`、`wss://*.aws.amazon.com`、和 `cloudfront.net` 的流量。
+ 为 `*.aws.amazon.com`、`amazonaws.com`、`wss://*.aws.amazon.com` 和 `cloudfront.net` 向您的广告拦截器添加例外。
+ 如果使用的是代理服务器，请确认 `*.quicksight.aws.amazon.com` 和 `cloudfront.net` 已添加到已批准的域列表（允许列表）中。
# 打印文档上出现反馈栏
浏览器有时会打印页面上的文档反馈栏，遮挡一些打印内容。
为避免此问题，请使用屏幕左下方的旋转向下图标（如下所示）将反馈栏最小化。然后再打印文档。
![\[\]](http://docs.aws.amazon.com/zh_cn/quick/latest/userguide/images/printing-docs.png)
# 地图不显示位置
要使自动映射（称为地理编码）在地图上起作用，请确保您的数据必须做好了遵循特定规则的准备。如需帮助解决地理空间方面的问题，请参阅[地理空间故障排除](geospatial-troubleshooting.md)。如需准备数据以用于地理空间图表方面的帮助，请参阅[添加地理空间数据](geospatial-data-prep.md)。
# 数据透视表停止工作
如果数据透视表超出了基础数据库的计算限制，就会发生这种情况，这通常是由字段井中的项目组合引起的。也就是说，是由行、列、指标和表计算的组合引起的。要降低复杂性级别并降低出错的可能性，请简化数据透视表。有关更多信息，请参阅 [数据透视表最佳实践](pivot-table-best-practices.md)。
# 我的视觉对象找不到缺失的列
我的分析中的视觉对象的效果不符合预期。错误消息提示 `"The column(s) used in this visual do not exist."`
导致此错误的最常见原因是您的数据来源架构已更改。例如，列名可能从 `a_column` 更改为 `b_column`。
根据数据集访问数据来源的方式，选择下列选项之一。
+ 如果数据集基于自定义 SQL，请执行以下一项或多项操作：
+ 编辑数据集。
+ 编辑 SQL 语句。
例如，如果表名已从 `a_column` 更改为 `b_column`，您可以更新 SQL 语句以创建一个别名：`SELECT b_column as a_column`。通过使用别名在数据集中维护相同的字段名称，您可以避免将列作为新实体添加到视觉对象中。
完成此操作后，选择**保存并可视化**。
+ 如果数据集不是基于自定义 SQL，请执行以下一项或多项操作：
+ 编辑数据集。
+ 对于现在具有不同名称的字段，请在数据集中重命名它们。您可以使用原始数据集中的字段名称。然后打开分析，将重命名的字段添加到受影响的视觉对象中。
完成此操作后，选择**保存并可视化**。
# 我的视觉对象无法找到查询表
在这种情况下，您分析中视觉对象的效果不符合预期。错误消息提示 `"Amazon Quick Sight can’t find the query table."`
导致此错误的最常见原因是您的数据来源架构已更改。例如，表名可能从 `x_table` 更改为 `y_table`。
根据数据集访问数据来源的方式，选择下列选项之一。
+ 如果数据集基于自定义 SQL，请执行以下一项或多项操作：
+ 编辑数据集。
+ 编辑 SQL 语句。
例如，如果表名已从 `x_table` 更改为 `y_table`，您可以更新 SQL 语句中的 FROM 子句以改为引用新表。
完成此操作后，选择**保存并可视化**，然后选择每个视觉对象并根据需要重新添加字段。
+ 如果数据集不是基于自定义 SQL，请执行以下操作：
1. 使用新表（例如 `y_table`）创建新数据集。
1. 打开您的分析。
1. 使用新创建的数据集替换原始数据集。如果没有列更改，则在替换数据集后，所有视觉对象都应正常工作。有关更多信息，请参阅 [替换数据集](replacing-data-sets.md)。
# 更改计算字段后视觉对象未更新
更新许多其他字段所依赖的计算字段时，使用实体可能无法按预期进行更新。例如，当您更新可视化字段使用的计算字段时，视觉对象不会按预期进行更新。
要解决此问题，请刷新您的互联网浏览器。
# 在 Quick Sight 中，带有科学记数法的 Microsoft Excel 文件中的值格式不正确
当你连接到 Microsoft Excel 文件时，该文件中的数字列包含带有科学计数法的值，它们在 Quick Sight 中可能无法正确格式化。例如，在 Quick Sight 中，值 1.59964E\$111（实际上是 159964032802）的格式为 1599640000。这可能会导致分析不正确。
要解决此问题，请按照 Microsoft Excel `Text` 中的格式设置该列的格式，然后将文件上传到 Quick Sight。
# 使用亚马逊 Quick Sight 进行开发
我们为 Amazon Quick Sight 提供 API 操作，还提供软件开发套件 (SDKs) AWS ，使您可以从首选的编程语言访问 Amazon Quick Sight。目前，您可以管理用户和组。在企业版中，您还可以在网页或应用程序中嵌入控制面板。
要监控您的账户向 Amazon Quick Sight API 发出的调用，包括由 AWS 管理控制台、命令行工具和其他服务进行的调用，请使用 AWS CloudTrail。有关更多信息，请参阅 [AWS CloudTrail 《用户指南》](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。
## 所需知识
如果您计划通过 API 访问 Amazon Quick Sight，则应熟悉以下内容：
+ JSON
+ Web 服务
+ HTTP 请求
+ 一种或多种编程语言，例如 Java JavaScript、Python 或 C\$1
我们建议您访问 AWS [入门资源中心](https://aws.amazon.com/getting-started/tools-sdks/)，了解所提供的内容 AWS SDKs 和工具包。
尽管您可以使用终端和最喜欢的文本编辑器，但集成式开发环境（IDE）提供的更具视觉效果的 UI 体验可能会让您受益匪浅。我们 IDEs 在 “*AWS 入门资源中心*” 的 “[IDE 和 IDE 工具包](https://aws.amazon.com/getting-started/tools-sdks/#IDE_and_IDE_Toolkits)” 部分提供了一个列表。该网站提供了可供您下载的首选 IDE 的 AWS 工具包。有些 IDEs 还提供教程，以帮助您更多地了解编程语言。
## Amazon Quick Sight 可用的 API 操作
AWS 为喜欢使用特定语言的 API 操作而不是通过 HTTPS 提交请求来构建应用程序的软件开发人员提供了库、示例代码、教程和其他资源。这些库文件提供可自动执行任务的基本功能，例如以加密方式对请求签名、重试请求和处理错误响应。这些库有助于您更轻松地入门。
有关下载的更多信息 AWS SDKs，请参阅[AWS SDKs 和工具](https://aws.amazon.com/tools/)。以下链接是特定语言的 API 文档的示例。
**AWS Command Line Interface**
+ [AWS CLI QuickSight Command Reference](https://docs.aws.amazon.com/cli/latest/reference/quicksight/index.html)
+ [AWS CLI 用户指南](https://docs.aws.amazon.com/cli/latest/userguide/)
+ [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/)
**适用于 .NET 的 AWS SDK**
+ [Amazon.Quicksight](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=QuickSight/NQuickSight.html)
+ [Amazon.Quicksight.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=QuickSight/NQuickSightModel.html)
**适用于 C\$1\$1 的 AWS SDK**
+ [Aws:QuickSight::: QuickSightClient 类参考](https://sdk.amazonaws.com/cpp/api/LATEST/class_aws_1_1_quick_sight_1_1_quick_sight_client.html)
**适用于 Go 的 AWS SDK**
+ [quicksight](https://docs.aws.amazon.com/sdk-for-go/api/service/quicksight/)
**适用于 Java 的 AWS SDK**
+ [com.amazonaws.services.quicksight](https://docs.aws.amazon.com/sdk-for-java/latest/reference/index.html?com/amazonaws/services/quicksight/package-summary.html)
+ [com.amazonaws.services.quicksight.model](https://docs.aws.amazon.com/sdk-for-java/latest/reference/index.html?com/amazonaws/services/quicksight/model/package-summary.html)
**适用于 JavaScript 的 AWS SDK**
+ [AWS QuickSight](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/QuickSight.html)
**适用于 PHP 的 AWS SDK**
+ [QuickSightClient](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.QuickSight.QuickSightClient.html)
**适用于 Python (Boto3) 的 AWS SDK**
+ [Amazon Quick Sight](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/quicksight.html)
**适用于 Ruby 的 AWS SDK**
+ [Aws:: QuickSight](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/QuickSight.html)
# 术语和概念
本节提供了 Amazon Quick Sight 开发术语列表。
**匿名 Amazon Quick Sight 用户：**— 临时的 Amazon Quick Sight 用户身份，实际上属于命名空间，只能通过嵌入使用。您可以使用基于标签的规则为此类用户实现行级别安全性。
**调用方身份：**– 发出 API 请求的 AWS Identity and Access Management 用户的身份。来电者的身份由 Amazon Quick Sight 使用请求所附的签名确定。通过使用我们提供的开发工具包客户端，您无需以手动方式生成签名或将其附加到请求。但是，如果需要的话，您也可以手动完成上述操作。
**调用者身份：**— 除了来电者身份（但不能替代来电者身份）之外，在拨打 Amazon Quick Sight 时，您还可以通过 IAM `AssumeRole` API 假设来电者的身份。 AWS 通过调用者的身份批准来电者。这样做是为了避免必须明确添加属于同一 Amazon Quick Sight 订阅的多个账户。
**命名空间：**– 一种逻辑容器，允许您隔离用户群体以组织客户、子公司、团队等。有关更多信息，请参阅[使用隔离命名空间支持多租户](https://docs.aws.amazon.com/quicksight/latest/user/namespaces.html)
**QuickSight ARN: —** 亚马逊资源名称 (ARN)。Amazon Quick Sight 资源使用其名称或 ARN 进行标识。例如，以下是针对名ARNs 为的群组`MyGroup1`、名为的用户和 ID 为`User1`的仪表板`1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89`：
```
arn:aws:quicksight:us-east-1:111122223333:group/default/MyGroup1
arn:aws:quicksight:us-east-1:111122223333:user/default/User1
arn:aws:quicksight:us-west-2:111122223333:dashboard/1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89
```
以下示例显示了名 ARNs 为的模板`MyTemplate`和名为的仪表板`MyDashboard`。
1. 模板的 ARN 示例
```
arn:aws:quicksight:us-east-1:111122223333:template/MyTemplate
```
1. 模板的 ARN 示例，引用模板的特定版本
```
arn:aws:quicksight:us-east-1:111122223333:template/MyTemplate/version/10
```
1. 模板别名的 ARN 示例
```
arn:aws:quicksight:us-east-1:111122223333:template/MyTemplate/alias/STAGING
```
1. 控制面板的 ARN 示例
```
arn:aws:quicksight:us-east-1:111122223333:dashboard/MyDashboard
```
1. 控制面板的 ARN 示例，引用控制面板的特定版本
```
arn:aws:quicksight:us-east-1:111122223333:dashboard/MyDashboard/version/10
```
根据具体情况，您可能需要提供实体的名称、ID 或 ARN。如果你有名字，你可以使用一些 Amazon Quick Sight API 操作来检索 ARN。
**Amazon Quick Sight 控制面板：**— 识别根据分析或模板创建的 Amazon Quick Sight 报告的实体。Amazon Quick Sight 控制面板是可共享的。您可以通过相应的权限从中创建计划的电子邮件报告。`CreateDashboard` 和 `DescribeDashboard` API 操作作用于控制面板实体。
**Amazon Quick Sight 模板：**— 封装了创建分析或控制面板所需的元数据的实体。它通过用占位符替换与分析相关的数据集来对其进行抽象。模板可用于创建控制面板，方法是将数据集占位符替换为遵循用于创建源分析和模板的相同架构的数据集。
**Amazon Quick Sight 用户：**— 这是你的 API 调用所依据的 Amazon Quick Sight 用户身份。此用户与来电者身份不同，但可能是 Amazon Quick Sight 中映射到该用户的身份。
# 使用 Amazon Quick Sight API 开发应用程序
您可以使用访问针对您正在使用的编程语言或平台量身定制的 API，从而管理部署的大部分方面。 AWS SDKs 有关更多信息，请参阅 [AWS SDKs](https://aws.amazon.com/tools/#SDKs)。
有关 API 操作的更多信息，请参阅 [Amazon Quick Sight API 参考](https://docs.aws.amazon.com/quicksight/index.html?id=docs_gateway)。
在调用 Amazon Quick Sight API 操作之前，您需要在附加到您的 IAM 身份的策略中`quicksight:operation-name`获得许可。例如，要调用 `list-users`，您需要 `quicksight:ListUsers` 权限。该模式适用于所有操作。
如果不确定所需的具体权限，您可以尝试进行调用。客户端会告诉您到底缺少什么权限。您可以在权限策略的“资源”字段中使用星号 (`*`)，而非指定显式资源。不过，建议您尽量对每个权限施加限制。您可以使用用户的 Amazon Quick Sight Amazon 资源名称 (ARN) 标识符在策略中指定或排除资源，从而限制用户访问。
有关更多信息，请参阅下列内容：
+ [亚马逊 Quick Sight 的 IAM 政策示例](https://docs.aws.amazon.com/quicksight/latest/user/iam-policy-examples.html)
+ [操作、资源和条件键](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonquicksight.html)
+ [IAM JSON 策略元素](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html)
要检索用户或组的 ARN，请对相关资源使用 `Describe` 操作。您也可以在 IAM 中添加条件，以进一步限制在某些情况下对 API 的访问。例如，`User1`添加到时，主要资源是 `Group1``Group1`，因此您可以允许或拒绝访问某些群组，但也可以使用 IAM Amazon Quick Sight 密钥添加条件，`quicksight:UserName`以允许或阻止将某些用户添加到该群组。
下面是一个示例策略。这意味着只要添加到组中的用户名不是 `user1`，附加该策略的调用方就能够在任意组上调用 `CreateGroupMembership` 操作。
```
{
"Effect": "Allow",
"Action": "quicksight:CreateGroupMembership",
"Resource": "arn:aws:quicksight:us-east-1:aws-account-id:group/default/*",
"Condition": {
"StringNotEquals": {
"quicksight:UserName": "user1"
}
}
}
```
------
#### [ AWS CLI ]
以下过程说明了如何通过 AWS CLI 与 Amazon Quick Sight API 操作进行交互。以下说明已在 Bash 中进行测试，在其他命令行环境中应可取得相同或相似的效果。
1. 在您的环境中安装 AWS SDK。有关如何执行该操作的说明，请参阅 [AWS 命令行界面](https://aws.amazon.com/cli/)。
1. 使用以下命令和后续说明设置您的 AWS CLI 身份和区域。使用具有适当权限的 IAM 身份或角色的凭证。
```
aws configure
```
1. 通过发出以下命令来查看 Amazon Quick Sight SDK 的帮助：
```
aws quicksight help
```
1. 要获取有关如何使用 API 的详细说明，请输入 API 名称，然后输入 help，如下所示：
```
aws quicksight list-users help
```
1. 现在你可以调用 Amazon Quick Sight API 操作了。此示例返回您账户中的 Amazon Quick Sight 用户列表。
```
aws quicksight list-users --aws-account-id aws-account-id --namespace default --region us-east-1
```
------
#### [ Java SDK ]
使用以下步骤设置与 Amazon Quick Sight 交互的 Java 应用程序。
1. 首先，在 IDE 中创建一个 Java 项目。
1. 将 Amazon Quick Sight 软件开发工具包导入到您的新项目中，例如：`AWSQuickSightJavaClient-1.11.x.jar`
1. 在你的 IDE 为 Amazon Quick Sight SDK 编制索引后，你应该能够按如下方式添加导入行：
```
import com.amazonaws.services.quicksight.AmazonQuickSight;
```
如果 IDE 未将其识别为有效名称，请确认是否已导入开发工具包。
1. 与其他软件开发工具包一样 AWS SDKs，Amazon Quick Sight SDK 需要外部依赖才能执行其许多功能。您需要将它们下载并导入到同一个项目中。以下依赖项是必需的：
+ `aws-java-sdk-1.11.402.jar`（AWS Java SDK 和凭据设置）— 参见[设置适用于 Java 的 AWS 软件开发工具包](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-install.html)
+ `commons-logging-1.2.jar`— 见 [https://commons.apache。 org/proper/commons-logging/download](https://commons.apache.org/proper/commons-logging/download_logging.cgi)\$1logging.cgi
+ `jackson-annotations-2.9.6.jar``jackson-core-2.9.6.jar`、和 `jackson-databind-2.9.6.jar` — 见 [http://repo1.maven。 org/maven2/com/fasterxml/jackson/core](https://repo1.maven.org/maven2/com/fasterxml/jackson/core/)/
+ `httpclient-4.5.6.jar`、`httpcore-4.4.10.jar` – 请参阅 [https://hc.apache.org/downloads.cgi](https://hc.apache.org/downloads.cgi)
+ `joda-time-2.1.jar`— 参见 [ https://mvnrepository.com/artifact/joda-time/joda](https://mvnrepository.com/artifact/joda-time/joda-time/2.1)-time/2.1
1. 现在，您已准备好创建 Amazon Quick Sight 客户端。您可以使用客户端能够与之通信的默认公有终端节点，也可以显式引用该终端节点。提供 AWS 凭证的方法有多种。在以下示例中，我们提供一种直接、简单的方法。以下客户端方法用于进行下面所有的 API 调用：
```
private static AmazonQuickSight getClient() {
final AWSCredentialsProvider credsProvider = 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() {}
};
return AmazonQuickSightClientBuilder
.standard()
.withRegion(Regions.US_EAST_1.getName())
.withCredentials(credsProvider)
.build();
}
```
1. 现在，我们可以使用上述客户端列出我们的 Amazon Quick Sight 账户中的所有用户。
**注意**
您必须提供订阅 Amazon Quick Sight 时使用的 AWS 账户编号。这必须与来电者身份的 AWS 账户 ID 相匹配。目前，不支持跨账户调用。此外，必需的参数`namespace`应始终设置为*default*。
```
getClient().listUsers(new ListUsersRequest()
.withAwsAccountId("relevant_AWS_account_ID")
.withNamespace("default"))
.getUserList().forEach(user -> {
System.out.println(user.getArn());
});
```
1. 要查看所有可能的 API 操作及其使用的请求对象的列表，您可以**按住 Ctrl 键单击** IDE 中的客户端对象，以查看 Amazon Quick Sight 界面。或者，也可以在 Amazon Quick Sight JavaClient JAR 文件的`com.amazonaws.services.quicksight`包中找到它。
------
#### [ JavaScript (Node.js) SDK ]
使用以下步骤通过 Node.js 与 Amazon Quick Sight 进行交互。
1. 使用以下命令设置节点环境：
+ `npm install aws-sdk`
+ `npm install aws4 `
+ `npm install request`
+ `npm install url`
1. 有关使用 AWS SDK 配置 Node.js 和设置凭据的信息，请参阅-> S [DK v 适用于 JavaScript 的 AWS SDK 2 开发者指南](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html)。
1. 使用下面的代码示例测试设置。必须使用 HTTPS。该示例显示了 Amazon Quick Sight 操作的完整列表及其网址请求参数，然后是您账户中的 Amazon Quick Sight 用户列表。
```
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',
});
console.log(quicksight.config.apiConfig.operations);
quicksight.listUsers({
// Enter your actual AWS account ID
'AwsAccountId': 'relevant_AWS_account_ID',
'Namespace': 'default',
}, function(err, data) {
console.log('---');
console.log('Errors: ');
console.log(err);
console.log('---');
console.log('Response: ');
console.log(data);
});
```
------
#### [ Python3 SDK ]
使用以下步骤创建定制`botocore`包以与 Amazon Quick Sight 进行交互。
1. 在您的环境 AWS 目录中创建凭证文件。在 a Linux/Mac-based environment, that file is called \$1/.aws/credentials 中看起来像这样：
```
[default]
aws_access_key_id = Your_IAM_access_key
aws_secret_access_key = Your_IAM_secret_key
```
1. 解压缩文件夹 `botocore-1.12.10`。将目录切换到 `botocore-1.12.10`，然后进入 Python3 解释器环境。
1. 响应以字典对象的形式返回。它们都有一个包含请求 IDs 和响应状态的`ResponseMetadata`条目。其他条目基于您运行的操作类型。
1. 下面是一个示例应用程序，它首先创建、删除和列出组，然后列出 QuickSight 账户中的用户：
```
import botocore.session
default_namespace = 'default'
account_id = 'relevant_AWS_Account'
session = botocore.session.get_session()
client = session.create_client("quicksight", region_name='us-east-1')
print('Creating three groups: ')
client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup1')
client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup2')
client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup3')
print('Retrieving the groups and listing them: ')
response = client.list_groups(AwsAccountId = account_id, Namespace=default_namespace)
for group in response['GroupList']:
print(group)
print('Deleting our groups: ')
client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup1')
client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup2')
client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup3')
response = client.list_users(AwsAccountId = account_id, Namespace=default_namespace)
for user in response['UserList']:
print(user)
```
------
#### [ .NET/C\$1 SDK ]
使用以下步骤通过 C\$1.NET 与 Amazon Quick Sight 进行交互。该示例在 Microsoft Visual for Mac 上构建；根据您的 IDE 和平台，说明可能略有不同。但是，过程应该是相似的。
1. 将 `nuget.zip` 文件解压缩到名为 `nuget` 的文件夹。
1. 在 Visual Studio 中创建一个新的**控制台应用**。
1. 在解决方案下，找到应用程序 **Dependencies (依赖关系)**，然后打开上下文（右键单击）菜单并选择 **Add Packages (添加包)**）。
1. 在源列表中，选择 **Configure Sources (配置源)**。
1. 选择**添加**，然后将源命名为 `QuickSightSDK`。浏览到 `nuget` 文件夹，然后选择 **Add Source (添加源)**。
1. 选择**确定**。然后，`QuickSightSDK`选择所有三个 Amazon Quick Sight 套餐：
+ `AWSSDK.QuickSight`
+ `AWSSDK.Extensions.NETCore.Setup`
+ `AWSSDK.Extensions.CognitoAuthentication`
1. 请单击**添加包**。
1. 将以下示例应用程序复制并粘贴到您的控制台应用编辑器中。
```
using System;
using Amazon.QuickSight.Model;
using Amazon.QuickSight;
namespace DotNetQuickSightSDKTest
{
class Program
{
private static readonly string AccessKey = "insert_your_access_key";
private static readonly string SecretAccessKey = "insert_your_secret_key";
private static readonly string AccountID = "AWS_account_ID";
private static readonly string Namespace = "default"; // leave this as default
static void Main(string[] args)
{
var client = new AmazonQuickSightClient(
AccessKey,
SecretAccessKey,
Amazon.RegionEndpoint.USEast1);
var listUsersRequest = new ListUsersRequest
{
AwsAccountId = AccountID,
Namespace = Namespace
};
client.ListUsersAsync(listUsersRequest).Result.UserList.ForEach(
user => Console.WriteLine(user.Arn)
);
var listGroupsRequest = new ListGroupsRequest
{
AwsAccountId = AccountID,
Namespace = Namespace
};
client.ListGroupsAsync(listGroupsRequest).Result.GroupList.ForEach(
group => Console.WriteLine(group.Arn)
);
}
}
}
```
------
# 亚马逊 Quick Sight 事件集成
借助亚马逊 EventBridge，您可以自动响应 Amazon Quick Sight 中的事件，例如创建或更新新的控制面板。这些事件几乎是实时传送到 EventBridge 的。作为开发人员，您可以编写简单的规则来指示哪些事件值得关注，以及当事件与规则匹配时要采取什么操作。通过使用事件，您可以完成持续备份和部署等使用场景。
**Topics**
+ [支持的事件](#events-supported)
+ [事件有效载荷示例](#sample-events-payload)
+ [创建规则以将 Amazon Quick Sight 事件发送到亚马逊 CloudWatch](events-send-cloudwatch.md)
+ [创建向其发送 Amazon Quick Sight 事件的规则 AWS Lambda](events-send-lambda.md)
## 支持的事件
Amazon Quick Sight 目前支持以下事件。
| Asset type | Action | 事件详细信息类型 | 事件详细信息 |
| --- | --- | --- | --- |
| 控制面板 | Create | 成功创建亚马逊 Quick Sight 控制面板 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1
} |
| 控制面板 | Create | 创建亚马逊 Quick Sight 控制面板失败 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1,
"errors": [
{
"Type": "PARAMETER_NOT_FOUND",
"Message": "Missing property abc"
},
{
"Type": "DATA_SET_NOT_FOUND",
"Message": "Cannot find dataset with id abc"
}
]
} |
| 控制面板 | Create | Amazon Quick Sight 控制面板权限已更新 | {"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83" } |
| 控制面板 | 更新 | 亚马逊 Quick Sight 控制面板更新成功 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1
} |
| 控制面板 | 更新 | 亚马逊 Quick Sight 控制面板更新失败 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1,
"errors": [
{
"Type": "PARAMETER_NOT_FOUND",
"Message": "Missing property abc"
},
{
"Type": "DATA_SET_NOT_FOUND",
"Message": "Cannot find dataset with id abc"
}
]
} |
| 控制面板 | 更新 | Amazon Quick Sight 控制面板权限已更新 | {"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83"} |
| 控制面板 | 发布 | 亚马逊 Quick Sight 控制面板发布版本已更新 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 2
} |
| 控制面板 | 删除 | 亚马逊快速浏览控制面板已删除 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83"
} |
| 分析 | Create | Amazon Quick Sight 分析创建成功 | {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5"
} |
| 分析 | Create | 创建亚马逊 Quick Sight 分析失败 | {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5",
"errors": [
{
"Type": "PARAMETER_NOT_FOUND",
"Message": "Missing property abc"
},
{
"Type": "DATA_SET_NOT_FOUND",
"Message": "Cannot find dataset with id abc"
}
]
} |
| 分析 | Create | Amazon Quick Sight 分析权限已更新 | {"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5" } |
| 分析 | 删除 | 亚马逊 Quick Sight 分析已删除 | {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5"
} |
| 分析 | 更新 | Amazon Quick Sight 分析更新成功 | {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5"
} |
| 分析 | 更新 | Amazon 快速观察分析更新失败 | {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5",
"errors": [
{
"Type": "PARAMETER_NOT_FOUND",
"Message": "Missing property abc"
},
{
"Type": "DATA_SET_NOT_FOUND",
"Message": "Cannot find dataset with id abc"
}
]
} |
| 分析 | 更新 | Amazon Quick Sight 分析权限已更新 | {"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5" } |
| VPC 连接 | Create | 成功创建 Amazon Quick Sight VPC 连接 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "CREATION_SUCCESSFUL"
} |
| VPC 连接 | Create | Amazon Quick Sight VPC 连接创建失败 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "CREATION_FAILED"
} |
| VPC 连接 | 更新 | Amazon Quick Sight VPC 连接更新成功 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "UPDATE_SUCCESSFUL"
} |
| VPC 连接 | 更新 | Amazon Quick Sight VPC 连接更新失败 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "UPDATE_FAILED"
} |
| VPC 连接 | 删除 | 成功删除 Amazon Quick Sight VPC 连接 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "DELETED"
} |
| VPC 连接 | 删除 | Amazon Quick Sight VPC 连接删除失败 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "DELETION_FAILED"
} |
| Folder | Create | 已创建 Amazon 快速浏览文件夹 | {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be",
"parentFolderArn": "arn:aws:quicksight:us-east-1:123456789012:folder/098765432134"
} |
| Folder | Create | 亚马逊 Quick Sight 文件夹权限已更新 | {"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be" } |
| Folder | 更新 | 亚马逊 Quick Sight 文件夹已更新 | {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be"
} |
| Folder | 更新 | 亚马逊 Quick Sight 文件夹权限已更新 | {"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be" } |
| Folder | 删除 | 亚马逊 Quick Sight 文件夹已删除 | {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be"
} |
| Folder | 成员资格更新 | 亚马逊 Quick Sight 文件夹成员资格已更新 | {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be",
"membersAdded": ["arn:aws:quicksight:us-east-1:123456789012:analysis/e5f37119-e24c-4874-901a-af9032b729b5"],
"membersRemoved": []
} |
| 数据集 | Create | 已创建 Amazon 快速视觉数据集 | {
"datasetId": "a6553a81-f97e-4ffa-a860-baea63196efa"
} |
| 数据集 | Create | 亚马逊 Quick Sight 数据集权限已更新 | {"datasetId": "a6553a81-f97e-4ffa-a860-baea63196efa" } |
| 数据集 | 更新 | Amazon 快速瞄准数据集已更新 | {
"datasetId": "a6553a81-f97e-4ffa-a860-baea63196efa"
} |
| 数据集 | 更新 | 亚马逊 Quick Sight 数据集权限已更新 | {"datasetId": "a6553a81-f97e-4ffa-a860-baea63196efa" } |
| 数据集 | 删除 | Amazon 快速视觉数据集已删除 | {
"datasetId": "a6553a81-f97e-4ffa-a860-baea63196efa"
} |
| DataSource | Create | 成功 DataSource 创建亚马逊 Quick Sight | {
"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824"
} |
| DataSource | Create | 亚马逊 Quick Sight DataSource 创建失败 | {
"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824",
"error": {
"message": "AMAZON_ELASTICSEARCH engine version 7.4 is lower than minimum supported version 7.7",
"type": "ENGINE_VERSION_NOT_SUPPORTED"
}
} |
| DataSource | Create | 亚马逊 Quick Sight DataSource 权限已更新 | {"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824" } |
| DataSource | 更新 | 亚马逊 Quick Sight DataSource 更新成功 | {
"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824"
} |
| DataSource | 更新 | 亚马逊 Quick Sight DataSource 更新失败 | {
"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824",
"error": {
"message": "AMAZON_ELASTICSEARCH engine version 7.4 is lower than minimum supported version 7.7",
"type": "ENGINE_VERSION_NOT_SUPPORTED"
}
} |
| DataSource | 更新 | 亚马逊 Quick Sight DataSource 权限已更新 | {"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824" } |
| DataSource | 删除 | Amazon Quick Sig DataSource h | {
"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824"
} |
| Theme | Create | Amazon Quick Sight 主题创建成功 | {
""themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1"
} |
| Theme | Create | 亚马逊 Quick Sight 主题创建失败 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1
} |
| Theme | Create | 亚马逊 Quick Sight 主题权限已更新 | {"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83" } |
| Theme | 更新 | 亚马逊 Quick Sight 主题更新成功 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 2
} |
| Theme | 更新 | 亚马逊 Quick Sight 主题更新失败 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 2
} |
| Theme | 更新 | 亚马逊 Quick Sight 主题权限已更新 | {"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83" } |
| Theme | 删除 | 亚马逊 Quick Sight 主题已删除 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83"
} |
| Theme | 别名创建 | 已创建亚马逊 Quick Sight 主题别名 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"aliasName": "MyThemeAlias"
"versionNumber": 2
} |
| Theme | 别名更新 | Amazon 快速浏览别名已更新 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"aliasName": "MyThemeAlias"
"versionNumber": 4
} |
| Theme | 别名删除 | 亚马逊 Quick Sight 主题别名已删除 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"aliasName": "MyThemeAlias"
"versionNumber": 2
} |
## 事件有效载荷示例
所有事件都遵循标准 EventBridge [对象结构](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html)。详细信息字段是一个 JSON 对象，其中包含有关事件的更多信息。
```
{
"version": "0",
"id": "3acb26c8-397c-4c89-a80a-ce672a864c55",
"detail-type": "QuickSight Dashboard Creation Successful",
"source": "aws.quicksight",
"account": "123456789012",
"time": "2023-10-30T22:06:31Z",
"region": "us-east-1",
"resources": ["arn:aws:quicksight:us-east-1:123456789012:dashboard/6fdbc328-ebbd-457f-aa02-9780173afc83"],
"detail": {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1
}
}
```
# 创建规则以将 Amazon Quick Sight 事件发送到亚马逊 CloudWatch
您可以编写简单的规则来指明您对哪些 Amazon Quick Sight 事件感兴趣，以及当事件与规则匹配时要执行哪些自动操作。例如，您可以将 Amazon Quick Sight 配置为在文件夹中放置 Amazon Quick Sight 资产 CloudWatch 时向亚马逊发送事件。有关更多信息，请参阅 [Amazon EventBridge 用户指南](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html)。
1. 登录 AWS 管理控制台 并打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。
1. 在导航窗格中的**事件**下，选择**规则**。
1. 选择**创建规则**。
1. 为规则输入名称和描述。规则名称在此区域中必须是唯一的。例如，输入 `QuickSightAssetChangeRuleCloudWatch`。
1. 选择**默认**事件总线。
1. 选择 **Rule with an event pattern**（具有事件模式的规则），然后选择 **Next**（下一步）。
1. 对于**事件来源**，选择**AWS 事件或 EventBridge合作伙伴事件**。
1. 在**创建方法**部分中，选择**自定义模式（JSON 编辑器）**。
1. 在**事件模式**文本框中，输入以下片段并选择**下一步**。
```
{
"source": ["aws.quicksight"]
}
```
或者，您可以在 Amazon Quick Sight 中创建仅订阅事件类型子集的规则。例如，仅当将资产添加到 ID 为 `77e307e8-b41b-472a-90e8-fe3f471537be` 的文件夹或从中删除资产时，才会触发以下规则。
```
{
"source": ["aws.quicksight"],
"detail-type": ["QuickSight Folder Membership Updated"],
"detail": {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be"
}
}
```
1. 对于**目标**，选择**AWS 服务** > **CloudWatch 日志组。**
1. 从现有日志组中选择，或通过输入新的日志组名称来创建新的日志组。
1. 您可以选择为此规则添加另一个目标。
1. 在 **Configure tags**（配置标签）中，选择 **Next**（下一步）。
1. 选择 **Create rule**（创建规则）。
有关更多信息，请参阅[亚马逊 EventBridge 用户指南中的创建对事件做出反应的亚马逊 EventBridge 规则](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html)。
# 创建向其发送 Amazon Quick Sight 事件的规则 AWS Lambda
在本教程中，您将创建一个用于在 Amazon Quick Sight 账户中记录资产事件的 AWS Lambda 函数。然后，您将创建一个规则，只要资产发生更爱，便运行该函数。本教程假设你已经注册了 Amazon Quick Sight。
**步骤 1：创建 Lambda 函数**
创建 Lambda 函数以记录状态更改事件。在创建规则时，您可以指定此函数。
1. 登录 AWS 管理控制台 并打开 AWS Lambda 控制台，网址为[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/)。
1. 如果您是首次接触 Lambda，您将看到欢迎页面。选择 **Get Started Now (立即开始)**。否则，选择**创建函数**。
1. 选择 **Author from scratch (从头创作)**。
1. 在“创建函数”页面上，输入 Lambda 函数的名称和描述。例如，将函数命名为 `QuickSightAssetChangeFn`。
1. 在**运行时**中，选择 **Node.js 18x**。
1. 对于**架构**，选择 **x86\$164**。
1. 对于**执行角色**，选择**创建具有基本 Lambda 权限的新角色**或**使用现有角色**，然后选择所需的角色。
1. 选择**创建函数**。
1. 在该**QuickSightAssetChange**页面上，选择 **index.js**。
1. 在 **index.js** 窗格中，删除现有代码。
1. 输入以下代码片段。
```
console.log('Loading function');
exports.handler = async (event, context) => {
console.log('Received QuickSight event:', JSON.stringify(event));
};
```
1. 选择 **Deploy (部署)**。
**步骤 2：创建规则**
创建一条规则，以便在您拥有 create/update/delete Amazon Quick Sight 资产时运行您的 Lambda 函数。
1. 登录 AWS 管理控制台 并打开亚马逊 EventBridge 控制台，网址为[https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/)。
1. 在导航窗格中，选择**规则**。
1. 选择**创建规则**。
1. 为规则输入名称和描述。例如，输入 `QuickSightAssetChangeRule`。
1. 选择**默认**事件总线。
1. 选择 **Rule with an event pattern**（具有事件模式的规则），然后选择 **Next**（下一步）。
1. 对于**事件来源**，选择**AWS 事件或 EventBridge合作伙伴事件**。
1. 在**创建方法**部分中，选择**自定义模式（JSON 编辑器）**。
1. 在**事件模式**文本框中，输入以下片段并选择**下一步**。
```
{
"source": ["aws.quicksight"]
}
```
或者，您可以在 Amazon Quick Sight 中创建仅订阅事件类型子集的规则。例如，仅当将资产添加到 ID 为 `77e307e8-b41b-472a-90e8-fe3f471537be` 的文件夹或从中删除资产时，才会触发以下规则。
```
{
"source": ["aws.quicksight"],
"detail-type": ["QuickSight Folder Membership Updated"],
"detail": {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be"
}
}
```
1. 对于**目标类型**，选择 **AWS 服务**和 **Lambda 函数**。
1. 对于 **Function**（函数），选择您创建的 Lambda 函数。然后选择**下一步**。
1. 在 **Configure tags**（配置标签）中，选择 **Next**（下一步）。
1. 查看您的规则中的步骤。然后，选择 **Create rule**（创建规则）。
**步骤 3：测试规则**
要测试您的规则，请创建一个分析。等待片刻后，验证您的 Lambda 函数是否已调用。
1. 打开 Amazon Quick Sight 控制台，网[https://quicksight.aws.amazon.com址为/](https://quicksight.aws.amazon.com/)。
1. 创建新分析。
1. 在导航窗格中，选择 **Rules (规则)**，再选择所创建规则的名称。
1. 在**规则详细信息**中，选择**监控**。
1. 您将被重定向到 Amazon CloudWatch 控制台。如果您未被重定向，请选择**查看中的指标 CloudWatch**。
1. 在 **All metrics (所有指标)**中，选择所创建规则的名称。该图表表明已调用该规则。
1. 在导航窗格中，选择**日志组**。
1. 选择您的 Lambda 函数的日志组的名称。例如 `/aws/lambda/function-name`。
1. 选择日志流的名称，以查看您启动的实例的函数提供的数据。您应该会看到接收的事件，类似以下内容：
```
{
"version": "0",
"id": "3acb26c8-397c-4c89-a80a-ce672a864c55",
"detail-type": "QuickSight Analysis Creation Successful",
"source": "aws.quicksight",
"account": "123456789012",
"time": "2023-10-30T22:06:31Z",
"region": "us-east-1",
"resources": ["arn:aws:quicksight:us-east-1:123456789012:analysis/e5f37119-e24c-4874-901a-af9032b729b5"],
"detail": {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5"
}
}
```
有关 JSON 格式的 Amazon Quick Sight 事件[的示例，请参阅 Amazon Quick Sight 事件概述](https://docs.aws.amazon.com/quicksight/latest/developerguide/events.html)。
# 亚马逊 Quick Sight 的嵌入式分析
**重要**
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 分析嵌入您的应用程序中
| |
| --- |
| 适用于：企业版 |
要嵌入分析，您可以运行 Amazon Quick Sight 嵌入 API 来生成嵌入代码。或者，对于控制面板，您可以在 Amazon Quick Sight 中共享控制面板时复制嵌入代码。每个选项如下所述。
## 注册用户一键式嵌入
在与账户中的注册用户共享控制面板时，您可以复制控制面板的嵌入代码并将其粘贴到内部应用程序的 HTML 中。
当您想要将 Amazon Quick Sight 控制面板嵌入到用户需要进行身份验证的内部应用程序中时，最好使用一键式企业嵌入。复制嵌入代码时，您会获得一个不变的静态嵌入代码。
有关更多信息，请参阅 [通过一键嵌入代码为注册用户嵌入 Amazon Quick Sight 视觉效果和控制面板](embedded-analytics-1-click.md)。
## 嵌入 Amazon Quick Sight APIs
当你想将 Amazon Quick Sight 体验嵌入到用户必须进行身份验证的内部应用程序或任何人都可以访问的外部应用程序中时，最适合嵌入 Amazon Quick Sight API。使用嵌入 API 操作生成嵌入代码时，您会获得一个一次性代码。
有关更多信息，请参阅 [嵌入 Amazon Quick Sight APIs](embedded-analytics-api.md)。
# 将自定义 Amazon Quick Sight 资产嵌入您的应用程序中
您可以使用 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 中添加运行时嵌入式回调操作
使用嵌入式数据点回调操作在您的软件即服务 (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 嵌入式控制面板和视觉对象的运行时筛选数据
您可以在 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 或更高版本。
## 术语和概念
使用嵌入式运行时筛选时，以下术语可能很有用。
+ *筛选条件组* – 一组单独的筛选条件。位于 `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)。
## 设置
开始之前，请确保您已准备好以下资产和信息。
+ 您想要将 `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 方法接口
**控制面板嵌入 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 嵌入式仪表板和视觉效果的外观
您可以使用 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 控制台分析编辑器中主题旁边的**共享**图标。
## 术语和概念
使用嵌入式运行时主题时，以下术语可能很有用。
+ *主题* – 可应用于多个分析和控制面板的设置集合，可更改内容的显示方式。
+ *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`
## 设置
确保您已准备好以下信息，以开始使用运行时主题。
+ 您要使用的主题的主题。 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 方法接口
**Setter 方法**
下表介绍了开发人员可以用于运行时主题的不同 setter 方法。
| 方法 | 说明 |
| --- | --- |
| `setTheme(themeArn: string)` | 将控制面板或视觉对象的活动主题替换为其他主题。如果应用，则会移除主题覆盖。 如果您无权访问主题或主题不存在，则会返回错误。 |
| `setThemeOverride(themeOverride: ThemeConfiguration)` | 设置动态 `ThemeConfiguration` 以覆盖当前活动主题。这将替换之前设置的主题覆盖。新 `ThemeConfiguration` 中未提供的任何值都将默认为当前活动主题中的值。 如果您提供的 `ThemeConfiguration` 无效，则会返回错误。 |
## 使用主题初始化嵌入式内容
要使用非默认主题初始化嵌入式控制面板或视觉对象，请在 `DashboardContentOptions` 或 `VisualContentOptions` 参数上定义 `themeOptions` 对象，并将 `themeOptions` 中的 `themeArn` 属性设置为所需的主题 ARN。
以下示例使用 `MIDNIGHT` 主题初始化嵌入式控制面板。
```
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';
const embeddingContext = await createEmbeddingContext();
const {
embedDashboard,
} = embeddingContext;
const frameOptions = {
url: '',
container: '#experience-container',
};
const contentOptions = {
themeOptions: {
themeArn: "arn:aws:quicksight::aws:theme/MIDNIGHT"
}
};
// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```
## 使用主题覆盖初始化嵌入式内容
开发人员可以使用主题覆盖在运行时定义嵌入式控制面板或视觉对象的主题。这允许控制面板或视觉对象从第三方应用程序继承主题，而无需在 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: '',
container: '#experience-container',
};
const contentOptions = {
themeOptions: {
"themeOverride":{"Typography":{"FontFamilies":[{"FontFamily":"Comic Neue"}]}}
}
};
// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```
## 使用预加载的主题初始化嵌入式内容
开发人员可以配置一组控制面板主题，以便在初始化时预加载。这对于在不同视图（例如深色和浅色模式）之间快速切换最为有利。嵌入式控制面板或视觉对象最多可使用 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: '',
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 启用指向嵌入式控制面板视图的可共享链接
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`功能配置
当您使用 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 创建共享视图
将 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 视图
创建新的共享视图后，请使用 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 视觉效果和仪表板
您可以使用嵌入代码在应用程序中嵌入视觉对象或控制面板。当你共享控制面板或从 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 视觉效果和控制面板
| |
| --- |
| 适用于：企业版 |
您可以在内部应用程序中嵌入视觉或控制面板，供您的 Amazon Quick Sight 账户的注册用户使用。您可以使用共享控制面板时获得的嵌入代码或从 Amazon Quick Sight 的 “**嵌入” 视觉**菜单中获得的嵌入代码来执行此操作。您无需运行 Amazon Quick Sight 嵌入 API 即可生成嵌入代码。您可以从 Amazon Quick Sight 中复制嵌入代码并将其粘贴到内部应用程序的 HTML 代码中。
当有权访问您要嵌入的控制面板或包含您要嵌入的视觉效果的用户和群组（或您的 Amazon Quick Sight 账户中的所有用户）访问您的内部应用程序时，系统会提示他们使用自己的凭证登录 Amazon Quick Sight 账户。通过身份验证后，他们可以访问各自内部页面上的视觉对象或控制面板。如果启用了单点登录，系统不会提示用户再次登录。
接下来，您可以了解有关如何使用视觉对象或控制面板嵌入代码为注册用户嵌入视觉对象或控制面板的说明。
## 开始之前
在开始之前，您应确保满足以下条件：
+ 互联网浏览器设置包含以下某一项，以允许弹出窗口与 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：授予对控制面板的访问权限
要让用户访问您的嵌入式控制面板，请向其授予查看该控制面板的权限。您可以授予个人用户和用户组对控制面板的访问权限，也可以向账户中的所有人授予访问权限。视觉对象权限在控制面板级别确定。要授予对嵌入式视觉对象的访问权限，请授予对视觉对象所属控制面板的访问权限。有关更多信息，请参阅 [授予对控制面板的访问权限](share-a-dashboard.md)。
## 步骤 2：将要嵌入视觉对象或控制面板的域放入允许列表
要在内部应用程序中嵌入视觉对象和控制面板，请确保您要嵌入的域名已列入您的 Amazon Quick Sight 账户的允许名单。有关更多信息，请参阅 [允许列出静态域](manage-domains.md#embedding-static)。
## 步骤 3：获取嵌入代码
要获取视觉对象或控制面板嵌入代码，请按照以下过程操作。
**获取控制面板嵌入代码**
1. 在 Amazon Quick Sight 中打开已发布的控制面板，然后选择右上角的 “**共享**”。再选择**共享控制面板**。
1. 在打开的**共享控制面板**页面中，选择左上角的**复制嵌入代码**。
嵌入代码已复制到剪贴板，且类似于以下内容。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。
```
```
**获取视觉对象嵌入代码**
1. 在 Amazon Quick Sight 中打开已发布的控制面板，然后选择要嵌入的视觉效果。然后打开视觉对象右上角的视觉对象菜单，从中选择**嵌入视觉对象**。
1. 在打开的**嵌入视觉对象**窗格中，选择**复制代码**。
嵌入代码已复制到剪贴板，且类似于以下内容。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。
```
```
## 步骤 4：将代码粘贴到内部应用程序的 HTML 页面中
要将嵌入代码粘贴到内部应用程序的 HTML 页面中，请按照以下过程操作。
**将代码粘贴到内部应用程序的 HTML 页面中**
+ 打开要嵌入控制面板的任何页面的 HTML 代码，然后将嵌入代码粘贴到其中。
以下示例演示了嵌入式控制面板的大致样式。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。
```
Example.com - Employee Portal
Current shipment stats
```
以下示例演示了嵌入式视觉对象的大致样式。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。
```
Example.com - Employee Portal
Current shipment stats
```
例如，假设您希望将视觉对象或控制面板嵌入 Google 协作平台内部页面。您可以在 Google 协作平台上打开该页面，然后将嵌入代码粘贴到嵌入小部件中。
如果要将视觉对象或仪表板嵌入到 Microsoft 内部 SharePoint 网站中，可以创建一个新页面，然后将嵌入代码粘贴到嵌入的 Web 部件中。
# 使用一键嵌入代码为匿名用户嵌入 Amazon Quick Sight 视觉效果和控制面板
| |
| --- |
| 适用于：企业版 |
您可以使用在 Amazon Quick Sight 中共享视觉对象或控制面板时获得的嵌入代码将视觉对象或控制面板嵌入到公共网站中。您还可以使用 Amazon Quick Sight 控制台开启公开共享，并自动向互联网上的任何人授予访问共享视觉对象或控制面板的权限。
接下来，您可以了解如何为视觉对象或控制面板开启公开共享，以及如何嵌入视觉对象或控制面板供互联网上的任何人查看。在这两种情况下，您都可以使用一键式嵌入代码来完成此操作。
## 开始之前
在开始之前，您应确保满足以下条件：
+ 互联网浏览器设置包含以下某一项，以允许弹出窗口与共享使用的 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：开启控制面板的公有访问权限
要让互联网上的任何人都能访问您的嵌入式视觉对象或控制面板，请先开启控制面板的公有访问权限。视觉对象权限在控制面板级别确定。要授予对嵌入式视觉对象的访问权限，请授予对视觉对象所属控制面板的访问权限。有关更多信息，请参阅 [允许互联网上的任何人访问 Amazon Quick Sight 控制面板](share-a-dashboard-grant-access-anyone.md)。
## 步骤 2：将要嵌入视觉对象或控制面板的域放入允许列表
要在公共应用程序、wiki 或门户中嵌入视觉对象和控制面板，请确保您要嵌入的域名位于您的 Amazon Quick Sight 账户的允许列表中。
## 步骤 3：获取嵌入代码
要获取视觉对象或控制面板嵌入代码，请按照以下过程操作。
**获取控制面板嵌入代码**
1. 在 Amazon Quick Sight 中打开已发布的控制面板，然后选择右上角的 “**共享**”。再选择**共享控制面板**。
1. 在打开的**共享控制面板**页面中，选择左上角的**复制嵌入代码**。
嵌入代码已复制到剪贴板，且类似于以下内容。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。
```
```
**获取视觉对象嵌入代码**
1. 在 Amazon Quick Sight 中打开已发布的控制面板，然后选择要嵌入的视觉效果。然后打开视觉对象右上角的视觉对象菜单，从中选择**嵌入视觉对象**。
1. 在打开的**嵌入视觉对象**窗格中，选择**复制代码**。
嵌入代码已复制到剪贴板，且类似于以下内容。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。
```
```
## 步骤 4：将嵌入代码粘贴到 HTML 页面、wiki 页面或门户中
要将嵌入代码粘贴到 HTML 页面、wiki 页面或门户中，请按照以下过程操作。
**粘贴嵌入代码**
+ 打开要嵌入视觉对象或控制面板的位置的 HTML 代码，然后将嵌入代码粘贴到其中。
以下示例演示了嵌入式控制面板的大致样式。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。
```
Example.com - Employee Portal
Current shipment stats
```
以下示例演示了嵌入式视觉对象的大致样式。此示例`quicksightdomain`中的是您用来访问您的 Amazon Quick Sight 账户的网址。
```
Example.com - Employee Portal
Current shipment stats
```
如果面向公众的应用程序是基于 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
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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
使用以下主题了解如何使用 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 快速浏览控制面板
**重要**
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：设置权限
在下节中，您可以了解如何设置后端应用程序或 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
在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入控制面板 URL。如果您计划为 IAM 或 Amazon Quick Sight 身份类型嵌入控制面板，请与用户共享控制面板。
用户访问您的应用程序时，该应用程序代表用户代入 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.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 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
```
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
```
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
以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 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
以下示例演示了可以在应用程序服务器上使用以生成嵌入式控制面板 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
要代入该角色，请选择以下 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
在下一节中，您可以了解如何使用 [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
```
Dashboard Embedding Example
```
### SDK 1.0
```
Basic Embed
```
要使此示例起作用，请务必使用 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 控制面板
**重要**
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：设置权限
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：Amazon Quick 开发者 |
在下节中，您可以了解如何代表匿名访问者进行身份验证，并获取应用程序服务器上的可嵌入控制面板 URL。
用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，它会将该用户添加到 Amazon Quick Sight（如果该用户尚不存在）。接下来，其会将标识符作为唯一角色会话 ID 进行传递。
以下示例展示了代表用户执行 IAM 身份验证。将标识符作为唯一角色会话 ID 进行传递。此代码在您的应用程序服务器上运行。
### Java
```
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 authorizedResourceArns, // DASHBOARD ARN LIST TO EMBED
final List allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
final List 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
```
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
```
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
以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 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
以下示例演示了可以在应用程序服务器上使用以生成嵌入式控制面板 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
要代入该角色，请选择以下 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
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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
```
Dashboard Embedding Example
```
### SDK 1.0
```
Basic Embed
```
要使此示例起作用，请务必使用 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
```
# 在嵌入式控制面板中启用执行摘要
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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
您可以使用 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 视觉效果
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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：设置权限
在下节中，您可以了解如何设置后端应用程序或 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
在下一节中，您可以了解如何对您的 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
```
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 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
```
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
```
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
以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 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
以下示例演示了可以在应用程序服务器上使用以生成嵌入式控制面板 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
要代入该角色，请选择以下 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
在下一节中，您可以了解如何使用 [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
```
Visual Embedding Example
```
### SDK 1.0
```
Visual Embedding Example
```
要使此示例起作用，请务必使用 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 视觉效果
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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：设置权限
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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.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 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 allowedDomains, // Runtime allowed domains for embedding
final List 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
```
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
```
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
以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 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
以下示例演示了可以在应用程序服务器上使用以生成嵌入式控制面板 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
要代入该角色，请选择以下 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
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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
```
Visual Embedding Example
```
### SDK 1.0
```
Visual Embedding Example
```
要使此示例起作用，请务必使用 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 控制台的全部功能
**重要**
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：设置权限
在下节中，您可以了解如何设置后端应用程序或 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
在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入控制台会话 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.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 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
```
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
```
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
以下示例显示了可以在应用服务器上使用的 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
以下示例演示了可以在应用服务器上使用以生成嵌入式控制台会话 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
要代入该角色，请选择以下 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
在下一节中，您可以了解如何使用 [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
```
Console Embedding Example
```
### SDK 1.0
```
QuickSight Console Embedding
```
要使此示例起作用，请务必使用 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 功能
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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
| |
| --- |
| 目标受众：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 生成问答体验中
在以下各节中，您可以找到有关如何为 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：设置权限
在以下部分中，您可以了解如何设置后端应用程序或 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
在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入 Q 主题 URL。如果您计划为 IAM 或 Amazon Quick Sight 身份类型嵌入生成式问答体验，请与用户分享 Q 主题。
用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，如果该用户尚不存在，则该应用程序会将该用户添加到 Amazon Quick Sight。接下来，其会将标识符作为唯一角色会话 ID 进行传递。
执行上述步骤可确保在 Amazon Quick Sight 中对 Q 主题的每个查看者进行唯一配置。它还实施每个用户的设置，例如，行级别安全性和参数的动态默认值。基于标签的行级别安全性可用于匿名用户嵌入 Q 栏。
以下示例展示了代表用户执行 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.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 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
**注意**
APIs 不能直接从浏览器调用嵌入网址生成。请改为参考 Node.JS 示例。
#### Python3
```
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
以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 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
以下示例演示了可以在应用程序服务器上使用以生成嵌入式 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
要代入该角色，请选择以下 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
在以下部分中，您可以了解如何将生成式问答体验嵌入网站或应用程序页面。你可以使用 [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
```
Generative Q&A Embedding Example
```
要使此示例起作用，请务必使用 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
```
### 可选的嵌入生成式问答体验功能
以下可选功能可用于使用 Embedding SDK 的嵌入生成式问答体验。
#### 调用生成式问答搜索栏操作
+ 设置问题 — 此功能将问题发送到生成式问答体验并立即查询问题。
```
embeddedGenerativeQnExperience.setQuestion('show me monthly revenue');
```
+ 关闭答案面板（适用于生成式问答搜索栏选项）— 此功能将关闭答案面板并将 iframe 返回到原始搜索栏状态。
```
embeddedGenerativeQnExperience.close();
```
有关更多信息，请参阅 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。
## 将 Amazon Q 嵌入匿名（未注册）用户的快速生成问答体验中
| |
| --- |
| 目标受众：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：设置权限
在以下部分中，您可以了解如何设置后端应用程序或 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
在下节中，您可以了解如何对用户进行身份验证，并获取应用程序服务器上的可嵌入 Q 主题 URL。
用户访问您的应用程序时，该应用程序代表用户代入 IAM 角色。然后，如果该用户尚不存在，则该应用程序会将该用户添加到 Amazon Quick Sight。接下来，其会将标识符作为唯一角色会话 ID 进行传递。
#### Java
```
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 authorizedResourceArns, // Q TOPIC ARN LIST TO EMBED
final List allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
final List 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
**注意**
APIs 不能直接从浏览器调用嵌入网址生成。请改为参考 Node.JS 示例。
#### Python3
```
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
以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 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
以下示例演示了可以在应用程序服务器上使用以生成嵌入式 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
要代入该角色，请选择以下 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
在以下部分中，您可以了解如何将生成式问答体验嵌入网站或应用程序页面。你可以使用 [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
```
Generative Q&A Embedding Example
```
要使此示例起作用，请务必使用 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
```
### 可选的嵌入生成式问答体验功能
以下可选功能可用于使用 Embedding SDK 的嵌入生成式问答体验。
#### 调用生成式问答搜索栏操作
+ 设置问题 — 此功能将问题发送到生成式问答体验并立即查询问题。
```
embeddedGenerativeQnExperience.setQuestion('show me monthly revenue');
```
+ 关闭答案面板（适用于生成式问答搜索栏选项）— 此功能将关闭答案面板并将 iframe 返回到原始搜索栏状态。
```
embeddedGenerativeQnExperience.close();
```
有关更多信息，请参阅 [Amazon Quick Sight 嵌入软件开发工具包](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。
# 嵌入 Amazon Quick Sight Q 搜索栏（经典版）
| |
| --- |
| 目标受众：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 搜索栏
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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：设置权限
**注意**
嵌入式的 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
**注意**
嵌入式的 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
```
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 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
```
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
```
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
以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 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
以下示例演示了可以在应用程序服务器上使用以生成嵌入式 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
要代入该角色，请选择以下 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
**注意**
嵌入式的 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
```
Q Search Bar Embedding Example
```
### SDK 1.0
```
QuickSight Q Search Bar Embedding
```
要使此示例起作用，请务必使用 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 搜索栏嵌入功能
**注意**
嵌入式的 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 搜索栏操作
以下选项仅支持嵌入 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 搜索栏
| |
| --- |
| 目标受众：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：设置权限
**注意**
嵌入式的 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
**注意**
嵌入式的 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
```
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 authorizedResourceArns, // Q SEARCHBAR TOPIC ARN LIST TO EMBED
final List allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
final List 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
```
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
```
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
以下示例显示了可以在应用服务器上用来生成嵌入式仪表板的 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
以下示例演示了可以在应用程序服务器上使用以生成嵌入式 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
要代入该角色，请选择以下 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
**注意**
嵌入式的 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
```
Q Search Bar Embedding Example
```
### SDK 1.0
```
QuickSight Q Search Bar Embedding
```
要使此示例起作用，请务必使用 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 搜索栏嵌入功能
**注意**
嵌入式的 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 搜索栏操作
以下选项仅支持嵌入 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 操作嵌入分析
| |
| --- |
| 适用于：企业版 |
| |
| --- |
| 目标受众：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）为所有人嵌入控制面板
**重要**
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：设置权限
**重要**
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
**重要**
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
**重要**
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。此代码位于您的应用程序服务器上。
```
Basic Embed
```
要使此示例起作用，请务必使用 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）为注册用户嵌入控制面板
**重要**
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：设置权限
**重要**
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
**重要**
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
**重要**
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。此代码在您的应用程序服务器上生成。
```
Basic Embed
```
要使此示例起作用，请务必使用 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 控制台
**重要**
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：设置权限
**重要**
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
**重要**
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
**重要**
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。此代码在您的应用程序服务器上生成。
```
Basic Embed
```
要使此示例起作用，请务必使用 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
```