本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
将亚马逊 Q 嵌入亚马逊 Quick Sight Generative Q & A 体验中
| 目标受众:亚马逊 Quick 开发者 |
在以下部分中,您可以找到有关如何设置使用由 LLM 提供支持的增强 NLQ 功能的嵌入式生成问答体验的详细信息。生成式问答体验是嵌入式 Q 搜索栏的推荐替代品,并为用户提供更新的 BI 体验。
主题
将亚马逊 Q 嵌入亚马逊 Quick Sight Generative Q & A 体验中,为注册用户提供体验
在以下部分中,您可以找到有关如何为亚马逊 Quick Sight 的注册用户设置嵌入式生成式问答体验的详细信息。
步骤 1:设置权限
在以下部分中,您可以了解如何设置后端应用程序或 Web 服务器的权限来嵌入生成式问答体验。此任务需要对 Amazon Identity and Access Management (IAM) 的管理访问权限。
每位访问生成式问答体验的用户都将扮演一个赋予他们 Amazon Quick Sight 访问权限和权限的角色。要实现该目的,请在您的 Amazon Web Services 账户中创建一个 IAM 角色。将一个 IAM 策略与该角色相关联,以便为担任该角色的任何用户提供权限。IAM 角色需要提供权限才能检索特定用户群体的嵌入 URL。
借助通配符 *,您可以授予为特定命名空间中的所有用户生成 URL 的权限。您也可以授予为特定命名空间中的一部分用户生成 URL 的权限。为此,请添加 quicksight:GenerateEmbedUrlForRegisteredUser。
您可以在 IAM 策略中创建一个条件,限制开发人员可以在 GenerateEmbedUrlForRegisteredUser API 操作的 AllowedDomains 参数中列出的域。AllowedDomains 参数是可选参数。它允许开发人员选择覆盖在 M anage Amazon Quick Sight 菜单中配置的静态域,改为列出最多三个可以访问生成的 URL 的域名或子域名。然后,此 URL 会嵌入开发人员的网站。只有参数中列出的域才能访问嵌入生成式问答体验。如果没有此条件,开发人员可以在 AllowedDomains 参数中列出互联网上的任何域。
要限制开发人员可用于此参数的域,请在 IAM 策略中添加一个 AllowedEmbeddingDomains 条件。有关该AllowedDomains参数的更多信息,请参阅亚马逊 Quick Sight API 参考GenerateEmbedUrlForRegisteredUser中的内容。
配置不当的 IAM 条件运算符可能允许通过 URL 变体在未经授权的情况下访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用quicksight:AllowedEmbeddingDomains条件密钥时,请使用条件运算符,这些运算符要么允许特定域,要么拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息,请参阅 IAM 用户指南中的 IAM JSON 策略元素:条件运算符。
许多不同的 URL 变体可以指向相同的资源。例如,以下 URL 都解析为相同的内容:
https://example.comhttps://example.com/https://Example.com
如果您的策略使用的运算符不考虑这些 URL 变体,则攻击者可以通过提供等效的 URL 变体来绕过您的限制。
您必须验证您的 IAM 策略是否使用适当的条件运算符来防止绕过漏洞,并确保只有您的目标域才能访问您的嵌入式资源。
以下示例策略提供了这些权限。
此外,如果您创建的初次用户将成为亚马逊 Quick Sight 的读者,请务必在政策中添加quicksight:RegisterUser权限。
以下示例策略为即将成为亚马逊 Quick Sight 读者的首次用户提供了检索嵌入网址的权限。
最后,您应用程序的 IAM 身份必须具有关联的信任策略,才允许访问您刚创建的角色。这意味着,当用户访问您的应用程序时,您的应用程序可以代表用户代入该角色并在 Amazon Quick Sight 中为用户进行配置。
下面演示了一个示例信任策略。
有关 OpenID Connect 或安全断言标记语言(SAML)身份验证的信任策略的更多信息,请参阅《IAM 用户指南》的以下章节:
步骤 2:生成附带身份验证代码的 URL
在下节中,您可以了解如何对用户进行身份验证,并获取应用程序服务器上的可嵌入 Q 主题 URL。如果您计划为 IAM 或 Amazon Quick Sight 身份类型嵌入生成式问答体验,请与用户分享问答主题。
用户访问您的应用程序时,该应用程序代表用户代入 IAM 角色。然后,如果该用户尚不存在,则该应用程序将该用户添加到亚马逊 Quick Sight 中。接下来,其会将标识符作为唯一角色会话 ID 进行传递。
执行上述步骤可确保 Q 主题的每位查看者都在 Amazon Quick Sight 中获得唯一的配置。它还强制执行每个用户的设置,例如行级安全性和参数的动态默认值。 Tag-based 行级安全性可用于匿名用户嵌入 Q 栏。
以下示例展示了代表用户执行 IAM 身份验证。此代码在您的应用程序服务器上运行。
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 Amazon 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, // Amazon Account ID final String topicId, // Topic ID to embed final List<String> allowedDomains, // Runtime allowed domain for embedding final String userArn // Registered user arn to use for embedding. Refer to Get Embed Url section in developer portal to find how to get user arn for a QuickSight user. ) throws Exception { final RegisteredUserEmbeddingExperienceConfiguration experienceConfiguration = new RegisteredUserEmbeddingExperienceConfiguration() .withGenerativeQnA(new RegisteredUserGenerativeQnAEmbeddingConfiguration().withInitialTopicId(topicId)); final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest = new GenerateEmbedUrlForRegisteredUserRequest(); generateEmbedUrlForRegisteredUserRequest.setAwsAccountId(accountId); generateEmbedUrlForRegisteredUserRequest.setUserArn(userArn); generateEmbedUrlForRegisteredUserRequest.setAllowedDomains(allowedDomains); generateEmbedUrlForRegisteredUserRequest.setExperienceConfiguration(experienceConfiguration); final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest); return generateEmbedUrlForRegisteredUserResult.getEmbedUrl(); } }
嵌入式 URL 生成 API 不能直接从浏览器调用。请改为参考 Node.JS 示例。
import json import boto3 from botocore.exceptions import ClientError sts = boto3.client('sts') # Function to generate embedded URL # accountId: Amazon 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)
以下示例显示了可在应用服务器上使用的 JavaScript (Node.js) 为嵌入式仪表板生成 URL。您可以在网站或应用程序中使用该 URL 以显示控制面板。
例
const Amazon = 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# 代码可以在应用服务器上用于生成嵌入式 Q 搜索栏的 URL。您可以在网站或应用程序中使用此 URL 以显示 Q 搜索栏。
例
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); } } } }
要代入该角色,请选择以下 Amazon Security Token Service (Amazon STS) API 操作之一:
-
AssumeRole— 当您使用 IAM 身份代入角色时,请使用此操作。
-
AssumeRoleWithWebIdentity— 当您使用 Web 身份提供商对用户进行身份验证时,请使用此操作。
-
AssumeRoleWithSaml— 当您使用 SAML 对用户进行身份验证时,请使用此操作。
以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 quicksight:GenerateEmbedUrlForRegisteredUser 启用权限。如果您在用户在 Q 搜索栏中使用主题时采用即时方法添加用户,则该角色还需要为 quicksight:RegisterUser 启用权限。
aws sts assume-role \ --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_generative_qna_role" \ --role-session-namejohn.doe@example.com
assume-role 操作返回三个输出参数:访问密钥、私有密钥和会话令牌。
如果在调用 AssumeRole 操作时遇到 ExpiredToken 错误,可能是因为之前的 SESSION TOKEN 仍在环境变量中。通过设置以下变量可以解决这一问题:
-
AWS_ACCESS_KEY_ID
-
AWS_SECRET_ACCESS_KEY
-
AWS_SESSION_TOKEN
以下示例说明了如何在 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 可以确保为每个用户设置相应的权限。此外,它还能避免任何用户访问限制。限制是一项安全功能,可防止同一个用户从多个位置访问亚马逊 Quick Sight。
角色会话 ID 也成为亚马逊 Quick Sight 中的用户名。您可以使用这种模式提前在 Amazon Quick Sight 中预置用户,也可以在用户首次访问生成式问答体验时为他们进行预配置。
以下示例显示了可用于预置用户的 CLI 命令。有关RegisterUser和其他 Amazon Quick Sight API 操作的更多信息,请参阅亚马逊 Quick Sight API 参考。 DescribeUser
aws quicksight register-user \ --aws-account-id111122223333\ --namespacedefault\ --identity-typeIAM\ --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_generative_qna_role" \ --user-roleREADER\ --user-namejhnd\ --session-name "john.doe@example.com" \ --emailjohn.doe@example.com\ --regionus-east-1\ --custom-permissions-nameTeamA1
如果用户通过 Microsoft AD 进行身份验证,则无需使用 RegisterUser 进行设置。取而代之的是,他们应该在首次访问亚马逊Quick Sight时自动订阅。对于 Microsoft AD 用户,您可以使用 DescribeUser 获取用户 Amazon 资源名称(ARN)。
用户首次访问 Amazon Quick Sight 时,您还可以将该用户添加到与之共享仪表板的群组中。以下示例显示了将用户添加到组的 CLI 命令。
aws quicksight create-group-membership \ --aws-account-id111122223333\ --namespacedefault\ --group-namefinanceusers\ --member-name "embedding_quicksight_q_generative_qna_role/john.doe@example.com"
现在,您的应用程序的用户也是亚马逊 Quick Sight 的用户,并且可以访问控制面板。
最后,要获取控制面板的签名 URL,请从应用程序服务器中调用 generate-embed-url-for-registered-user。这会返回可嵌入的控制面板 URL。以下示例显示如何使用服务器端调用为通过身份验证 Amazon Managed Microsoft AD 或单点登录(IAM 身份中心)的用户生成嵌入式仪表板的 URL。
aws quicksight generate-embed-url-for-anonymous-user \ --aws-account-id111122223333\ --namespacedefault-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-minutes15
有关使用此操作的更多信息,请参阅 GenerateEmbedUrlForRegisteredUser。您可以在自己的代码中使用该 API 操作和其他操作。
第 3 步:嵌入 Generative Q & A 体验 URL
在以下部分中,您可以了解如何将生成式问答体验嵌入网站或应用程序页面。您可以使用亚马逊 Quick Sight 嵌入 SDK
-
将生成式问答体验放置到 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" }
使用亚马逊 Quick Sight 嵌入软件开发工具包
确保托管嵌入式生成式问答体验的域名在允许列表中,即允许订阅亚马逊 Quick Sight 的域名列表。这一要求可阻止未经批准的域托管嵌入式控制面板,从而保护您的数据。有关为嵌入生成式问答体验添加域的更多信息,请参阅 管理域名。
您可以使用亚马逊 Quick Sight 嵌入式软件开发工具包自定义嵌入式生成式问答体验的布局和外观,以适应您的应用程序。使用 panelType 属性配置生成式问答体验在您的应用程序中呈现时的着陆状态。将 panelType 属性设置为 'FULL' 以呈现完整的生成式问答体验面板。该面板类似于亚马逊 Quick Sight 用户在亚马逊 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属性后,使用亚马逊 Quick Sight 嵌入软件开发工具包自定义生成式问答体验的以下属性。
-
生成式问答面板的标题(仅适用于
panelType: FULL选项)。 -
搜索栏的占位符文本。
-
是否允许选择主题。
-
主题名称是显示还是隐藏。
-
Amazon Q 图标是显示还是隐藏(仅适用于
panelType: FULL选项)。 -
Pinboard 是显示还是隐藏。
-
用户是否可以将生成式问答面板最大化为全屏显示。
-
生成式问答面板的主题。可以在 SDK 中传递自定义主题 ARN 来更改框架内容的外观。嵌入式生成式商业智能面板不支持亚马逊 Quick Sight 入门主题。要使用亚马逊 Quick Sight 入门主题,请将其另存为亚马逊 Quick Sight 中的自定义主题。
当您使用亚马逊 Quick Sight 嵌入软件开发工具包时,页面上的生成式问答体验会根据状态动态调整大小。通过使用 Amazon Quick Sight Embedding SDK,您还可以控制生成式问答体验中的参数,并接收有关页面加载完成、状态更改和错误的回传。
以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。
<!DOCTYPE html> <html> <head> <title>Generative Q&A Embedding Example</title> <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.7.0/dist/quicksight-embedding-js-sdk.min.js"></script> <script type="text/javascript"> const embedGenerativeQnA = async() => { const {createEmbeddingContext} = QuickSightEmbedding; const embeddingContext = await createEmbeddingContext({ onChange: (changeEvent, metadata) => { console.log('Context received a change', changeEvent, metadata); }, }); const frameOptions = { url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API container: '#experience-container', height: "700px", width: "1000px", onChange: (changeEvent, metadata) => { switch (changeEvent.eventName) { case 'FRAME_MOUNTED': { console.log("Do something when the experience frame is mounted."); break; } case 'FRAME_LOADED': { console.log("Do something when the experience frame is loaded."); break; } } }, }; const contentOptions = { // Optional panel settings. Default behavior is equivalent to {panelType: 'FULL'} panelOptions: { panelType: 'FULL', title: 'custom title', // Optional showQIcon: false, // Optional, Default: true }, // Use SEARCH_BAR panel type for the landing state to be similar to embedQSearchBar // with generative capability enabled topics /* panelOptions: { panelType: 'SEARCH_BAR', focusedHeight: '250px', expandedHeight: '500px', }, */ showTopicName: false, // Optional, Default: true showPinboard: false, // Optional, Default: true allowTopicSelection: false, // Optional, Default: true allowFullscreen: false, // Optional, Default: true searchPlaceholderText: "custom search placeholder", // Optional themeOptions: { // Optional themeArn: 'arn:aws:quicksight:<Region>:<AWS-Account-ID>:theme/<Theme-ID>' } onMessage: async (messageEvent, experienceMetadata) => { switch (messageEvent.eventName) { case 'Q_SEARCH_OPENED': { // called when pinboard is shown / visuals are rendered console.log("Do something when SEARCH_BAR type panel is expanded"); break; } case 'Q_SEARCH_FOCUSED': { // called when question suggestions or topic selection dropdown are shown console.log("Do something when SEARCH_BAR type panel is focused"); break; } case 'Q_SEARCH_CLOSED': { // called when shrinked to initial bar height console.log("Do something when SEARCH_BAR type panel is collapsed"); break; } case 'Q_PANEL_ENTERED_FULLSCREEN': { console.log("Do something when panel enters full screen mode"); break; } case 'Q_PANEL_EXITED_FULLSCREEN': { console.log("Do something when panel exits full screen mode"); break; } case 'CONTENT_LOADED': { console.log("Do something after experience is loaded"); break; } case 'ERROR_OCCURRED': { console.log("Do something when experience fails to load"); break; } } } }; const embeddedGenerativeQnExperience = await embeddingContext.embedGenerativeQnA(frameOptions, contentOptions); }; </script> </head> <body onload="embedGenerativeQnA()"> <div id="experience-container"></div> </body> </html>
要使此示例起作用,请务必使用亚马逊 Quick Sight 嵌入式软件开发工具包在您的网站上加载嵌入式生成式问答体验。 JavaScript要获取副本,请执行下列操作之一:
-
从下载
亚马逊 Quick Sight 嵌入软件开发工具包 GitHub。该存储库由一群亚马逊 Quick Sight 开发人员维护。 -
从下载最新的嵌入式 SDK 版本https://www.npmjs.com/package/amazon-quicksight-embedding-sdk
。 -
如果您使用
npmJavaScript 依赖关系,请通过运行以下命令下载并安装它。npm install amazon-quicksight-embedding-sdk
可选的嵌入式 Generative Q & A 体验功能
以下可选功能可用于使用 Embedding SDK 的嵌入生成式问答体验。
调用 Generative Q & A 搜索栏操作
-
设置问题 — 此功能将问题发送到生成式问答体验并立即查询问题。
embeddedGenerativeQnExperience.setQuestion('show me monthly revenue'); -
关闭答案面板(适用于生成式问答搜索栏选项)— 此功能将关闭答案面板并将 iframe 返回到原始搜索栏状态。
embeddedGenerativeQnExperience.close();
有关更多信息,请参阅亚马逊 Quick Sight 嵌入软件开发工具包
将亚马逊 Q 嵌入匿名(未注册)用户的 Quick Generative Q & A 体验中
| 目标受众:亚马逊 Quick 开发者 |
在以下部分中,您可以了解有关如何为匿名(未注册)用户设置嵌入生成式问答体验的详细信息。
步骤 1:设置权限
在以下部分中,您可以了解如何设置后端应用程序或 Web 服务器的权限来嵌入生成式问答体验。此任务需要对 Amazon Identity and Access Management (IAM) 的管理访问权限。
每位访问生成式问答体验的用户都将扮演一个赋予他们 Amazon Quick Sight 访问权限和权限的角色。要实现该目的,请在您的 Amazon Web Services 账户中创建一个 IAM 角色。将一个 IAM 策略与该角色相关联,以便为担任该角色的任何用户提供权限。IAM 角色需要提供权限才能检索特定用户群体的嵌入 URL。
借助通配符 *,您可以授予为特定命名空间中的所有用户生成 URL 的权限。您也可以授予为特定命名空间中的一部分用户生成 URL 的权限。为此,请添加 quicksight:GenerateEmbedUrlForAnonymousUser。
您可以在 IAM 策略中创建一个条件,限制开发人员可以在 GenerateEmbedUrlForAnonymousUser API 操作的 AllowedDomains 参数中列出的域。AllowedDomains 参数是可选参数。它允许开发人员选择覆盖在 M anage Amazon Quick Sight 菜单中配置的静态域,改为列出最多三个可以访问生成的 URL 的域名或子域名。然后,此 URL 会嵌入开发人员的网站。只有参数中列出的域才能访问嵌入式 Q 搜索栏。如果没有此条件,开发人员可以在 AllowedDomains 参数中列出互联网上的任何域。
要限制开发人员可用于此参数的域,请在 IAM 策略中添加一个 AllowedEmbeddingDomains 条件。有关该AllowedDomains参数的更多信息,请参阅亚马逊 Quick Sight API 参考GenerateEmbedUrlForAnonymousUser中的内容。
配置不当的 IAM 条件运算符可能允许通过 URL 变体在未经授权的情况下访问您的嵌入式 Quick 资源。在您的 IAM 策略中使用quicksight:AllowedEmbeddingDomains条件密钥时,请使用条件运算符,这些运算符要么允许特定域,要么拒绝所有未特别允许的域。有关 IAM 条件运算符的更多信息,请参阅 IAM 用户指南中的 IAM JSON 策略元素:条件运算符。
许多不同的 URL 变体可以指向相同的资源。例如,以下 URL 都解析为相同的内容:
https://example.comhttps://example.com/https://Example.com
如果您的策略使用的运算符不考虑这些 URL 变体,则攻击者可以通过提供等效的 URL 变体来绕过您的限制。
您必须验证您的 IAM 策略是否使用适当的条件运算符来防止绕过漏洞,并确保只有您的目标域才能访问您的嵌入式资源。
您应用程序的 IAM 身份必须具有关联的信任策略,才允许访问您刚创建的角色。这意味着,在用户访问您的应用程序时,您的应用程序可以代表用户代入该角色,以加载生成式问答体验。下面演示了一个示例信任策略。
有关信任策略的更多信息,请参阅《IAM 用户指南》中的 IAM 临时安全凭证
步骤 2:生成附带身份验证代码的 URL
在下节中,您可以了解如何对用户进行身份验证,并获取应用程序服务器上的可嵌入 Q 主题 URL。
用户访问您的应用程序时,该应用程序代表用户代入 IAM 角色。然后,如果该用户尚不存在,则该应用程序将该用户添加到亚马逊 Quick Sight 中。接下来,其会将标识符作为唯一角色会话 ID 进行传递。
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 Amazon 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 Amazon ACCOUNT ID final String initialTopicId, // Q TOPIC ID TO WHICH THE CONSTRUCTED URL POINTS AND EXPERIENCE PREPOPULATES INITIALLY final String namespace, // ANONYMOUS EMBEDDING REQUIRES SPECIFYING A VALID NAMESPACE FOR WHICH YOU WANT THE EMBEDDING URL final List<String> authorizedResourceArns, // Q TOPIC ARN LIST TO EMBED final List<String> allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING final List<SessionTag> sessionTags // SESSION TAGS USED FOR ROW-LEVEL SECURITY ) throws Exception { AnonymousUserEmbeddingExperienceConfiguration experienceConfiguration = new AnonymousUserEmbeddingExperienceConfiguration(); AnonymousUserGenerativeQnAEmbeddingConfiguration generativeQnAConfiguration = new AnonymousUserGenerativeQnAEmbeddingConfiguration(); generativeQnAConfiguration.setInitialTopicId(initialTopicId); experienceConfiguration.setGenerativeQnA(generativeQnAConfiguration); GenerateEmbedUrlForAnonymousUserRequest generateEmbedUrlForAnonymousUserRequest = new GenerateEmbedUrlForAnonymousUserRequest() .withAwsAccountId(accountId) .withNamespace(namespace) .withAuthorizedResourceArns(authorizedResourceArns) .withExperienceConfiguration(experienceConfiguration) .withSessionTags(sessionTags) .withSessionLifetimeInMinutes(600L); // OPTIONAL: VALUE CAN BE [15-600]. DEFAULT: 600 .withAllowedDomains(allowedDomains); GenerateEmbedUrlForAnonymousUserResult result = quickSightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserRequest); return result.getEmbedUrl(); } }
嵌入式 URL 生成 API 不能直接从浏览器调用。请改为参考 Node.JS 示例。
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 Amazon 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)
以下示例显示了可在应用服务器上使用的 JavaScript (Node.js) 为嵌入式仪表板生成 URL。您可以在网站或应用程序中使用该 URL 以显示控制面板。
例
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# 代码可以在应用服务器上用于生成嵌入式 Q 搜索栏的 URL。您可以在网站或应用程序中使用此 URL 以显示 Q 搜索栏。
例
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); } } } }
要代入该角色,请选择以下 Amazon Security Token Service (Amazon STS) API 操作之一:
-
AssumeRole— 当您使用 IAM 身份代入角色时,请使用此操作。
-
AssumeRoleWithWebIdentity— 当您使用 Web 身份提供商对用户进行身份验证时,请使用此操作。
-
AssumeRoleWithSaml— 当您使用 SAML 对用户进行身份验证时,请使用此操作。
以下示例显示了用于设置 IAM 角色的 CLI 命令。该角色需要为 quicksight:GenerateEmbedUrlForAnonymousUser 启用权限。
aws sts assume-role \ --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_generative_qna_role" \ --role-session-nameanonymous caller
assume-role 操作返回三个输出参数:访问密钥、私有密钥和会话令牌。
如果在调用 AssumeRole 操作时遇到 ExpiredToken 错误,可能是因为之前的 SESSION TOKEN 仍在环境变量中。通过设置以下变量可以解决这一问题:
-
AWS_ACCESS_KEY_ID
-
AWS_SECRET_ACCESS_KEY
-
AWS_SESSION_TOKEN
以下示例说明了如何在 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 可以确保为每个用户设置相应的权限。此外,它还能避免任何用户访问限制。限制是一项安全功能,可防止同一个用户从多个位置访问亚马逊 Quick Sight。它还能使每个会话保持独立和独特。如果您使用一组 Web 服务器(例如用于负载平衡),并且会话重新连接到其他服务器,则会开始新的会话。
要获取控制面板的签名 URL,请从应用程序服务器中调用 generate-embed-url-for-anynymous-user。这会返回可嵌入的控制面板 URL。以下示例演示了如何使用服务器端调用为匿名访问您 Web 门户或应用程序的用户生成嵌入式控制面板的 URL。
aws quicksight generate-embed-url-for-anonymous-user \ --aws-account-id111122223333\ --namespacedefault-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-minutes15
有关使用此操作的更多信息,请参阅 GenerateEmbedUrlForAnonymousUser。您可以在自己的代码中使用该 API 操作和其他操作。
第 3 步:嵌入 Generative Q & A 体验 URL
在以下部分中,您可以了解如何将生成式问答体验嵌入网站或应用程序页面。您可以使用亚马逊 Quick Sight 嵌入 SDK
-
将生成式问答体验放置到 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" }
使用亚马逊 Quick Sight 嵌入软件开发工具包
确保举办生成式问答体验的域名在允许列表中,即您的亚马逊 Quick Sight 订阅的批准域名列表。此要求可阻止未经批准的域托管嵌入生成式问答体验,从而保护您的数据。有关为嵌入生成式问答体验添加域的更多信息,请参阅 管理域名。
您可以使用亚马逊 Quick Sight 嵌入式软件开发工具包自定义嵌入式生成式问答体验的布局和外观,以适应您的应用程序。使用 panelType 属性配置生成式问答体验在您的应用程序中呈现时的着陆状态。将 panelType 属性设置为 'FULL' 以呈现完整的生成式问答体验面板。该面板类似于亚马逊 Quick Sight 用户在亚马逊 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属性后,使用亚马逊 Quick Sight 嵌入软件开发工具包自定义生成式问答体验的以下属性。
-
生成式问答面板的标题(仅适用于
panelType: FULL选项)。 -
搜索栏的占位符文本。
-
是否允许选择主题。
-
主题名称是显示还是隐藏。
-
Amazon Q 图标是显示还是隐藏(仅适用于
panelType: FULL选项)。 -
Pinboard 是显示还是隐藏。
-
用户是否可以将生成式问答面板最大化为全屏显示。
-
生成式问答面板的主题。可以在 SDK 中传递自定义主题 ARN 来更改框架内容的外观。嵌入式生成式商业智能面板不支持亚马逊 Quick Sight 入门主题。要使用亚马逊 Quick Sight 入门主题,请将其另存为亚马逊 Quick Sight 中的自定义主题。
当您使用亚马逊 Quick Sight 嵌入软件开发工具包时,页面上的生成式问答体验会根据状态动态调整大小。借助 Amazon Quick Sight Embedding SDK,您还可以控制生成式问答体验中的参数,并接收有关页面加载完成、状态更改和错误的回传。
以下示例演示了如何使用生成的 URL。此代码在您的应用程序服务器上生成。
<!DOCTYPE html> <html> <head> <title>Generative Q&A Embedding Example</title> <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.7.0/dist/quicksight-embedding-js-sdk.min.js"></script> <script type="text/javascript"> const embedGenerativeQnA = async() => { const {createEmbeddingContext} = QuickSightEmbedding; const embeddingContext = await createEmbeddingContext({ onChange: (changeEvent, metadata) => { console.log('Context received a change', changeEvent, metadata); }, }); const frameOptions = { url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API container: '#experience-container', height: "700px", width: "1000px", onChange: (changeEvent, metadata) => { switch (changeEvent.eventName) { case 'FRAME_MOUNTED': { console.log("Do something when the experience frame is mounted."); break; } case 'FRAME_LOADED': { console.log("Do something when the experience frame is loaded."); break; } } }, }; const contentOptions = { // Optional panel settings. Default behavior is equivalent to {panelType: 'FULL'} panelOptions: { panelType: 'FULL', title: 'custom title', // Optional showQIcon: false, // Optional, Default: true }, // Use SEARCH_BAR panel type for the landing state to be similar to embedQSearchBar // with generative capability enabled topics /* panelOptions: { panelType: 'SEARCH_BAR', focusedHeight: '250px', expandedHeight: '500px', }, */ showTopicName: false, // Optional, Default: true showPinboard: false, // Optional, Default: true allowTopicSelection: false, // Optional, Default: true allowFullscreen: false, // Optional, Default: true searchPlaceholderText: "custom search placeholder", // Optional themeOptions: { // Optional themeArn: 'arn:aws:quicksight:<Region>:<Amazon-Account-ID>:theme/<Theme-ID>' } onMessage: async (messageEvent, experienceMetadata) => { switch (messageEvent.eventName) { case 'Q_SEARCH_OPENED': { // called when pinboard is shown / visuals are rendered console.log("Do something when SEARCH_BAR type panel is expanded"); break; } case 'Q_SEARCH_FOCUSED': { // called when question suggestions or topic selection dropdown are shown console.log("Do something when SEARCH_BAR type panel is focused"); break; } case 'Q_SEARCH_CLOSED': { // called when shrinked to initial bar height console.log("Do something when SEARCH_BAR type panel is collapsed"); break; } case 'Q_PANEL_ENTERED_FULLSCREEN': { console.log("Do something when panel enters full screen mode"); break; } case 'Q_PANEL_EXITED_FULLSCREEN': { console.log("Do something when panel exits full screen mode"); break; } case 'CONTENT_LOADED': { console.log("Do something after experience is loaded"); break; } case 'ERROR_OCCURRED': { console.log("Do something when experience fails to load"); break; } } } }; const embeddedGenerativeQnExperience = await embeddingContext.embedGenerativeQnA(frameOptions, contentOptions); }; </script> </head> <body onload="embedGenerativeQnA()"> <div id="experience-container"></div> </body> </html>
要使此示例起作用,请务必使用亚马逊 Quick Sight 嵌入式软件开发工具包在您的网站上加载嵌入式生成式问答体验。 JavaScript要获取副本,请执行下列操作之一:
-
从下载
亚马逊 Quick Sight 嵌入软件开发工具包 GitHub。该存储库由一群亚马逊 Quick Sight 开发人员维护。 -
从下载最新的嵌入式 SDK 版本https://www.npmjs.com/package/amazon-quicksight-embedding-sdk
。 -
如果您使用
npmJavaScript 依赖关系,请通过运行以下命令下载并安装它。npm install amazon-quicksight-embedding-sdk
可选的嵌入式 Generative Q & A 体验功能
以下可选功能可用于使用 Embedding SDK 的嵌入生成式问答体验。
调用 Generative Q & A 搜索栏操作
-
设置问题 — 此功能将问题发送到生成式问答体验并立即查询问题。
embeddedGenerativeQnExperience.setQuestion('show me monthly revenue'); -
关闭答案面板(适用于生成式问答搜索栏选项)— 此功能将关闭答案面板并将 iframe 返回到原始搜索栏状态。
embeddedGenerativeQnExperience.close();
有关更多信息,请参阅亚马逊 Quick Sight 嵌入软件开发工具包