Étape 3 : Intégrer l'URL de l'expérience de questions-réponses générative

Dans la section suivante, vous découvrirez comment intégrer l'URL de l'expérience de questions-réponses générative dans votre site Web ou votre page d'application. Pour ce faire, utilisez le SDK QuickSight d'intégration Amazon ()JavaScript. Le kit SDK vous permet d'effectuer les opérations suivantes :

• Placez l'expérience de questions-réponses générative sur une page HTML.

• Personnalisez la mise en page et l'apparence de l'expérience intégrée en fonction des besoins de votre application.

• Gérer les états d'erreurs avec des messages personnalisés pour votre application.

Pour générer l'URL que vous pouvez intégrer dans votre application, appelez l'opération d'API GenerateEmbedUrlForAnonymousUser. Cette URL est valable pendant 5 minutes et la session qui en résulte est valide jusqu'à 10 heures. L'opération d'API fournit l'URL avec une valeur auth_code qui permet une session à connexion unique.

Voici un exemple de réponse de 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"
} 

Intégrez l'expérience de questions-réponses générative à votre page Web à l'aide du SDK QuickSight d'intégration ou en ajoutant cette URL dans un iframe. Si vous définissez une hauteur et une largeur fixes (en pixels), QuickSight utilisez-les et ne modifiez pas votre visuel lors du redimensionnement de la fenêtre. Si vous définissez un pourcentage relatif de hauteur et de largeur, QuickSight fournit une mise en page réactive qui est modifiée en fonction de l'évolution de la taille de votre fenêtre.

Assurez-vous que le domaine qui hébergera l'expérience Generative Q&R figure sur la liste des domaines autorisés, c'est-à-dire la liste des domaines approuvés pour votre QuickSight abonnement. Cette exigence protège vos données en empêchant les domaines non approuvés d'héberger des expériences de questions-réponses génératives intégrées. Pour plus d'informations sur l'ajout de domaines pour une expérience de questions-réponses générative intégrée, consultezGestion des domaines et des intégrations.

Vous pouvez utiliser le SDK QuickSight d'intégration pour personnaliser la mise en page et l'apparence de l'expérience de questions-réponses générative intégrée en fonction de votre application. Utilisez cette panelType propriété pour configurer l'état d'arrivée de l'expérience de questions-réponses générative lors de son affichage dans votre application. Définissez la panelType propriété sur pour 'FULL' afficher l'intégralité du panneau d'expérience Generative Q&R. Ce panneau ressemble à l'expérience des QuickSight utilisateurs dans la console. La hauteur du cadre du panneau n'est pas modifiée en fonction de l'interaction de l'utilisateur et respecte la valeur que vous avez définie dans la frameOptions.height propriété. L'image ci-dessous montre le panneau d'expérience générative de questions-réponses qui s'affiche lorsque vous définissez la panelType valeur sur. 'FULL'

Définissez la panelType propriété sur pour 'SEARCH_BAR' afficher l'expérience de questions-réponses générative sous forme de barre de recherche. Cette barre de recherche ressemble au rendu de la barre de recherche Q lorsqu'elle est intégrée à une application. La barre de recherche générative de questions-réponses s'étend à un panneau plus grand qui affiche les options de sélection de sujets, la liste de suggestions de questions, le panneau de réponses ou le tableau d'affichage.

La hauteur minimale par défaut de la barre de recherche Generative Q&R est affichée lorsque l'actif intégré est chargé. Il est recommandé de définir la frameOptions.height valeur sur "38px" pour optimiser l'expérience de la barre de recherche. Utilisez cette focusedHeight propriété pour définir la taille optimale de la liste déroulante de sélection des sujets et de la liste de suggestions de questions. Utilisez cette expandedHeight propriété pour définir la taille optimale du panneau de réponses et du tableau d'affichage. Si vous choisissez 'SEARCH_BAR' cette option, il est recommandé de définir le style du conteneur parent en utilisant la position ; absolu pour éviter tout déplacement de contenu indésirable dans votre application. L'image ci-dessous montre la barre de recherche de l'expérience Generative Q&R qui s'affiche lorsque vous définissez la panelType valeur sur. 'SEARCH_BAR'

Après avoir configuré la panelType propriété, utilisez le SDK QuickSight d'intégration pour personnaliser les propriétés suivantes de l'expérience Generative Q&R.

• Titre du panel de questions-réponses génératives (s'applique uniquement à l'panelType: FULLoption).

• Le texte de remplacement de la barre de recherche.

• Si la sélection de sujets est autorisée.

• Indique si les noms des rubriques sont affichés ou masqués.

• Indique si l'icône Amazon Q est affichée ou masquée (s'applique uniquement à l'panelType: FULLoption).

• Indique si le tableau d'affichage est affiché ou masqué.

• Si les utilisateurs peuvent optimiser le panneau de questions-réponses génératives en plein écran.

• Le thème du panel de questions-réponses génératives. Un ARN de thème personnalisé peut être transmis au SDK pour modifier l'apparence du contenu du cadre.

Lorsque vous utilisez le SDK QuickSight d'intégration, l'expérience générative de questions-réponses de votre page est redimensionnée dynamiquement en fonction de l'état. Avec le SDK QuickSight d'intégration, vous pouvez également contrôler les paramètres de l'expérience Generative Q&R et recevoir des rappels en termes de fin de chargement de page, de changements d'état et d'erreurs.

L'exemple suivant montre comment utiliser l'URL générée. Ce code est généré sur votre serveur d'applications.

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>

Pour que cet exemple fonctionne, assurez-vous d'utiliser le SDK Amazon QuickSight Embedding pour charger l'expérience de questions-réponses générative intégrée sur votre site Web. JavaScript Pour obtenir votre copie, effectuez l'une des actions suivantes :

• Téléchargez le SDK QuickSight d'intégration Amazon depuis. GitHub Ce référentiel est géré par un groupe de QuickSight développeurs.

• Téléchargez la dernière version du SDK d'intégration sur https://www.npmjs.com/package/. amazon-quicksight-embedding-sdk

• Si vous utilisez npm for JavaScript dependencies, téléchargez-le et installez-le en exécutant la commande suivante.

  npm install amazon-quicksight-embedding-sdk