1단계: 권한 설정 2단계: 생성 URL 3단계: 임베드 URL 선택적 함수

등록된 사용자를 위한 Amazon QuickSight Q 검색 창 포함

적용 대상: Enterprise Edition

대상: Amazon QuickSight 개발자

참고

임베디드 QuickSight Q 검색 표시줄은 Amazon QuickSight Q Business와 QuickSight 통합된 클래식 Q&A 환경을 제공하여 새로운 생성형 Q&A 환경을 시작합니다. 개발자는 새로운 생성형 Q&A 환경을 사용하는 것이 좋습니다. 임베디드 생성형 Q&A 환경에 대한 자세한 정보는 QuickSight 생성형 Q&A 환경에 Amazon Q 포함 섹션을 참조하세요.

다음 섹션에서는 등록된 사용자를 위해 임베디드 Amazon QuickSight Q 검색 창을 설정하는 방법에 대한 자세한 정보를 확인할 수 있습니다 QuickSight.

1단계: 권한 설정

참고

다음 단원에서 임베디드 Q 검색 창에 백엔드 애플리케이션 또는 웹 서버의 권한을 설정하는 방법을 알아봅니다. 이 작업을 수행하려면 AWS Identity and Access Management ()에 대한 관리 액세스 권한이 필요합니다IAM.

대시보드에 액세스하는 각 사용자는 Amazon에 대시보드에 대한 QuickSight 액세스 및 권한을 부여하는 역할을 맡습니다. 이를 가능하게 하려면에서 IAM 역할을 생성합니다 AWS 계정. IAM 정책을 역할과 연결하여 이를 수임하는 모든 사용자에게 권한을 제공합니다. IAM 역할은 특정 사용자 풀에 URLs 대한 임베딩을 검색할 수 있는 권한을 제공해야 합니다.

와일드카드 문자 *를 사용하여 특정 네임스페이스의 모든 사용자에 URL 대해를 생성할 수 있는 권한을 부여할 수 있습니다. 또는 특정 네임스페이스의 사용자 하위 집합에 URL 대해를 생성할 수 있는 권한을 부여할 수 있습니다. 이를 위해 quicksight:GenerateEmbedUrlForRegisteredUser을(를) 추가합니다.

IAM 정책에서 개발자가 GenerateEmbedUrlForRegisteredUser API 작업의 AllowedDomains 파라미터에 나열할 수 있는 도메인을 제한하는 조건을 생성할 수 있습니다. AllowedDomains 파라미터는 선택 파라미터입니다. 개발자는 관리 QuickSight 메뉴에서 구성된 정적 도메인을 재정의하고 생성된에 액세스할 수 있는 도메인 또는 하위 도메인을 최대 3개까지 나열할 수 있습니다URL. URL 그러면 개발자의 웹 사이트에 포함됩니다. 파라미터에 나열된 도메인만 임베디드 Q 검색 창에 액세스할 수 있습니다. 이 조건이 없으면, 개발자는 인터넷에 있는 모든 도메인을 AllowedDomains 파라미터에 나열할 수 있습니다.

개발자가이 파라미터와 함께 사용할 수 있는 도메인을 제한하려면 IAM 정책에 AllowedEmbeddingDomains 조건을 추가합니다. AllowedDomains 파라미터에 대한 자세한 내용은 Amazon QuickSight API 참조GenerateEmbedUrlForRegisteredUser의 섹션을 참조하세요.

다음 샘플 정책은 이러한 권한을 제공합니다.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "quicksight:GenerateEmbedUrlForRegisteredUser"
            ],
            "Resource": "arn:partition:quicksight:region:accountId:user/namespace/userName",
            "Condition": {
                "ForAllValues:StringEquals": {
                    "quicksight:AllowedEmbeddingDomains": [
                        "https://my.static.domain1.com",
                        "https://*.my.static.domain2.com"
                ]
            }
        }
        }
    ]
}

또한 Amazon QuickSight 독자가 될 최초 사용자를 생성하는 경우 정책에 quicksight:RegisterUser 권한을 추가해야 합니다.

다음 샘플 정책은 QuickSight 독자가 되어야 하는 URL 최초 사용자의 임베딩을 검색할 수 있는 권한을 제공합니다.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": "quicksight:RegisterUser",
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Effect": "Allow",
            "Action": [
              "quicksight:GenerateEmbedUrlForRegisteredUser"
            ],
            "Resource": [
              "arn:partition:quicksight:region:accountId:user/namespace/userName"
            ],
            "Condition": {
                "ForAllValues:StringEquals": {
                    "quicksight:AllowedEmbeddingDomains": [
                        "https://my.static.domain1.com",
                        "https://*.my.static.domain2.com"
                ]
            }
        }
        }
    ]
}

