Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Menyematkan Amazon Q di Amazon Quick Sight Generative Tanya Jawab
<a name="embedding-gen-bi"></a>


|  | 
| --- |
|    Pemirsa yang dituju: Pengembang Amazon Quick  | 

Di bagian berikut, Anda dapat menemukan informasi terperinci tentang cara mengatur pengalaman Tanya Jawab Generatif tertanam yang menggunakan kemampuan NLQ yang ditingkatkan yang didukung oleh. LLMs Pengalaman Tanya Jawab Generatif adalah pengganti yang direkomendasikan untuk Q Search Bar yang disematkan dan memberikan pengalaman BI yang diperbarui bagi pengguna.

**Topics**
+ [Menyematkan Amazon Q di Amazon Quick Sight Generative Q&A experience untuk pengguna terdaftar](#embedded-analytics-gen-bi-authenticated-users)
+ [Menyematkan Amazon Q dalam pengalaman Tanya Jawab Generatif Cepat untuk pengguna anonim (tidak terdaftar)](#embedded-analytics-gen-bi-anonymous-users)

## Menyematkan Amazon Q di Amazon Quick Sight Generative Q&A experience untuk pengguna terdaftar
<a name="embedded-analytics-gen-bi-authenticated-users"></a>

Di bagian berikut, Anda dapat menemukan informasi terperinci tentang cara menyiapkan pengalaman Tanya Jawab Generatif yang disematkan untuk pengguna terdaftar Amazon Quick Sight.

**Topics**
+ [Langkah 1: Siapkan izin](#embedded-analytics-gen-bi-authenticated-users-step-1)
+ [Langkah 2: Hasilkan URL dengan kode otentikasi terlampir](#embedded-analytics-gen-bi-authenticated-users-step-2)
+ [Langkah 3: Sematkan URL pengalaman Tanya Jawab Generatif](#embedded-analytics-gen-bi-authenticated-users-step-3)
+ [Fungsionalitas pengalaman Tanya Jawab Generatif tertanam opsional](#embedded-analytics-gen-bi-authenticated-users-step-4)

### Langkah 1: Siapkan izin
<a name="embedded-analytics-gen-bi-authenticated-users-step-1"></a>

Di bagian berikut, Anda dapat menemukan cara mengatur izin untuk aplikasi backend atau server web Anda untuk menyematkan pengalaman Tanya Jawab Generatif. Tugas ini membutuhkan akses administratif ke AWS Identity and Access Management (IAM).

Setiap pengguna yang mengakses pengalaman Tanya Jawab Generatif mengambil peran yang memberi mereka akses dan izin Amazon Quick Sight. Untuk memungkinkan ini, buat peran IAM di Anda Akun AWS. Kaitkan kebijakan IAM dengan peran untuk memberikan izin kepada pengguna mana pun yang mengasumsikannya. Peran IAM perlu memberikan izin untuk mengambil penyematan untuk kumpulan pengguna URLs tertentu. 

Dengan bantuan karakter *wildcard\$1*, Anda dapat memberikan izin untuk menghasilkan URL untuk semua pengguna di namespace tertentu. Atau Anda dapat memberikan izin untuk menghasilkan URL untuk subset pengguna di ruang nama tertentu. Untuk ini, Anda menambahkan`quicksight:GenerateEmbedUrlForRegisteredUser`.

Anda dapat membuat kondisi dalam kebijakan IAM yang membatasi domain yang dapat dicantumkan developer dalam `AllowedDomains` parameter operasi `GenerateEmbedUrlForRegisteredUser` API. `AllowedDomains`Parameter adalah parameter opsional. Ini memberi pengembang opsi untuk mengganti domain statis yang dikonfigurasi di menu Kelola **Amazon Quick Sight** dan sebagai gantinya mencantumkan hingga tiga domain atau subdomain yang dapat mengakses URL yang dihasilkan. URL ini kemudian disematkan di situs web pengembang. Hanya domain yang tercantum dalam parameter yang dapat mengakses pengalaman Tanya Jawab Generatif yang disematkan. Tanpa kondisi ini, pengembang dapat mencantumkan domain apa pun di internet dalam `AllowedDomains` parameter. 

Untuk membatasi domain yang dapat digunakan pengembang dengan parameter ini, tambahkan `AllowedEmbeddingDomains` kondisi ke kebijakan IAM Anda. Untuk informasi selengkapnya tentang `AllowedDomains` parameter, lihat [GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)di *Referensi API Amazon Quick Sight*.

**Praktik terbaik keamanan untuk operator kondisi IAM**  
Operator kondisi IAM yang tidak dikonfigurasi dengan benar dapat mengizinkan akses tidak sah ke sumber daya Cepat yang disematkan Anda melalui variasi URL. Saat menggunakan kunci `quicksight:AllowedEmbeddingDomains` kondisi dalam kebijakan IAM Anda, gunakan operator kondisi yang mengizinkan domain tertentu atau menolak semua domain yang tidak diizinkan secara khusus. Untuk informasi selengkapnya tentang operator kondisi IAM, lihat [elemen kebijakan IAM JSON: Operator kondisi di Panduan](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html) Pengguna IAM.  
Banyak variasi URL yang berbeda dapat menunjuk ke sumber daya yang sama. Misalnya, berikut ini URLs semua menyelesaikan konten yang sama:  
`https://example.com`
`https://example.com/`
`https://Example.com`
Jika kebijakan Anda menggunakan operator yang tidak memperhitungkan variasi URL ini, penyerang dapat melewati batasan Anda dengan memberikan variasi URL yang setara.  
Anda harus memvalidasi bahwa kebijakan IAM Anda menggunakan operator kondisi yang sesuai untuk mencegah kerentanan bypass dan memastikan bahwa hanya domain yang Anda inginkan yang dapat mengakses sumber daya yang disematkan.

Kebijakan contoh berikut memberikan izin ini.

Selain itu, jika Anda membuat pengguna pertama kali yang akan menjadi pembaca Amazon Quick Sight, pastikan untuk menambahkan `quicksight:RegisterUser` izin dalam kebijakan.

Kebijakan contoh berikut memberikan izin untuk mengambil URL penyematan bagi pengguna pertama kali yang akan menjadi pembaca Amazon Quick Sight.

Terakhir, identitas IAM aplikasi Anda harus memiliki kebijakan kepercayaan yang terkait dengannya untuk memungkinkan akses ke peran yang baru saja Anda buat. Ini berarti bahwa ketika pengguna mengakses aplikasi Anda, aplikasi Anda dapat mengambil peran atas nama pengguna dan menyediakan pengguna di Amazon Quick Sight. 

Contoh berikut menunjukkan contoh kebijakan kepercayaan.

------
#### [ 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"
            }
        ]
    }
```

------

*Untuk informasi selengkapnya mengenai kebijakan kepercayaan untuk otentikasi OpenID Connect atau Security Assertion Markup Language (SAM), lihat bagian berikut dari Panduan Pengguna IAM:*
+ [Membuat peran untuk identitas web atau federasi OpenID Connect (konsol)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [Membuat peran untuk federasi SAFL 2.0 (konsol)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

### Langkah 2: Hasilkan URL dengan kode otentikasi terlampir
<a name="embedded-analytics-gen-bi-authenticated-users-step-2"></a>

Di bagian berikut, Anda dapat menemukan cara mengautentikasi pengguna Anda dan mendapatkan URL topik Q yang dapat disematkan di server aplikasi Anda. Jika Anda berencana untuk menyematkan pengalaman Tanya Jawab Generatif untuk tipe identitas IAM atau Amazon Quick Sight, bagikan topik Q dengan pengguna.

Saat pengguna mengakses aplikasi Anda, aplikasi akan mengambil peran IAM atas nama pengguna. Kemudian aplikasi menambahkan pengguna ke Amazon Quick Sight, jika pengguna itu belum ada. Selanjutnya, ia melewati pengenal sebagai ID sesi peran unik. 

Melakukan langkah-langkah yang dijelaskan memastikan bahwa setiap pemirsa topik Q disediakan secara unik di Amazon Quick Sight. Ini juga memberlakukan pengaturan per pengguna, seperti keamanan tingkat baris dan default dinamis untuk parameter. Keamanan tingkat baris berbasis tag dapat digunakan untuk penyematan pengguna anonim dari bilah Q.

Contoh berikut melakukan otentikasi IAM atas nama pengguna. Kode ini berjalan di server aplikasi Anda.

#### Java
<a name="embedded-analytics-gen-bi-authenticated-users-java"></a>

```
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<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();
    }
}
```

#### JavaScript
<a name="embedded-analytics-gen-bi-authenticated-users-js"></a>

**catatan**  
Pembuatan URL embed APIs tidak dapat dipanggil dari browser secara langsung. Lihat contoh Node.JS sebagai gantinya.

#### Python3
<a name="embedded-analytics-gen-bi-authenticated-users-py"></a>

```
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
<a name="embedded-analytics-gen-bi-authenticated-users-node"></a>

Contoh berikut menunjukkan JavaScript (Node.js) yang dapat Anda gunakan di server aplikasi untuk menghasilkan URL untuk dasbor yang disematkan. Anda dapat menggunakan URL ini di situs web atau aplikasi Anda untuk menampilkan dasbor. 

**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
<a name="embedded-analytics-gen-bi-authenticated-users-cs"></a>

Contoh berikut menunjukkan kode.NET/C\$1 yang dapat Anda gunakan di server aplikasi untuk menghasilkan URL untuk bilah pencarian Q yang disematkan. Anda dapat menggunakan URL ini di situs web atau aplikasi Anda untuk menampilkan bilah pencarian 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
<a name="embedded-analytics-gen-bi-authenticated-users-cli"></a>

Untuk mengambil peran, pilih salah satu operasi API AWS Security Token Service (AWS STS) berikut:
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— Gunakan operasi ini ketika Anda menggunakan identitas IAM untuk mengambil peran.
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— Gunakan operasi ini ketika Anda menggunakan penyedia identitas web untuk mengautentikasi pengguna Anda. 
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— Gunakan operasi ini ketika Anda menggunakan SALL untuk mengautentikasi pengguna Anda.

Contoh berikut menunjukkan perintah CLI untuk mengatur peran IAM. Peran harus mengaktifkan izin untuk`quicksight:GenerateEmbedUrlForRegisteredUser`. Jika Anda mengambil just-in-time pendekatan untuk menambahkan pengguna saat mereka menggunakan topik di bilah pencarian Q, peran tersebut juga memerlukan izin yang diaktifkan. `quicksight:RegisterUser`

```
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`Operasi mengembalikan tiga parameter output: kunci akses, kunci rahasia, dan token sesi. 

**catatan**  
Jika Anda mendapatkan `ExpiredToken` kesalahan saat memanggil `AssumeRole` operasi, ini mungkin karena sebelumnya `SESSION TOKEN` masih dalam variabel lingkungan. Hapus ini dengan mengatur variabel berikut:  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

Contoh berikut menunjukkan cara mengatur ketiga parameter ini di CLI. Untuk mesin Microsoft Windows, gunakan `set` sebagai pengganti`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"
```

Menjalankan perintah ini akan menetapkan ID sesi peran pengguna yang mengunjungi situs web Anda`embedding_quicksight_q_search_bar_role/john.doe@example.com`. ID sesi peran terdiri dari nama peran dari `role-arn` dan `role-session-name` nilainya. Menggunakan ID sesi peran unik untuk setiap pengguna memastikan bahwa izin yang sesuai ditetapkan untuk setiap pengguna. Ini juga mencegah pembatasan akses pengguna. *Throttling* adalah fitur keamanan yang mencegah pengguna yang sama mengakses Amazon Quick Sight dari beberapa lokasi. 

ID sesi peran juga menjadi nama pengguna di Amazon Quick Sight. Anda dapat menggunakan pola ini untuk menyediakan pengguna Anda di Amazon Quick Sight sebelumnya, atau untuk memberi mereka saat pertama kali mereka mengakses pengalaman Tanya Jawab Generatif. 

Contoh berikut menunjukkan perintah CLI yang dapat Anda gunakan untuk menyediakan pengguna. Untuk informasi selengkapnya tentang [RegisterUser[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html)](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html),, dan operasi Amazon Quick Sight API lainnya, lihat [referensi 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
```

Jika pengguna diautentikasi melalui Microsoft AD, Anda tidak perlu menggunakannya `RegisterUser` untuk mengaturnya. Sebagai gantinya, mereka harus berlangganan secara otomatis saat pertama kali mengakses Amazon Quick Sight. Untuk pengguna Microsoft AD, Anda dapat menggunakan `DescribeUser` untuk mendapatkan pengguna Amazon Resource Name (ARN).

Saat pertama kali pengguna mengakses Amazon Quick Sight, Anda juga dapat menambahkan pengguna ini ke grup tempat dasbor dibagikan. Contoh berikut menunjukkan perintah CLI untuk menambahkan pengguna ke grup.

```
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"
```

Anda sekarang memiliki pengguna aplikasi Anda yang juga pengguna Amazon Quick Sight, dan yang memiliki akses ke dasbor. 

Terakhir, untuk mendapatkan URL yang ditandatangani untuk dasbor, panggil `generate-embed-url-for-registered-user` dari server aplikasi. Ini mengembalikan URL dasbor yang dapat disematkan. Contoh berikut menunjukkan cara membuat URL untuk dasbor tertanam menggunakan panggilan sisi server untuk pengguna yang diautentikasi melalui AWS Managed Microsoft AD atau sistem masuk tunggal (IAM Identity Center).

```
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
```

Untuk informasi lebih lanjut tentang penggunaan operasi ini, lihat [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html). Anda dapat menggunakan ini dan operasi API lainnya dalam kode Anda sendiri.

### Langkah 3: Sematkan URL pengalaman Tanya Jawab Generatif
<a name="embedded-analytics-gen-bi-authenticated-users-step-3"></a>

Di bagian berikut, Anda dapat menemukan cara menyematkan URL pengalaman Tanya Jawab Generatif di situs web atau halaman aplikasi Anda. Anda melakukan ini dengan [Amazon Quick Sight embedding SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) ()JavaScript. Dengan SDK, Anda dapat melakukan hal berikut: 
+ Tempatkan pengalaman Tanya Jawab Generatif pada halaman HTML.
+ Sesuaikan tata letak dan tampilan pengalaman yang disematkan agar sesuai dengan kebutuhan aplikasi Anda.
+ Menangani status kesalahan dengan pesan yang disesuaikan dengan aplikasi Anda.

Untuk membuat URL yang dapat disematkan di aplikasi, panggil operasi `GenerateEmbedUrlForRegisteredUser` API. URL ini berlaku selama 5 menit, dan sesi yang dihasilkan berlaku hingga 10 jam. Operasi API menyediakan URL dengan `auth_code` nilai yang memungkinkan sesi masuk tunggal. 

Berikut ini menunjukkan contoh respons dari`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"
}
```

Sematkan pengalaman Tanya Jawab Generatif di halaman web Anda dengan menggunakan [SDK penyematan Amazon Quick Sight](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) atau dengan menambahkan URL ini ke dalam iframe. Jika Anda menetapkan nomor tinggi dan lebar tetap (dalam piksel), Amazon Quick Sight menggunakannya dan tidak mengubah visual Anda saat jendela Anda berubah ukuran. Jika Anda menetapkan tinggi dan lebar persen relatif, Amazon Quick Sight menyediakan tata letak responsif yang dimodifikasi saat ukuran jendela Anda berubah. 

Pastikan domain untuk meng-host pengalaman Tanya Jawab Generatif yang disematkan ada di daftar izin, *daftar* domain yang disetujui untuk langganan Amazon Quick Sight Anda. Persyaratan ini melindungi data Anda dengan menjaga domain yang tidak disetujui dari hosting dasbor tertanam. Untuk informasi selengkapnya tentang menambahkan domain untuk pengalaman Tanya Jawab Generatif yang disematkan, lihat. [Mengelola domain](manage-domains.md)

Anda dapat menggunakan Amazon Quick Sight Embedding SDK untuk menyesuaikan tata letak dan tampilan pengalaman Tanya Jawab Generatif yang disematkan agar sesuai dengan aplikasi Anda. Gunakan `panelType` properti untuk mengonfigurasi status pendaratan pengalaman Tanya Jawab Generatif saat dirender dalam aplikasi Anda. Atur `panelType` properti `'FULL'` untuk membuat panel pengalaman Tanya Jawab Generatif lengkap. Panel ini menyerupai pengalaman yang dimiliki pengguna Amazon Quick Sight di konsol Amazon Quick Sight. Tinggi bingkai panel tidak berubah berdasarkan interaksi pengguna dan menghormati nilai yang Anda tetapkan di `frameOptions.height` properti. Gambar di bawah ini menunjukkan panel pengalaman Tanya Jawab Generatif yang dirender saat Anda menyetel nilainya. `panelType` `'FULL'`

Setel `panelType` properti `'SEARCH_BAR'` untuk membuat pengalaman Tanya Jawab Generatif sebagai bilah pencarian. Bilah pencarian ini menyerupai cara Q Search Bar ditampilkan ketika disematkan ke dalam aplikasi. Bilah pencarian Tanya Jawab Generatif meluas ke panel yang lebih besar yang menampilkan opsi pemilihan topik, daftar saran pertanyaan, panel jawaban, atau papan pin.

Tinggi minimum default dari bilah pencarian Tanya Jawab Generatif dirender saat aset yang disematkan dimuat. Disarankan agar Anda menetapkan `frameOptions.height` nilai `"38px"` untuk mengoptimalkan pengalaman bilah pencarian. Gunakan `focusedHeight` properti untuk mengatur ukuran optimal dropdown pemilihan topik dan daftar saran pertanyaan. Gunakan `expandedHeight` properti untuk mengatur ukuran optimal panel jawaban dan pinboard. Jika Anda memilih `'SEARCH_BAR'` opsi, disarankan agar Anda menata wadah induk dengan posisi; mutlak untuk menghindari pergeseran konten yang tidak diinginkan dalam aplikasi Anda. Gambar di bawah ini menunjukkan bilah pencarian pengalaman Tanya Jawab Generatif yang dirender saat Anda menetapkan nilainya. `panelType` `'SEARCH_BAR'`

Setelah mengonfigurasi `panelType` properti, gunakan SDK penyematan Amazon Quick Sight untuk menyesuaikan properti berikut dari pengalaman Tanya Jawab Generatif.
+ Judul panel Tanya Jawab Generatif (Berlaku hanya untuk opsi). `panelType: FULL` 
+ Teks placeholder bilah pencarian.
+ Apakah pemilihan topik diperbolehkan.
+ Apakah nama topik ditampilkan atau disembunyikan.
+ Apakah ikon Amazon Q ditampilkan atau disembunyikan (Berlaku hanya untuk `panelType: FULL` opsi).
+ Apakah pinboard ditampilkan tersembunyi.
+ Apakah pengguna dapat memaksimalkan panel T&J Genertaive ke layar penuh.
+ Tema panel Tanya Jawab Generatif. Tema khusus ARN dapat diteruskan di SDK untuk mengubah tampilan konten frame. Tema starter Amazon Quick Sight tidak didukung untuk panel Generative BI yang disematkan. Untuk menggunakan tema starter Amazon Quick Sight, simpan sebagai tema khusus di Amazon Quick Sight.

Saat Anda menggunakan Amazon Quick Sight Embedding SDK, pengalaman Tanya Jawab Generatif di halaman Anda diubah ukurannya secara dinamis berdasarkan status. Dengan menggunakan Amazon Quick Sight Embedding SDK, Anda juga dapat mengontrol parameter dalam pengalaman Tanya Jawab Generatif dan menerima panggilan balik dalam hal penyelesaian pemuatan halaman, perubahan status, dan kesalahan. 

Contoh berikut menunjukkan cara menggunakan URL yang dihasilkan. Kode ini dibuat di server aplikasi Anda.

#### SDK 2.0
<a name="collapsible-gen-bi-embedding-example"></a>

```
<!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>
```

Agar contoh ini berfungsi, pastikan untuk menggunakan Amazon Quick Sight Embedding SDK untuk memuat pengalaman Tanya Jawab Generatif yang disematkan di situs web Anda. JavaScript Untuk mendapatkan salinan Anda, lakukan salah satu hal berikut:
+ Unduh [SDK penyematan Amazon Quick Sight](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) dari. GitHub Repositori ini dikelola oleh sekelompok pengembang Amazon Quick Sight.
+ Unduh versi SDK penyematan terbaru dari. [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)
+ Jika Anda menggunakan `npm` untuk JavaScript dependensi, unduh dan instal dengan menjalankan perintah berikut.

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

### Fungsionalitas pengalaman Tanya Jawab Generatif tertanam opsional
<a name="embedded-analytics-gen-bi-authenticated-users-step-4"></a>

Fungsionalitas opsional berikut tersedia untuk pengalaman Tanya Jawab Generatif yang disematkan dengan SDK penyematan. 

#### Memanggil tindakan bilah penelusuran Tanya Jawab Generatif
<a name="w2aac35c27c21c43c29b9c21b5"></a>
+ Tetapkan pertanyaan — Fitur ini mengirimkan pertanyaan ke pengalaman Tanya Jawab Generatif dan segera menanyakan pertanyaan tersebut.

  ```
  embeddedGenerativeQnExperience.setQuestion('show me monthly revenue');
  ```
+ Tutup panel jawaban (berlaku untuk opsi bilah pencarian Tanya Jawab Generatif) - Fitur ini menutup panel jawaban dan mengembalikan iframe ke status bilah pencarian asli.

  ```
  embeddedGenerativeQnExperience.close();
  ```

Untuk informasi selengkapnya, lihat [SDK penyematan Amazon Quick Sight](https://github.com/awslabs/amazon-quicksight-embedding-sdk).

## Menyematkan Amazon Q dalam pengalaman Tanya Jawab Generatif Cepat untuk pengguna anonim (tidak terdaftar)
<a name="embedded-analytics-gen-bi-anonymous-users"></a>


|  | 
| --- |
|    Pemirsa yang dituju: Pengembang Amazon Quick  | 

Di bagian berikut, Anda dapat menemukan informasi terperinci tentang cara menyiapkan pengalaman Tanya Jawab Generatif yang disematkan untuk pengguna anonim (tidak terdaftar).

**Topics**
+ [Langkah 1: Siapkan izin](#embedded-analytics-gen-bi-anonymous-users-step-1)
+ [Langkah 2: Hasilkan URL dengan kode otentikasi terlampir](#embedded-analytics-gen-bi-anonymous-users-step-2)
+ [Langkah 3: Sematkan URL pengalaman Tanya Jawab Generatif](#embedded-analytics-gen-bi-anonymous-users-step-3)
+ [Fungsionalitas pengalaman Tanya Jawab Generatif tertanam opsional](#embedded-analytics-gen-bi-anonymous-users-step-4)

### Langkah 1: Siapkan izin
<a name="embedded-analytics-gen-bi-anonymous-users-step-1"></a>

Di bagian berikut, Anda dapat menemukan cara mengatur izin untuk aplikasi backend atau server web Anda untuk menyematkan pengalaman Tanya Jawab Generatif. Tugas ini membutuhkan akses administratif ke AWS Identity and Access Management (IAM).

Setiap pengguna yang mengakses pengalaman Tanya Jawab Generatif mengambil peran yang memberi mereka akses dan izin Amazon Quick Sight. Untuk memungkinkan ini, buat peran IAM di Anda Akun AWS. Kaitkan kebijakan IAM dengan peran untuk memberikan izin kepada pengguna mana pun yang mengasumsikannya. Peran IAM perlu memberikan izin untuk mengambil penyematan untuk kumpulan pengguna URLs tertentu. 

Dengan bantuan karakter *wildcard\$1*, Anda dapat memberikan izin untuk menghasilkan URL untuk semua pengguna di namespace tertentu. Atau Anda dapat memberikan izin untuk menghasilkan URL untuk subset pengguna di ruang nama tertentu. Untuk ini, Anda menambahkan`quicksight:GenerateEmbedUrlForAnonymousUser`.

Anda dapat membuat kondisi dalam kebijakan IAM yang membatasi domain yang dapat dicantumkan developer dalam `AllowedDomains` parameter operasi `GenerateEmbedUrlForAnonymousUser` API. `AllowedDomains`Parameter adalah parameter opsional. Ini memberi pengembang opsi untuk mengganti domain statis yang dikonfigurasi di menu Kelola **Amazon Quick Sight** dan sebagai gantinya mencantumkan hingga tiga domain atau subdomain yang dapat mengakses URL yang dihasilkan. URL ini kemudian disematkan di situs web pengembang. Hanya domain yang tercantum dalam parameter yang dapat mengakses bilah pencarian Q yang disematkan. Tanpa kondisi ini, pengembang dapat mencantumkan domain apa pun di internet dalam `AllowedDomains` parameter. 

Untuk membatasi domain yang dapat digunakan pengembang dengan parameter ini, tambahkan `AllowedEmbeddingDomains` kondisi ke kebijakan IAM Anda. Untuk informasi selengkapnya tentang `AllowedDomains` parameter, lihat [GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)di *Referensi API Amazon Quick Sight*.

**Praktik terbaik keamanan untuk operator kondisi IAM**  
Operator kondisi IAM yang tidak dikonfigurasi dengan benar dapat mengizinkan akses tidak sah ke sumber daya Cepat yang disematkan Anda melalui variasi URL. Saat menggunakan kunci `quicksight:AllowedEmbeddingDomains` kondisi dalam kebijakan IAM Anda, gunakan operator kondisi yang mengizinkan domain tertentu atau menolak semua domain yang tidak diizinkan secara khusus. Untuk informasi selengkapnya tentang operator kondisi IAM, lihat [elemen kebijakan IAM JSON: Operator kondisi di Panduan](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html) Pengguna IAM.  
Banyak variasi URL yang berbeda dapat menunjuk ke sumber daya yang sama. Misalnya, berikut ini URLs semua menyelesaikan konten yang sama:  
`https://example.com`
`https://example.com/`
`https://Example.com`
Jika kebijakan Anda menggunakan operator yang tidak memperhitungkan variasi URL ini, penyerang dapat melewati batasan Anda dengan memberikan variasi URL yang setara.  
Anda harus memvalidasi bahwa kebijakan IAM Anda menggunakan operator kondisi yang sesuai untuk mencegah kerentanan bypass dan memastikan bahwa hanya domain yang Anda inginkan yang dapat mengakses sumber daya yang disematkan.

Identitas IAM aplikasi Anda harus memiliki kebijakan kepercayaan yang terkait dengannya untuk memungkinkan akses ke peran yang baru saja Anda buat. Ini berarti bahwa ketika pengguna mengakses aplikasi Anda, aplikasi Anda dapat mengambil peran atas nama pengguna untuk memuat pengalaman Tanya Jawab Generatif. Contoh berikut menunjukkan contoh kebijakan kepercayaan.

------
#### [ 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"
        }
    ]
}
```

------

*Untuk informasi selengkapnya mengenai kebijakan kepercayaan, lihat [Kredensil keamanan sementara di IAM di Panduan Pengguna IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)*

### Langkah 2: Hasilkan URL dengan kode otentikasi terlampir
<a name="embedded-analytics-gen-bi-anonymous-users-step-2"></a>

Di bagian berikut, Anda dapat menemukan cara mengautentikasi pengguna Anda dan mendapatkan URL topik Q yang dapat disematkan di server aplikasi Anda.

Saat pengguna mengakses aplikasi Anda, aplikasi akan mengambil peran IAM atas nama pengguna. Kemudian aplikasi menambahkan pengguna ke Amazon Quick Sight, jika pengguna itu belum ada. Selanjutnya, ia melewati pengenal sebagai ID sesi peran unik. 

#### Java
<a name="embedded-analytics-gen-bi-anonymous-users-java"></a>

```
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<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();
    }

}
```

#### JavaScript
<a name="embedded-analytics-gen-bi-anonymous-users-js"></a>

**catatan**  
Pembuatan URL embed APIs tidak dapat dipanggil dari browser secara langsung. Lihat contoh Node.JS sebagai gantinya.

#### Python3
<a name="embedded-analytics-gen-bi-anonymous-users-py"></a>

```
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
<a name="embedded-analytics-gen-bi-anonymous-users-node"></a>

