ステップ 3: 生成 Q&A エクスペリエンス URL を埋め込む

次のセクションでは、ウェブサイトまたはアプリケーションページに生成 Q&A エクスペリエンス URL を埋め込む方法について説明します。これは、Amazon QuickSight 埋め込み SDK () で行いますJavaScript。この SDK を使用することで、以下を実行できます。

生成 Q&A エクスペリエンスを HTML ページに配置します。
埋め込みエクスペリエンスのレイアウトと外観をアプリケーションのニーズに合わせてカスタマイズします。
アプリケーションに合わせてカスタマイズされたメッセージでエラー状態を処理します。

アプリケーションに埋め込むことができる URL を生成するには、GenerateEmbedUrlForAnonymousUser API オペレーションを呼び出します。この URL は 5 分間有効で、得られたセッションは最大 10 時間有効です。API オペレーションは、シングルサインオンセッションを有効にする auth_code 値を伴う URL を提供します。

以下に、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"
}

埋め込み QuickSight SDK を使用して、またはこの URL を iframe に追加して、生成 Q&A エクスペリエンスをウェブページに埋め込みます。固定の高さと幅の数値 (ピクセル単位) を設定した場合、はそれら QuickSight を使用し、ウィンドウのサイズ変更に伴ってビジュアルを変更しません。相対的な高さと幅の割合を設定すると、 QuickSight はウィンドウサイズの変化に応じて変化するレスポンシブレイアウトを提供します。

生成 Q&A エクスペリエンスをホストするドメインが、 QuickSight サブスクリプションで承認されたドメインのリストである許可リスト に含まれていることを確認します。この要件は、未承認のドメインが埋め込み生成 Q&A エクスペリエンスをホストしないようにすることで、データを保護します。埋め込み生成 Q&A エクスペリエンスのドメインの追加の詳細については、「」を参照してくださいドメインの管理と埋め込み。

QuickSight Embedding SDK を使用して、埋め込み生成 Q&A エクスペリエンスのレイアウトと外観をアプリケーションに合わせてカスタマイズできます。panelType プロパティを使用して、アプリケーションでレンダリングする際の生成 Q&A エクスペリエンスのランディング状態を設定します。panelType プロパティをに設定'FULL'して、完全な生成 Q&A エクスペリエンスパネルをレンダリングします。このパネルは、 QuickSight ユーザーがコンソールで体験しているものに似ています。パネルのフレームの高さは、ユーザーの操作に基づいて変更されず、 frameOptions.heightプロパティで設定した値を優先します。以下の図は、panelType値をに設定したときにがレンダリングする生成 Q&A エクスペリエンスパネルを示しています'FULL'。

panelType 値をに設定したときにレンダリングされる生成 Q&A エクスペリエンスパネル'FULL'。

panelType プロパティをに設定'SEARCH_BAR'して、生成 Q&A エクスペリエンスを検索バーとしてレンダリングします。この検索バーは、アプリケーションに埋め込まれたときに Q 検索バーがレンダリングする方法に似ています。生成 Q&A 検索バーが拡大され、トピック選択オプション、質問提案リスト、回答パネル、またはピンボードが表示されます。

埋め込みアセットがロードされると、生成 Q&A 検索バーのデフォルトの最小高さがレンダリングされます。検索バーのエクスペリエンスを最適化"38px"するには、 frameOptions.height 値をに設定することをお勧めします。focusedHeight プロパティを使用して、トピック選択ドロップダウンと質問提案リストの最適なサイズを設定します。expandedHeight プロパティを使用して、回答パネルとピンボードの最適なサイズを設定します。'SEARCH_BAR' オプションを選択した場合は、親コンテナを位置でスタイル設定することをお勧めします。アプリケーションで不要なコンテンツが移動しないように絶対です。以下の図は、panelType値をに設定したときにレンダリングされる生成 Q&A エクスペリエンス検索バーを示しています'SEARCH_BAR'。

panelType 値をに設定したときにレンダリングされる生成 Q&A エクスペリエンスパネル'SEARCH_BAR'。

panelType プロパティを設定したら、 QuickSight 埋め込み SDK を使用して生成 Q&A エクスペリエンスの次のプロパティをカスタマイズします。

生成 Q&A パネルのタイトル ( panelType: FULLオプションにのみ適用されます）。
検索バーのプレースホルダーテキスト。
トピックの選択を許可するかどうか。
トピック名を表示するか非表示にするか。
Amazon Q アイコンを表示するか非表示にするか ( panelType: FULLオプションにのみ適用されます）。
ピンボードが非表示になっているかどうかを示します。
ユーザーが生成 Q&A パネルを全画面表示に最大化できるかどうか。
生成 Q&A パネルのテーマ。カスタムテーマ ARN を SDK に渡して、フレームのコンテンツの外観を変更できます。

QuickSight Embedding SDK を使用すると、ページ上の生成 Q&A エクスペリエンスは状態に基づいて動的にサイズ変更されます。 QuickSight Embedding SDK を使用すると、生成 Q&A エクスペリエンス内のパラメータを制御したり、ページロードの完了、状態の変更、エラーに関してコールバックを受信したりすることもできます。

次の例は生成された 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 QuickSight Embedding SDK を使用して、を使用してウェブサイトに埋め込み生成 Q&A エクスペリエンスをロードします JavaScript。コピーを取得するには、次のいずれかを実行します。

から Amazon QuickSight 埋め込み SDK をダウンロードします GitHub。このリポジトリは開発者グループによって管理されます QuickSight 。
https://www.npmjs.com/package/amazon-quicksight-embedding-sdk から最新の埋め込み SDK バージョンをダウンロードします。
JavaScript 依存関係npmにを使用する場合は、次のコマンドを実行してダウンロードしてインストールします。
```
npm install amazon-quicksight-embedding-sdk
```

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ステップ 2: URL を生成する

オプション機能