마지막으로 애플리케이션의 IAM 자격 증명에는 방금 생성한 역할에 대한 액세스를 허용하기 위한 신뢰 정책이 연결되어 있어야 합니다. 즉, 사용자가 애플리케이션에 액세스할 때 애플리케이션이 사용자를 대신하여 역할을 수임하고 사용자를 프로비저닝할 수 있습니다 QuickSight.

다음 예제는 샘플 신뢰 정책입니다.


{
    "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"
        }
    ]
}

OpenID Connect 또는 Security Assertion Markup Language(SAML) 인증의 신뢰 정책에 대한 자세한 내용은 IAM 사용 설명서의 다음 섹션을 참조하세요.

2단계: 인증 코드가 연결된 URL 상태에서 생성

참고

다음 섹션에서는 사용자를 인증하고 애플리케이션 서버에서 임베딩 가능한 Q 주제를 가져오는 방법을 찾을 수 URL 있습니다. IAM 또는 Amazon QuickSight 자격 증명 유형에 대한 Q 막대를 포함하려는 경우 Q 주제를 사용자와 공유합니다.

사용자가 앱에 액세스하면 앱이 사용자를 대신하여 IAM 역할을 수임합니다. 그런 다음 앱은 사용자가 아직 없는 QuickSight경우 사용자를에 추가합니다. 다음으로 식별자를 고유한 역할 세션 ID로 전달합니다.

설명된 단계를 수행하면 Q 주제의 각 뷰어가 고유하게 프로비저닝됩니다 QuickSight. 또한 사용자 단위 설정(예: 파라미터에 대한 동적 기본값 및 행 수준 보안)을 적용합니다.

다음 예제에서는 사용자를 대신하여 IAM 인증을 수행합니다. 이 코드는 앱 서버에서 실행됩니다.


import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
        import com.amazonaws.auth.AWSCredentialsProvider;
        import com.amazonaws.regions.Regions;
        import com.amazonaws.services.quicksight.AmazonQuickSight;
        import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserResult;
import com.amazonaws.services.quicksight.model.RegisteredUserEmbeddingExperienceConfiguration;
import com.amazonaws.services.quicksight.model.RegisteredUserQSearchBarEmbeddingConfiguration;

        /**
 * Class to call QuickSight AWS SDK to get url for embedding the Q search bar.
        */
public class RegisteredUserQSearchBarEmbeddingConfiguration {

            private final AmazonQuickSight quickSightClient;

    public RegisteredUserQSearchBarEmbeddingConfiguration() {
        this.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 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()
                .withQSearchBar(new RegisteredUserQSearchBarEmbeddingConfiguration().withInitialTopicId(topicId));
        final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest = new GenerateEmbedUrlForRegisteredUserRequest();
        generateEmbedUrlForRegisteredUserRequest.setAwsAccountId(accountId);
        generateEmbedUrlForRegisteredUserRequest.setUserArn(userArn);
        generateEmbedUrlForRegisteredUserRequest.setAllowedDomains(allowedDomains);
        generateEmbedUrlForRegisteredUserRequest.setExperienceConfiguration(QSearchBar);

        final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);

        return generateEmbedUrlForRegisteredUserResult.getEmbedUrl();
            }
        }