Contoh berikut menunjukkan JavaScript (Node.js) yang dapat Anda gunakan di server aplikasi untuk menghasilkan URL untuk dasbor yang disematkan. Anda dapat menggunakan URL ini di situs web atau aplikasi Anda untuk menampilkan dasbor. 

**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
<a name="embedded-analytics-gen-bi-anonymous-users-cs"></a>

Contoh berikut menunjukkan kode.NET/C\$1 yang dapat Anda gunakan di server aplikasi untuk menghasilkan URL untuk bilah pencarian Q yang disematkan. Anda dapat menggunakan URL ini di situs web atau aplikasi Anda untuk menampilkan bilah pencarian 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
<a name="embedded-analytics-gen-bi-anonymous-users-cli"></a>

Untuk mengambil peran, pilih salah satu operasi API AWS Security Token Service (AWS STS) berikut:
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— Gunakan operasi ini ketika Anda menggunakan identitas IAM untuk mengambil peran.
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— Gunakan operasi ini ketika Anda menggunakan penyedia identitas web untuk mengautentikasi pengguna Anda. 
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— Gunakan operasi ini ketika Anda menggunakan SALL untuk mengautentikasi pengguna Anda.

Contoh berikut menunjukkan perintah CLI untuk mengatur peran IAM. Peran harus mengaktifkan izin untuk`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`Operasi mengembalikan tiga parameter output: kunci akses, kunci rahasia, dan token sesi. 

