第 3 步：嵌入生成式问答体验网址 - Amazon QuickSight

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

第 3 步：嵌入生成式问答体验网址

在下一节中，您可以找到如何在您的网站或应用程序页面中嵌入生成式问答体验网址。您可以使用 Amazon QuickSight 嵌入软件开发工具包 (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"
}

使用嵌入式 SDK 或将此 URL 添加到 iframe 中，将生成式问答体验QuickSight嵌入到您的网页中。如果您设置了固定的高度和宽度数字（以像素为单位），则 QuickSight 使用这些数字，并且不会在窗口大小调整时更改视觉效果。如果您设置了相对的百分比高度和宽度，则会 QuickSight提供响应式布局，该布局会随着窗口大小的变化而进行修改。

请确保托管生成问答体验的域名在允许列表中，这是您 QuickSight 订阅的已批准域名列表。此要求通过防止未经批准的域名托管嵌入式生成问答体验来保护您的数据。有关为嵌入式生成问答体验添加域名的更多信息，请参阅管理域和嵌入。

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

生成式问答体验面板，当您将panelType值设置为时会呈现。'FULL'

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

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

生成式问答体验面板，当您将panelType值设置为时会呈现。'SEARCH_BAR'

配置panelType属性后，使用 QuickSight 嵌入式 SDK 自定义生成问答体验的以下属性。

  • 生成式问答面板的标题（仅适用于该panelType: FULL选项）。

  • 搜索栏的占位符文本。

  • 是否允许选择主题。

  • 主题名称是显示还是隐藏。

  • Amazon Q 图标是显示还是隐藏（仅适用于该panelType: FULL选项）。

  • 插接板是否显示为隐藏。

  • 用户是否可以将生成问答面板最大化为全屏显示。

  • 生成式问答小组的主题。可以在 SDK 中传递自定义主题 ARN 以更改框架内容的外观。

当你使用 Emb QuickSight edding SDK 时，页面上的生成式问答体验会根据状态动态调整大小。借助 E QuickSight mbedding SDK，您还可以控制生成式问答体验中的参数，并接收有关页面加载完成、状态更改和错误的回调。

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

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

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

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

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

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

</html>

要使此示例起作用，请务必使用 Amazon Em QuickSight bedding SDK 在您的网站上加载嵌入式生成问答体验 JavaScript。要获取副本，请执行下列操作之一：