global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function generateEmbedUrlForRegisteredUser(
    accountId,
    topicId, // Topic ID to embed
    openIdToken, // Cognito-based token
    userArn, // registered user arn
    roleArn, // IAM user role to use for embedding
    sessionName, // Session name for the roleArn assume role
    allowedDomains, // Runtime allowed domain for embedding
    getEmbedUrlCallback, // GetEmbedUrl success callback method
    errorCallback // GetEmbedUrl error callback method
    ) {
    const stsClient = new AWS.STS();
    let stsParams = {
        RoleSessionName: sessionName,
        WebIdentityToken: openIdToken,
        RoleArn: roleArn
        }
    
    stsClient.assumeRoleWithWebIdentity(stsParams, function(err, data) {
        if (err) {
            console.log('Error assuming role');
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const getQSearchBarParams = {
        "AwsAccountId": accountId,
                "ExperienceConfiguration": {
                    "QSearchBar": {
                        "InitialTopicId": topicId
                    }
                },
                "UserArn": userArn,
        "AllowedDomains": allowedDomains,
        "SessionLifetimeInMinutes": 600
    };

            const quicksightGetQSearchBar = new AWS.QuickSight({
        region: process.env.AWS_REGION,
                credentials: {
                    accessKeyId: data.Credentials.AccessKeyId,
                    secretAccessKey: data.Credentials.SecretAccessKey,
                    sessionToken: data.Credentials.SessionToken,
                    expiration: data.Credentials.Expiration
                }
    });

            quicksightGetQSearchBar.generateEmbedUrlForRegisteredUser(getQSearchBarParams, function(err, data) {
        if (err) {
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const result = {
                "statusCode": 200,
                "headers": {
                            "Access-Control-Allow-Origin": "*", // Use your website domain to secure access to GetEmbedUrl API
                    "Access-Control-Allow-Headers": "Content-Type"
                },
                "body": JSON.stringify(data),
                "isBase64Encoded": false
            }
                    getEmbedUrlCallback(result);
                }
            });
        }
    });
}


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 = {
                    "QSearchBar": {
                        "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)

다음 예제는 앱 서버에서 임베디드 대시보드에 URL 대한를 생성하는 데 사용할 수 있는 JavaScript (Node.js)를 보여줍니다. 웹 사이트 또는 앱에서 이를 사용하여 대시보드를 표시할 수 URL 있습니다.


const AWS = require('aws-sdk');
const https = require('https');

var quicksightClient = new AWS.Service({
    apiConfig: require('./quicksight-2018-04-01.min.json'),
    region: 'us-east-1',
});

quicksightClient.generateEmbedUrlForRegisteredUser({
    'AwsAccountId': '111122223333',
    'ExperienceConfiguration': { 
        'QSearchBar': {
            '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);
});


//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/embed/12345/dashboards/67890/sheets/12345/visuals/67890...",
        RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' 
    }

다음 예제에서는를 보여줍니다.NET/앱 서버에서 임베디드 Q 검색 창에 URL 대한를 생성하는 데 사용할 수 있는 C# 코드입니다. 웹 사이트 또는 앱에서 이를 사용하여 Q 검색 창을 표시할 수 URL 있습니다.


using System;
using Amazon.QuickSight;
using Amazon.QuickSight.Model;

namespace GenerateDashboardEmbedUrlForRegisteredUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                RegisteredUserQSearchBarEmbeddingConfiguration registeredUserQSearchBarEmbeddingConfiguration
                    = new RegisteredUserQSearchBarEmbeddingConfiguration
                    {
                        InitialTopicId = "U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f"
                    };
                RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                    = new RegisteredUserEmbeddingExperienceConfiguration
                    {
                        QSearchBar = registeredUserQSearchBarEmbeddingConfiguration
                    }; 
                
                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 Security Token Service (AWS STS) API 작업 중 하나를 선택합니다.

AssumeRole - 자격 IAM 증명을 사용하여 역할을 수임하는 경우이 작업을 사용합니다.
AssumeRoleWithWebIdentity - 웹 자격 증명 공급자를 사용하여 사용자를 인증할 때이 작업을 사용합니다.
AssumeRoleWithSaml -를 사용하여 사용자를 인증SAML할 때이 작업을 사용합니다.

다음 예제에서는 IAM 역할을 설정하는 CLI 명령을 보여줍니다. 역할은 quicksight:GenerateEmbedUrlForRegisteredUser에 대한 권한이 활성화되어 있어야 합니다. Q 검색 창에서 주제를 사용할 때 사용자를 추가하는 접근 방식을 취하는 just-in-time 경우 역할에는에 대해 활성화된 권한도 필요합니다quicksight:RegisterUser.


aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_search_bar_role" \
     --role-session-name john.doe@example.com

assume-role 작업은 액세스 키, 보안 키 및 세션 토큰의 세 가지 출력 파라미터를 반환합니다.

참고

AssumeRole 작업을 호출할 때 ExpiredToken 오류가 발생할 경우, 이는 아마도 이전의 SESSION TOKEN이(가) 환경 변수에 남아 있기 때문입니다. 다음 변수를 설정하여 이를 삭제합니다.

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

다음 예제는에서 이러한 세 파라미터를 설정하는 방법을 보여줍니다CLI. Microsoft Windows 컴퓨터의 경우, export 대신 set을(를) 사용하십시오.


export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"

이러한 명령을 실행하여 웹 사이트를 방문하는 사용자의 역할 세션 ID를 embedding_quicksight_q_search_bar_role/john.doe@example.com으로 설정합니다. 역할 세션 ID는 role-arn의 역할 이름과 role-session-name 값으로 구성됩니다. 각 사용자에 대해 적절한 권한을 설정하려면 각 사용자에 대해 고유한 역할 세션 ID를 사용해야 합니다. 또한 사용자 액세스 조절을 방지할 수 있습니다. 제한은 동일한 사용자가 여러 위치에서 QuickSight 에 액세스하지 못하도록 하는 보안 기능입니다.

또한 역할 세션 ID는 QuickSight에서 사용자 이름으로 사용됩니다. 이 패턴을 사용하여 사용자를 QuickSight 미리 프로비저닝하거나 Q 검색 창에 처음 액세스할 때 프로비저닝할 수 있습니다.

다음 예제에서는 사용자를 프로비저닝하는 데 사용할 수 있는 CLI 명령을 보여줍니다. RegisterUser, DescribeUser및 기타 QuickSight API 작업에 대한 자세한 내용은 QuickSight API 참조를 참조하세요.


aws quicksight register-user \
    --aws-account-id 111122223333 \
    --namespace default \
    --identity-type IAM \
    --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_search_bar_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

사용자가 Microsoft AD를 통해 인증된 경우에는 설정을 위해 RegisterUser를 사용하지 않아도 됩니다. 대신 처음 액세스할 때 자동으로 구독해야 합니다 QuickSight. Microsoft AD 사용자의 경우 DescribeUser를 사용하여 사용자 Amazon 리소스 이름()을 가져올 수 있습니다ARN.

사용자가 처음에 액세스할 QuickSight때 대시보드가 공유되는 그룹에이 사용자를 추가할 수도 있습니다. 다음 예제에서는 그룹에 사용자를 추가하는 CLI 명령을 보여줍니다.


aws quicksight create-group-membership \
    --aws-account-id=111122223333 \
    --namespace=default \
    --group-name=financeusers \
    --member-name="embedding_quicksight_q_search_bar_role/john.doe@example.com"

이제 앱의 사용자도 대시보드에 액세스할 수 QuickSight있는 사용자입니다.

마지막으로 대시보드에 URL 대한 서명을 받으려면 앱 서버에서 generate-embed-url-for-registered-user를 호출합니다. 그러면 임베드 가능한 대시보드가 반환됩니다URL. 다음 예제에서는 AWS Managed Microsoft AD 또는 Single Sign-On(IAM Identity Center)을 통해 인증된 사용자에 URL 대한 서버 측 호출을 사용하여 임베디드 대시보드에 대한를 생성하는 방법을 보여줍니다.


aws quicksight generate-embed-url-for-registered-user \
--aws-account-id 111122223333 \
--session-lifetime-in-minutes 600 \
--user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_q_search_bar_role/embeddingsession
--allowed-domains '["domain1","domain2"]' \
--experience-configuration QSearchBar={InitialTopicId=U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f}

이 작업 사용에 대한 자세한 내용은 섹션을 참조하세요. GenerateEmbedUrlForRegisteredUser. 자체 코드에서이 작업과 다른 API 작업을 사용할 수 있습니다.

3단계: Q 검색 창 포함 URL

참고

다음 섹션에서는 웹 사이트 또는 애플리케이션 페이지의 3단계URL에서 Q 검색 창을 포함하는 방법을 확인할 수 있습니다. Amazon QuickSight 임베딩SDK()을 사용하여이 작업을 수행합니다JavaScript. SDK에서 다음 작업을 수행할 수 있습니다.

Q 검색 창을 HTML 페이지에 배치합니다.
Q 검색창에 파라미터를 전달합니다.
애플리케이션에 사용자 지정되는 메시지로 오류 상태 처리

앱에 포함할 수 URL 있는를 생성하려면 GenerateEmbedUrlForRegisteredUser API 작업을 호출합니다. 이는 5분 동안 URL 유효하며 결과 세션은 최대 10시간 동안 유효합니다. API 작업은에 Single-sign on 세션을 활성화하는 URL auth_code 값을 제공합니다.

다음은 generate-embed-url-for-registered-user의 응답 예입니다.


//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
{
     "Status": "200",
     "EmbedUrl": "https://quicksightdomain/embedding/12345/q/search...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}

임베QuickSight딩을 사용하거나 이를 iframe에 추가하여 웹 페이지에 Q 검색 창을 임베SDK딩합니다. URL 고정 높이 및 너비 수(픽셀)를 설정하는 경우는 이를 QuickSight 사용하고 창 크기가 조정될 때 시각적 객체를 변경하지 않습니다. 상대 비율 높이 및 너비를 설정한 경우 QuickSight가 창 크기 변화에 따라 수정되는 반응형 레이아웃을 제공합니다.

이렇게 하려면 임베디드 Q 검색 창을 호스팅할 도메인이 QuickSight 구독에 승인된 도메인 목록인 허용 목록에 있는지 확인합니다. 이 요건은 임베디드 대시보드에서 미승인 도메인을 제외함으로써 데이터를 보호합니다. 임베디드 Q 검색 창의 도메인 추가에 대한 자세한 내용은 도메인 및 임베딩 관리 단원을 참조하세요.

QuickSight 임베딩을 사용하면 페이지의 SDKQ 검색 표시줄이 상태에 따라 동적으로 크기가 조정됩니다. QuickSight 임베딩을 사용하면 Q 검색 창에서 파라미터를 제어하고 페이지 로드 완료 및 오류 측면에서 콜백을 수신SDK할 수도 있습니다.

다음 예제에서는 생성된를 사용하는 방법을 보여줍니다URL. 이 코드는 앱 서버에서 생성됩니다.


<!DOCTYPE html>
<html>

    <head>
        <title>Q Search Bar Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedQSearchBar = 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 = {
                    hideTopicName: false, 
                    theme: '<YOUR_THEME_ID>',
                    allowTopicSelection: true,
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'Q_SEARCH_OPENED': {
                                console.log("Do something when Q Search content expanded");
                                break;
                            }
                            case 'Q_SEARCH_CLOSED': {
                                console.log("Do something when Q Search content collapsed");
                                break;
                            }
                            case 'Q_SEARCH_SIZE_CHANGED': {
                                console.log("Do something when Q Search size changed");
                                break;
                            }
                            case 'CONTENT_LOADED': {
                                console.log("Do something when the Q Search is loaded.");
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Do something when the Q Search fails loading.");
                                break;
                            }
                        }
                    }
                };
                const embeddedDashboardExperience = await embeddingContext.embedQSearchBar(frameOptions, contentOptions);
            };
        </script>
    </head>

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

</html>


<!DOCTYPE html>
<html>

    <head>
        <title>QuickSight Q Search Bar Embedding</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.18.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            var session

            function onError(payload) {
                console.log("Do something when the session fails loading");
            }

            function onOpen() {
                console.log("Do something when the Q search bar opens");
            }

            function onClose() {
                console.log("Do something when the Q search bar closes");
            }

            function embedQSearchBar() {
                var containerDiv = document.getElementById("embeddingContainer");
                var options = {
                    url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode", // replace this dummy url with the one generated via embedding API
                    container: containerDiv,
                    width: "1000px",
                    locale: "en-US",
                    qSearchBarOptions: {
                        expandCallback: onOpen,
                        collapseCallback: onClose,
                        iconDisabled: false,
                        topicNameDisabled: false, 
                        themeId: 'bdb844d0-0fe9-4d9d-b520-0fe602d93639',
                        allowTopicSelection: true
                    }
                };
                session = QuickSightEmbedding.embedQSearchBar(options);
                session.on("error", onError);
            }

            function onCountryChange(obj) {
                session.setParameters({country: obj.value});
            }
        </script>
    </head>

    <body onload="embedQSearchBar()">
        <div id="embeddingContainer"></div>
    </body>

</html>

이 예제가 작동하려면 Amazon QuickSight Embedding을 사용하여 SDK를 사용하여 웹 사이트에 임베디드 대시보드를 로드해야 합니다 JavaScript. 이 정보를 얻으려면 다음 중 하나를 수행합니다.

에서 Amazon QuickSight 임베딩SDK을 다운로드합니다 GitHub. 이 리포지토리는 QuickSight 개발자 그룹에 의해 유지됩니다.
에서 최신 임베딩 SDK 버전을 다운로드합니다https://www.npmjs.com/package/amazon-quicksight-embedding-sdk.
JavaScript 종속성npm에를 사용하는 경우 다음 명령을 실행하여 다운로드하고 설치합니다.
```
npm install amazon-quicksight-embedding-sdk
```

선택적 Amazon QuickSight Q 검색 창 임베딩 기능

참고

임베딩를 사용하여 임베디드 Q 검색 창에 사용할 수 있는 선택적 기능은 다음과 같습니다SDK.

Q 검색 창 작업 간접 호출

다음 옵션은 Q 검색 창 임베딩에만 지원됩니다.

Q 검색 창 질문 설정 - 이 기능은 질문을 Q 검색 창으로 보내고 질문을 즉시 쿼리합니다. 또한 Q 팝오버도 자동으로 열립니다.
```
qBar.setQBarQuestion('show me monthly revenue');
```
Q 팝오버 닫기 - 이 기능은 Q 팝오버를 닫고 iframe을 원래 Q 검색창 크기로 되돌립니다.
```
qBar.closeQPopover();
```

자세한 내용은 QuickSight 임베딩을 SDK참조하세요.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

QuickSight Q 검색 창 포함(클래식)

익명 사용자를 위한 QuickSight Q 검색 창 포함