**catatan**  
Jika Anda mendapatkan `ExpiredToken` kesalahan saat memanggil `AssumeRole` operasi, ini mungkin karena sebelumnya `SESSION TOKEN` masih dalam variabel lingkungan. Hapus ini dengan mengatur variabel berikut:  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

Contoh berikut menunjukkan cara mengatur ketiga parameter ini di CLI. Untuk mesin Microsoft Windows, gunakan `set` sebagai pengganti`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"
```

Menjalankan perintah ini akan menetapkan ID sesi peran pengguna yang mengunjungi situs web Anda`embedding_quicksight_q_search_bar_role/QuickSightEmbeddingAnonymousPolicy`. ID sesi peran terdiri dari nama peran dari `role-arn` dan `role-session-name` nilainya. Menggunakan ID sesi peran unik untuk setiap pengguna memastikan bahwa izin yang sesuai ditetapkan untuk setiap pengguna. Ini juga mencegah pembatasan akses pengguna. *Throttling* adalah fitur keamanan yang mencegah pengguna yang sama mengakses Amazon Quick Sight dari beberapa lokasi. Selain itu, ini membuat setiap sesi terpisah dan berbeda. Jika Anda menggunakan array server web, misalnya untuk load balancing, dan sesi terhubung kembali ke server yang berbeda, sesi baru dimulai.

Untuk mendapatkan URL yang ditandatangani untuk dasbor, panggil `generate-embed-url-for-anynymous-user` dari server aplikasi. Ini mengembalikan URL dasbor yang dapat disematkan. Contoh berikut menunjukkan cara membuat URL untuk dasbor tertanam menggunakan panggilan sisi server untuk pengguna yang melakukan kunjungan anonim ke portal web atau aplikasi Anda.

```
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
```

Untuk informasi lebih lanjut tentang penggunaan operasi ini, lihat [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html). Anda dapat menggunakan ini dan operasi API lainnya dalam kode Anda sendiri.

### Langkah 3: Sematkan URL pengalaman Tanya Jawab Generatif
<a name="embedded-analytics-gen-bi-anonymous-users-step-3"></a>

Di bagian berikut, Anda dapat menemukan cara menyematkan URL pengalaman Tanya Jawab Generatif di situs web atau halaman aplikasi Anda. Anda melakukan ini dengan [Amazon Quick Sight embedding SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) ()JavaScript. Dengan SDK, Anda dapat melakukan hal berikut: 
+ Tempatkan pengalaman Tanya Jawab Generatif pada halaman HTML.
+ Sesuaikan tata letak dan tampilan pengalaman yang disematkan agar sesuai dengan kebutuhan aplikasi Anda.
+ Menangani status kesalahan dengan pesan yang disesuaikan dengan aplikasi Anda.

Untuk membuat URL yang dapat disematkan di aplikasi, panggil operasi `GenerateEmbedUrlForAnonymousUser` API. URL ini berlaku selama 5 menit, dan sesi yang dihasilkan berlaku hingga 10 jam. Operasi API menyediakan URL dengan `auth_code` nilai yang memungkinkan sesi masuk tunggal. 

Berikut ini menunjukkan contoh respons dari`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"
}
```

Sematkan pengalaman Tanya Jawab Generatif di halaman web Anda dengan SDK [penyematan Amazon Quick Sight](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) atau dengan menambahkan URL ini ke dalam iframe. Jika Anda menetapkan nomor tinggi dan lebar tetap (dalam piksel), Amazon Quick Sight menggunakannya dan tidak mengubah visual Anda saat jendela Anda berubah ukuran. Jika Anda menetapkan tinggi dan lebar persen relatif, Amazon Quick Sight menyediakan tata letak responsif yang dimodifikasi saat ukuran jendela Anda berubah. 

Pastikan bahwa domain untuk meng-host pengalaman Tanya Jawab Generatif ada di *daftar izinkan, daftar* domain yang disetujui untuk langganan Amazon Quick Sight Anda. Persyaratan ini melindungi data Anda dengan menjaga domain yang tidak disetujui dari hosting pengalaman Tanya Jawab Generatif yang disematkan. Untuk informasi selengkapnya tentang menambahkan domain untuk pengalaman Tanya Jawab Generatif yang disematkan, lihat. [Mengelola domain](manage-domains.md)

Anda dapat menggunakan Amazon Quick Sight Embedding SDK untuk menyesuaikan tata letak dan tampilan pengalaman Tanya Jawab Generatif yang disematkan agar sesuai dengan aplikasi Anda. Gunakan `panelType` properti untuk mengonfigurasi status pendaratan pengalaman Tanya Jawab Generatif saat dirender dalam aplikasi Anda. Atur `panelType` properti `'FULL'` untuk membuat panel pengalaman Tanya Jawab Generatif lengkap. Panel ini menyerupai pengalaman yang dimiliki pengguna Amazon Quick Sight di konsol Amazon Quick Sight. Tinggi bingkai panel tidak berubah berdasarkan interaksi pengguna dan menghormati nilai yang Anda tetapkan di `frameOptions.height` properti. Gambar di bawah ini menunjukkan panel pengalaman Tanya Jawab Generatif yang dirender saat Anda menyetel nilainya. `panelType` `'FULL'`

Setel `panelType` properti `'SEARCH_BAR'` untuk membuat pengalaman Tanya Jawab Generatif sebagai bilah pencarian. Bilah pencarian ini menyerupai cara Q Search Bar ditampilkan ketika disematkan ke dalam aplikasi. Bilah pencarian Tanya Jawab Generatif meluas ke panel yang lebih besar yang menampilkan opsi pemilihan topik, daftar saran pertanyaan, panel jawaban, atau papan pin.

Tinggi minimum default dari bilah pencarian Tanya Jawab Generatif dirender saat aset yang disematkan dimuat. Disarankan agar Anda menetapkan `frameOptions.height` nilai `"38px"` untuk mengoptimalkan pengalaman bilah pencarian. Gunakan `focusedHeight` properti untuk mengatur ukuran optimal dropdown pemilihan topik dan daftar saran pertanyaan. Gunakan `expandedHeight` properti untuk mengatur ukuran optimal panel jawaban dan pinboard. Jika Anda memilih `'SEARCH_BAR'` opsi, disarankan agar Anda menata wadah induk dengan posisi; mutlak untuk menghindari pergeseran konten yang tidak diinginkan dalam aplikasi Anda. Gambar di bawah ini menunjukkan bilah pencarian pengalaman Tanya Jawab Generatif yang dirender saat Anda menetapkan nilainya. `panelType` `'SEARCH_BAR'`

Setelah mengonfigurasi `panelType` properti, gunakan SDK penyematan Amazon Quick Sight untuk menyesuaikan properti berikut dari pengalaman Tanya Jawab Generatif.
+ Judul panel Tanya Jawab Generatif (Berlaku hanya untuk opsi). `panelType: FULL` 
+ Teks placeholder bilah pencarian.
+ Apakah pemilihan topik diperbolehkan.
+ Apakah nama topik ditampilkan atau disembunyikan.
+ Apakah ikon Amazon Q ditampilkan atau disembunyikan (Berlaku hanya untuk `panelType: FULL` opsi).
+ Apakah pinboard ditampilkan tersembunyi.
+ Apakah pengguna dapat memaksimalkan panel T&J Genertaive ke layar penuh.
+ Tema panel Tanya Jawab Generatif. Tema khusus ARN dapat diteruskan di SDK untuk mengubah tampilan konten frame. Tema starter Amazon Quick Sight tidak didukung untuk panel Generative BI yang disematkan. Untuk menggunakan tema starter Amazon Quick Sight, simpan sebagai tema khusus di Amazon Quick Sight.

Saat Anda menggunakan Amazon Quick Sight Embedding SDK, pengalaman Tanya Jawab Generatif di halaman Anda diubah ukurannya secara dinamis berdasarkan status. Dengan Amazon Quick Sight Embedding SDK, Anda juga dapat mengontrol parameter dalam pengalaman Tanya Jawab Generatif dan menerima panggilan balik dalam hal penyelesaian pemuatan halaman, perubahan status, dan kesalahan. 

Contoh berikut menunjukkan cara menggunakan URL yang dihasilkan. Kode ini dibuat di server aplikasi Anda.

#### SDK 2.0
<a name="embedded-analytics-gen-bi-anonymous-users-sdkv2"></a>

```
<!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>
```

Agar contoh ini berfungsi, pastikan untuk menggunakan Amazon Quick Sight Embedding SDK untuk memuat pengalaman Tanya Jawab Generatif yang disematkan di situs web Anda. JavaScript Untuk mendapatkan salinan Anda, lakukan salah satu hal berikut:
+ Unduh [SDK penyematan Amazon Quick Sight](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) dari. GitHub Repositori ini dikelola oleh sekelompok pengembang Amazon Quick Sight.
+ Unduh versi SDK penyematan terbaru dari. [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)
+ Jika Anda menggunakan `npm` untuk JavaScript dependensi, unduh dan instal dengan menjalankan perintah berikut.

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

### Fungsionalitas pengalaman Tanya Jawab Generatif tertanam opsional
<a name="embedded-analytics-gen-bi-anonymous-users-step-4"></a>

Fungsionalitas opsional berikut tersedia untuk pengalaman Tanya Jawab Generatif yang disematkan dengan SDK penyematan. 

#### Memanggil tindakan bilah penelusuran Tanya Jawab Generatif
<a name="w2aac35c27c21c43c29c13c25b5"></a>
+ Tetapkan pertanyaan — Fitur ini mengirimkan pertanyaan ke pengalaman Tanya Jawab Generatif dan segera menanyakan pertanyaan tersebut.

  ```
  embeddedGenerativeQnExperience.setQuestion('show me monthly revenue');
  ```
+ Tutup panel jawaban (berlaku untuk opsi bilah pencarian Tanya Jawab Generatif) - Fitur ini menutup panel jawaban dan mengembalikan iframe ke status bilah pencarian asli.

  ```
  embeddedGenerativeQnExperience.close();
  ```

Untuk informasi selengkapnya, lihat [SDK penyematan Amazon Quick Sight](https://github.com/awslabs/amazon-quicksight-embedding-sdk).