本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 Amazon Quick Sight APIs 內嵌
<a name="embedded-analytics-api"></a>


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

只有幾個步驟涉及使用 Amazon Quick Sight APIs 內嵌分析的實際程序。

開始前，請確定您有下列項目：
+ 為應用程式使用的呼叫者身分設定必要的 IAM 許可，該身分將使用 AWS SDK 進行 API 呼叫。例如，授予允許 `quicksight:GenerateEmbedUrlForAnonymousUser` 或 `quicksight:GenerateEmbedUrlForRegisteredUser` 動作的許可。
+ 若要為已註冊的使用者嵌入 ，請事先與他們共用 Amazon Quick Sight 資產。對於新的驗證使用者，請了解如何授予資產存取權。其中一種方法是將所有資產新增至 Amazon Quick Sight 資料夾。如果您偏好使用 Amazon Quick Sight API，請使用 `DescribeDashboardPermissions`和 `UpdateDashboardPermissions` API 操作。如需詳細資訊，請參閱《*Amazon Quick API 參考*》中的 [DescribeDashboardPermissions](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeDashboardPermissions.html) 或 [UpdateDashboardPermissions](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_UpdateDashboardPermissions.html)。如果您想要與命名空間或群組中的所有使用者共用儀表板，您可以與 `namespace` 或 `group` 共用儀表板。
+ 如果您要嵌入儀表板，請確保具有要嵌入的儀表板的 ID。儀表板 ID 是儀表板 URL 中的代碼。您也可以從儀表板 URL 獲取它。
+ Amazon Quick Sight 管理員必須明確啟用您計劃嵌入 Amazon Quick Sight 分析的網域。您可以使用設定檔功能表中的**管理 Amazon Quick Sight**、**網域和內嵌**來執行此操作，也可以使用 `GenerateEmbedUrlForAnonymousUser`或 `GenerateEmbedUrlForRegisteredUser` API 呼叫的 `AllowedDomains` 參數。

  只有 Amazon Quick Sight 管理員可以看到此選項。您也可以將子網域新增為域的一部分。如需詳細資訊，請參閱[允許使用 Amazon Quick API 在執行時間列出網域](manage-domains.md#embedding-run-time)。

  必須明確允許靜態允許清單 (例如開發、預備和生產) 中的所有域，且必須使用 HTTPS。新增至允許清單中的域可多達 100 個。您可以使用 Amazon Quick Sight API 操作在執行時間新增網域。

完成所有先決條件後，嵌入 Amazon Quick Sight 會涉及下列步驟，稍後會更詳細地說明這些步驟：

1. 對於身分驗證，請使用應用程式伺服器來驗證使用者。在伺服器中驗證之後，請使用您需要的 AWS SDK 產生內嵌儀表板 URL。

1. 在您的 Web 入口網站或應用程式中，使用產生的 URL 內嵌 Amazon Quick Sight。若要簡化此程序，您可以使用 [NPMJS](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 和 [GitHub](https://github.com/awslabs/amazon-quicksight-embedding-sdk) 上提供的 Amazon Quick Sight 內嵌 SDK。此自訂 JavaScript 開發套件旨在協助您有效地將 Amazon Quick Sight 整合到您的應用程式頁面、設定預設值、連接控制項、取得回呼和處理錯誤。

您可以使用 AWS CloudTrail 稽核日誌來取得內嵌儀表板數量、內嵌體驗的使用者和存取速率的相關資訊。

**Topics**
+ [

# 使用 Amazon Quick Sight API 內嵌 Amazon Quick Sight 儀表板
](embedding-dashboards.md)
+ [

# 使用 Amazon Quick Sight APIs 內嵌 Amazon Quick Sight 視覺效果
](embedding-visuals.md)
+ [

# 為已註冊使用者嵌入 Amazon Quick Sight 主控台的完整功能
](embedded-analytics-full-console-for-authenticated-users.md)
+ [

# 在 Amazon Quick Sight 生成式問答體驗中嵌入 Amazon Q
](embedding-gen-bi.md)
+ [

# 內嵌 Amazon Quick Sight Q 搜尋列 （傳統）
](embedding-quicksight-q.md)
+ [

# 使用 GetDashboardEmbedURL 和 GetSessionEmbedURL API 操作內嵌分析
](embedded-analytics-deprecated.md)

# 使用 Amazon Quick Sight API 內嵌 Amazon Quick Sight 儀表板
<a name="embedding-dashboards"></a>

使用下列主題來了解如何使用 Amazon Quick Sight API 內嵌儀表板。

**Topics**
+ [

# 內嵌已註冊使用者的 Amazon Quick Sight 儀表板
](embedded-analytics-dashboards-for-authenticated-users.md)
+ [

# 為匿名 （未註冊） 使用者嵌入 Amazon Quick Sight 儀表板
](embedded-analytics-dashboards-for-everyone.md)
+ [

# 在嵌入式儀表板中啟用執行摘要
](embedded-analytics-genbi-executive-summaries-dashboard.md)

# 內嵌已註冊使用者的 Amazon Quick Sight 儀表板
<a name="embedded-analytics-dashboards-for-authenticated-users"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 API 操作： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` API 操作來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需使用舊 API 操作內嵌的詳細資訊，請參閱[使用 GetDashboardEmbedURL和 GetSessionEmbedURL API 操作內嵌分析](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics-deprecated.html)。


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下列各節中，您可以找到有關如何為 Amazon Quick Sight 註冊使用者設定內嵌 Amazon Quick Sight 儀表板的詳細資訊。

**Topics**
+ [

## 步驟 1：設定許可
](#embedded-dashboards-for-authenticated-users-step-1)
+ [

## 步驟 2：產生帶有身分驗證碼的 URL
](#embedded-dashboards-for-authenticated-users-step-2)
+ [

## 步驟 3：內嵌儀表板 URL
](#embedded-dashboards-for-authenticated-users-step-3)

## 步驟 1：設定許可
<a name="embedded-dashboards-for-authenticated-users-step-1"></a>

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可。這個任務需要有 IAM 的管理存取權。

每個存取儀表板的使用者都會擔任一個角色，為他們提供儀表板的 Amazon Quick Sight 存取權和許可。若要實現這一點，請在 中建立 IAM 角色 AWS 帳戶。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。IAM 角色需要提供許可，以擷取特定使用者集區的內嵌 URL。藉助萬用字元 *\$1*，您可以授予許可，以便為特定命名空間中的所有使用者，或特定命名空間中的使用者子集產生 URL。對於這一點，您新增 `quicksight:GenerateEmbedUrlForRegisteredUser`。

您可以在 IAM 政策中建立條件，以限制開發人員可在 `GenerateEmbedUrlForRegisteredUser` API 操作的 `AllowedDomains` 參數中列出的域。`AllowedDomains` 參數是選用參數。它授予您作為開發人員覆寫**管理 Amazon Quick Sight **選單中設定的靜態網域的選項。您則最多可以列出三個可存取產生之 URL 的域或子網域。然後，此 URL 將嵌入您建立的網站中。只有參數中列出的域可以存取內嵌視覺效果。如果沒有這種情況，您可以在 `AllowedDomains` 參數中列出網際網路上的任何域。

若要限制開發人員可搭配此參數使用的域，請在 IAM 政策中新增 `AllowedEmbeddingDomains` 條件。如需 `AllowedDomains` 參數的詳細資訊，請參閱《*Amazon Quick Sight API 參考*》中的 [GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。

**IAM 條件運算子的安全最佳實務**  
設定不當的 IAM 條件運算子可能會允許透過 URL 變化未經授權存取您的內嵌 Quick 資源。在 IAM 政策中使用 `quicksight:AllowedEmbeddingDomains`條件金鑰時，請使用允許特定網域或拒絕未明確允許的所有網域的條件運算子。如需 IAM 條件運算子的詳細資訊，請參閱《IAM [使用者指南》中的 IAM JSON 政策元素：條件運算子](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
許多不同的 URL 變化可以指向相同的資源。例如，下列 URLs都會解析為相同的內容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的政策使用未考慮這些 URL 變化的運算子，攻擊者可以透過提供同等的 URL 變化來繞過您的限制。  
您必須驗證 IAM 政策是否使用適當的條件運算子來防止繞過漏洞，並確保只有您預期的網域可以存取您的內嵌資源。

下列範例政策提供這些許可。

此外，如果您要建立將成為 Amazon Quick Sight 讀者的第一次使用者，請務必在政策中新增 `quicksight:RegisterUser`許可。

下列範例政策提供許可，以擷取初次成為 Amazon Quick Sight 讀取器之使用者的內嵌 URL。

最後，您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可以代表使用者擔任該角色，並在 Amazon Quick Sight 中佈建使用者。範例信任政策如下所示。

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

------

如需 OpenID Connect 或 SAML 身分驗證的信任政策詳細資訊，請參閱 *IAM 使用者指南*的下列各節：
+ [建立 Web 身分或 OpenID Connect 聯合身分的角色 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [建立 SAML 2.0 聯合身分的角色 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

## 步驟 2：產生帶有身分驗證碼的 URL
<a name="embedded-dashboards-for-authenticated-users-step-2"></a>

在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌的儀表板 URL。如果您打算內嵌 IAM 或 Amazon Quick Sight 身分類型的儀表板，請與使用者共用儀表板。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，它會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

執行這些步驟可確保儀表板的每個檢視器都是在 Amazon Quick Sight 中唯一佈建。它還會強制執行個別使用者設定，例如資料列層級的安全性和參數的動態預設值。

下列範例會代表使用者執行 IAM 身分驗證。此代碼在您的應用程式伺服器上運行。

### Java
<a name="embedded-dashboards-for-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.RegisteredUserDashboardEmbeddingConfiguration;

    /**
    * Class to call QuickSight AWS SDK to get url for dashboard embedding.
    */
    public class GetQuicksightEmbedUrlRegisteredUserDashboardEmbedding {

        private final AmazonQuickSight quickSightClient;

        public GetQuicksightEmbedUrlRegisteredUserDashboardEmbedding() {
            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 dashboardId, // Dashboard 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 out how to get user arn for a QuickSight user.
        ) throws Exception {
            final RegisteredUserEmbeddingExperienceConfiguration experienceConfiguration = new RegisteredUserEmbeddingExperienceConfiguration()
                    .withDashboard(new RegisteredUserDashboardEmbeddingConfiguration().withInitialDashboardId(dashboardId));
            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-dashboards-for-authenticated-users-js"></a>

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

    function generateEmbedUrlForRegisteredUser(
        accountId,
        dashboardId,
        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 getDashboardParams = {
                    "AwsAccountId": accountId,
                    "ExperienceConfiguration": {
                        "Dashboard": {
                            "InitialDashboardId": dashboardId
                        }
                    },
                    "UserArn": userArn,
                    "AllowedDomains": allowedDomains,
                    "SessionLifetimeInMinutes": 600
                };

                const quicksightClient = 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
                    }
                });

                quicksightClient.generateEmbedUrlForRegisteredUser(getDashboardParams, 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);
                    }
                });
            }
        });
    }
```

### Python3
<a name="embedded-dashboards-for-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
# dashboardId: Dashboard 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, dashboardId, 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 = {
                    "Dashboard": {
                        "InitialDashboardId": dashboardId
                    }
                },
                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-dashboards-for-authenticated-users-node"></a>

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
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': { 
            'Dashboard': {
                'InitialDashboardId': '1c1fe111-e2d2-3b30-44ef-a0e111111cde'
            }
        },
        'UserArn': 'REGISTERED_USER_ARN',
        'AllowedDomains': allowedDomains,
        'SessionLifetimeInMinutes': 100
    }, function(err, data) {
        console.log('Errors: ');
        console.log(err);
        console.log('Response: ');
        console.log(data);
    });
```

**Example**  

```
//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...'
            RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' 
        }
```

### .NET/C\$1
<a name="embedded-dashboards-for-authenticated-users-cs"></a>

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
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
                {
                    RegisteredUserDashboardEmbeddingConfiguration registeredUserDashboardEmbeddingConfiguration
                        = new RegisteredUserDashboardEmbeddingConfiguration
                        {
                            InitialDashboardId = "dashboardId"
                        };
                    RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                        = new RegisteredUserEmbeddingExperienceConfiguration
                        {
                            Dashboard = registeredUserDashboardEmbeddingConfiguration
                        };
                        
                    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-dashboards-for-authenticated-users-cli"></a>

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用 SAML 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GenerateEmbedUrlForRegisteredUser` 的許可。如果您正在採取即時方法在使用者第一次開啟儀表板時新增使用者，則該角色也需要啓用 `quicksight:RegisterUser` 的許可。

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

`assume-role` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。如果您使用 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_dashboard_role/john.doe@example.com`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個使用者設定適當的許可。還能避免對使用者存取進行任何調節。*調節*是一項安全功能，可防止相同的使用者從多個位置存取 Amazon Quick Sight。

角色工作階段 ID 也會成為 Amazon Quick Sight 中的使用者名稱。您可以使用此模式提前在 Amazon Quick Sight 中佈建使用者，或在使用者第一次存取儀表板時佈建他們。

以下範例顯示可用來佈建使用者的 CLI 命令。如需 [RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html) 和其他 Amazon Quick Sight API 操作的詳細資訊，請參閱 [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_dashboard_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` 設定他們。相反地，他們應在第一次存取 Amazon Quick Sight 時自動訂閱。若是 Microsoft AD 使用者，您可以使用 `DescribeUser` 取得使用者的 ARN。

使用者第一次存取 Amazon Quick Sight 時，您也可以將此使用者新增至與儀表板共用的群組。以下範例顯示用於將使用者新增至群組的 CLI 命令。

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

您現在擁有的應用程式使用者也是 Amazon Quick Sight 的使用者，以及有權存取儀表板的使用者。

最後，為了取得儀表板的簽章 URL，請從應用程式伺服器呼叫 `generate-embed-url-for-registered-user`。這會傳回可嵌入的儀表板 URL。下列範例示範如何使用伺服器端呼叫為透過 AWS Managed Microsoft AD 或單一登入 (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_visual_role/embeddingsession \
        --allowed-domains '["domain1","domain2"]' \
        --experience-configuration Dashboard={InitialDashboardId=1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89}
```

如需使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

## 步驟 3：內嵌儀表板 URL
<a name="embedded-dashboards-for-authenticated-users-step-3"></a>

在下一節中，您可以了解如何使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 在網站或應用程式頁面的步驟 3 中內嵌儀表板 URL。您可以使用此 SDK 執行以下操作：
+ 將儀表板放在 HTML 頁面。
+ 將參數傳遞到儀表板。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

呼叫 `GenerateEmbedUrlForRegisteredUser` API 操作以產生可嵌入應用程式的 URL。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期最長為 10 小時。此 API 操作提供的 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/embed/12345/dashboards/67890..",
        "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
    }
```

使用 [Amazon Quick Sight 內嵌 SDK ](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)或將此 URL 新增至 iframe，將此儀表板內嵌在您的網頁中。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制儀表板中的參數，並根據頁面載入完成和錯誤接收回呼。

即將託管內嵌式儀表板的域必須列在*允許清單*中，此為您的 Quick 訂閱已獲核准的域清單。這項要求將使未獲核准的網域無法託管嵌入儀表板，進而保護您的資料。如需為內嵌儀表板新增網域的詳細資訊，請參閱[使用 Amazon Quick Sight API 在執行時間允許列出網域](https://docs.aws.amazon.com/quicksight/latest/user/embedding-run-time.html)。

下列範例示範如何使用產生的 URL。此代碼在您的應用程式伺服器上生成。

### SDK 2.0
<a name="embedded-dashboards-for-authenticated-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Dashboard 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 embedDashboard = 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>',
                    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 = {
                    parameters: [
                        {
                            Name: 'country',
                            Values: [
                                'United States'
                            ],
                        },
                        {
                            Name: 'states',
                            Values: [
                                'California',
                                'Washington'
                            ]
                        }
                    ],
                    locale: "en-US",
                    sheetOptions: {
                        initialSheetId: '<YOUR_SHEETID>',
                        singleSheet: false,                        
                        emitSizeChangedEventOnSheetChange: false,
                    },
                    toolbarOptions: {
                        export: false,
                        undoRedo: false,
                        reset: false
                    },
                    attributionOptions: {
                        overlayContent: false,
                    },
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'CONTENT_LOADED': {
                                console.log("All visuals are loaded. The title of the document:", messageEvent.message.title);
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Error occurred while rendering the experience. Error code:", messageEvent.message.errorCode);
                                break;
                            }
                            case 'PARAMETERS_CHANGED': {
                                console.log("Parameters changed. Changed parameters:", messageEvent.message.changedParameters);
                                break;
                            }
                            case 'SELECTED_SHEET_CHANGED': {
                                console.log("Selected sheet changed. Selected sheet:", messageEvent.message.selectedSheet);
                                break;
                            }
                            case 'SIZE_CHANGED': {
                                console.log("Size changed. New dimensions:", messageEvent.message);
                                break;
                            }
                            case 'MODAL_OPENED': {
                                window.scrollTo({
                                    top: 0 // iframe top position
                                });
                                break;
                            }
                        }
                    },
                };
                const embeddedDashboardExperience = await embeddingContext.embedDashboard(frameOptions, contentOptions);

                const selectCountryElement = document.getElementById('country');
                selectCountryElement.addEventListener('change', (event) => {
                    embeddedDashboardExperience.setParameters([
                        {
                            Name: 'country',
                            Values: event.target.value
                        }
                    ]);
                });
            };
        </script>
    </head>

    <body onload="embedDashboard()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="experience-container"></div>
    </body>

</html>
```

### SDK 1.0
<a name="embedded-dashboards-for-authenticated-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Basic Embed</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.0.15/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            var dashboard
            function onDashboardLoad(payload) {
                console.log("Do something when the dashboard is fully loaded.");
            }

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

            function embedDashboard() {
                var containerDiv = document.getElementById("embeddingContainer");
                var options = {
                    // replace this dummy url with the one generated via embedding API
                    url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",
                    container: containerDiv,
                    parameters: {
                        country: "United States"
                    },
                    scrolling: "no",
                    height: "700px",
                    width: "1000px",
                    locale: "en-US",
                    footerPaddingEnabled: true
                };
                dashboard = QuickSightEmbedding.embedDashboard(options);
                dashboard.on("error", onError);
                dashboard.on("load", onDashboardLoad);
            }

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

    <body onload="embedDashboard()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country" onchange="onCountryChange(this)">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="embeddingContainer"></div>
    </body>

</html>
```

若要讓此範例運作，請務必使用 Amazon Quick Sight 內嵌 SDK，使用 JavaScript 在您的網站上載入內嵌儀表板。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

# 為匿名 （未註冊） 使用者嵌入 Amazon Quick Sight 儀表板
<a name="embedded-analytics-dashboards-for-everyone"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 API 操作： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` API 操作來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需使用舊 API 操作內嵌的詳細資訊，請參閱[使用 GetDashboardEmbedURL和 GetSessionEmbedURL API 操作內嵌分析](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics-deprecated.html)。


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下列各節中，您可以找到有關如何為匿名 （未註冊） 使用者設定內嵌 Amazon Quick Sight 儀表板的詳細資訊。

**Topics**
+ [

## 步驟 1：設定許可
](#embedded-analytics-dashboards-with-anonymous-users-step-1)
+ [

## 步驟 2：產生帶有身分驗證碼的 URL
](#embedded-analytics-dashboards-with-anonymous-users-step-2)
+ [

## 步驟 3：內嵌儀表板 URL
](#embedded-analytics-dashboards-with-anonymous-users-step-3)

## 步驟 1：設定許可
<a name="embedded-analytics-dashboards-with-anonymous-users-step-1"></a>


|  | 
| --- |
|  適用於：企業版本  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可。這個任務需要有 IAM 的管理存取權。

每個存取儀表板的使用者都會擔任一個角色，為他們提供儀表板的 Amazon Quick Sight 存取權和許可。若要實現這一點，請在 中建立 IAM 角色 AWS 帳戶。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。

您可以在 IAM 政策中建立條件，以限制開發人員可在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 參數中列出的域。`AllowedDomains` 參數是選用參數。它授予身為開發人員的選項，讓您覆寫在**管理 Amazon Quick Sight **選單中設定的靜態網域。您則最多可以列出三個可存取產生之 URL 的域或子網域。然後，此 URL 將嵌入您建立的網站中。只有參數中列出的域可以存取內嵌式儀表板。如果沒有這種情況，您可以在 `AllowedDomains` 參數中列出網際網路上的任何域。

若要限制開發人員可搭配此參數使用的域，請在 IAM 政策中新增 `AllowedEmbeddingDomains` 條件。如需 `AllowedDomains` 參數的詳細資訊，請參閱《*Amazon Quick Sight API 參考*》中的 [GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)。

**IAM 條件運算子的安全最佳實務**  
設定不當的 IAM 條件運算子可能會允許透過 URL 變化未經授權存取您的內嵌 Quick 資源。在 IAM 政策中使用 `quicksight:AllowedEmbeddingDomains`條件金鑰時，請使用允許特定網域或拒絕未明確允許的所有網域的條件運算子。如需 IAM 條件運算子的詳細資訊，請參閱《IAM [使用者指南》中的 IAM JSON 政策元素：條件運算子](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
許多不同的 URL 變化可以指向相同的資源。例如，下列 URLs都會解析為相同的內容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的政策使用未考慮這些 URL 變化的運算子，攻擊者可以透過提供同等的 URL 變化來繞過您的限制。  
您必須驗證 IAM 政策是否使用適當的條件運算子來防止繞過漏洞，並確保只有您預期的網域可以存取您的內嵌資源。

下列範例政策提供搭配 `GenerateEmbedUrlForAnonymousUser` 使用的許可。若要使這種方法生效，您的 AWS 帳戶還需要一個工作階段套件。或工作階段容量定價。否則，當使用者嘗試存取儀表板時，會傳回錯誤 `UnsupportedPricingPlanException`。

您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可代表使用者擔任該角色，並開啟儀表板。範例信任政策如下所示。

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

------

如需有關信任政策的詳細資訊，請參閱**《IAM 使用者指南》中的[ IAM 中的臨時安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。

## 步驟 2：產生帶有身分驗證碼的 URL
<a name="embedded-analytics-dashboards-with-anonymous-users-step-2"></a>


|  | 
| --- |
|  適用於：企業版本  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下一章節，您可以了解如何在您的應用程式伺服器上代表匿名訪客進行身分驗證，以及取得可內嵌的儀表板 URL。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，它會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

下列範例會代表使用者執行 IAM 身分驗證。它傳遞識別符當作唯一的角色工作階段 ID。此代碼在您的應用程式伺服器上運行。

### Java
<a name="embedded-analytics-dashboards-with-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.RegisteredUserDashboardEmbeddingConfiguration;
    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 initialDashboardId, // DASHBOARD ID TO WHICH THE CONSTRUCTED URL POINTS.
            final String namespace, // ANONYMOUS EMBEDDING REQUIRES SPECIFYING A VALID NAMESPACE FOR WHICH YOU WANT THE EMBEDDING URL
            final List<String> authorizedResourceArns, // DASHBOARD 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();
            AnonymousUserDashboardEmbeddingConfiguration dashboardConfiguration = new AnonymousUserDashboardEmbeddingConfiguration();
            dashboardConfiguration.setInitialDashboardId(initialDashboardId);
            experienceConfiguration.setDashboard(dashboardConfiguration);

            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 dashboardEmbedUrl = quickSightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserRequest);

            return dashboardEmbedUrl.getEmbedUrl();
        }

    }
```

### JavaScript
<a name="embedded-analytics-dashboards-with-anonymous-users-js"></a>

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

function generateEmbedUrlForAnonymousUser(
accountId, // YOUR AWS ACCOUNT ID
initialDashboardId, // DASHBOARD ID TO WHICH THE CONSTRUCTED URL POINTS
quicksightNamespace, // VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
authorizedResourceArns, // DASHBOARD ARN LIST TO EMBED
allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
sessionTags, // SESSION TAGS USED FOR ROW-LEVEL SECURITY
generateEmbedUrlForAnonymousUserCallback, // GENERATEEMBEDURLFORANONYMOUSUSER SUCCESS CALLBACK METHOD
errorCallback // GENERATEEMBEDURLFORANONYMOUSUSER ERROR CALLBACK METHOD
) {
const experienceConfiguration = {
    "DashboardVisual": {
        "InitialDashboardVisualId": {
            "DashboardId": "dashboard_id",
            "SheetId": "sheet_id",
            "VisualId": "visual_id"
        }
    }
};

const generateEmbedUrlForAnonymousUserParams = {
    "AwsAccountId": accountId,
    "Namespace": quicksightNamespace,
    "AuthorizedResourceArns": authorizedResourceArns,
    "AllowedDomains": allowedDomains,
    "ExperienceConfiguration": experienceConfiguration,
    "SessionTags": sessionTags,
    "SessionLifetimeInMinutes": 600
};

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

quicksightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserParams, 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 THIS API
                "Access-Control-Allow-Headers": "Content-Type"
            },
            "body": JSON.stringify(data),
            "isBase64Encoded": false
        }
        generateEmbedUrlForAnonymousUserCallback(result);
    }
});
}
```

### Python3
<a name="embedded-analytics-dashboards-with-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
# quicksightNamespace: VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
# authorizedResourceArns: DASHBOARD ARN LIST TO EMBED
# allowedDomains: RUNTIME ALLOWED DOMAINS FOR EMBEDDING
# dashboardId: DASHBOARD ID TO WHICH THE CONSTRUCTED URL POINTS
# sessionTags: SESSION TAGS USED FOR ROW-LEVEL SECURITY
def generateEmbedUrlForAnonymousUser(accountId, quicksightNamespace, authorizedResourceArns, allowedDomains, dashboardId, sessionTags):
try:
    response = quicksightClient.generate_embed_url_for_anonymous_user(
        AwsAccountId = accountId,
        Namespace = quicksightNamespace,
        AuthorizedResourceArns = authorizedResourceArns,
        AllowedDomains = allowedDomains,
            ExperienceConfiguration = {
                "Dashboard": {
                    "InitialDashboardId": dashboardId
                }
            },
        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-dashboards-with-anonymous-users-node"></a>

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
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.generateEmbedUrlForAnonymousUser({
        'AwsAccountId': '111122223333',
        'Namespace' : 'default',
        'AuthorizedResourceArns': authorizedResourceArns,
        'AllowedDomains': allowedDomains,
        'ExperienceConfiguration': experienceConfiguration,
        'SessionTags': sessionTags,
        'SessionLifetimeInMinutes': 600

    }, function(err, data) {
        console.log('Errors: ');
        console.log(err);
        console.log('Response: ');
        console.log(data);
    });
```

**Example**  

```
//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..',
            RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' 
        }
```

### .NET/C\$1
<a name="embedded-analytics-dashboards-with-anonymous-users-cs"></a>

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

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

    var quicksightClient = new AmazonQuickSightClient(
        AccessKey,
        SecretAccessKey,
        sessionToken,
        Amazon.RegionEndpoint.USEast1);
        
    try
    {
        Console.WriteLine(
            quicksightClient.GenerateEmbedUrlForAnonymousUserAsync(new GenerateEmbedUrlForAnonymousUserRequest
            {
                AwsAccountId = "111122223333",
                Namespace = default,
                AuthorizedResourceArns = authorizedResourceArns,
                AllowedDomains = allowedDomains,
                ExperienceConfiguration = experienceConfiguration,
                SessionTags = sessionTags,
                SessionLifetimeInMinutes = 600,
            }).Result.EmbedUrl
        );
    } catch (Exception ex) {
        Console.WriteLine(ex.Message);
    }
```

### AWS CLI
<a name="embedded-analytics-dashboards-with-anonymous-users-cli"></a>

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用安全性聲明標記語言 (SAML) 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GenerateEmbedUrlForAnonymousUser` 的許可。

```
aws sts assume-role \
    --role-arn "arn:aws:iam::11112222333:role/QuickSightEmbeddingAnonymousPolicy" \
    --role-session-name anonymous caller
```

`assume-role` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。如果您使用 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_dashboard_role/QuickSightEmbeddingAnonymousPolicy`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個訪問使用者設定適當的許可。它還使每個會話獨立且不同。如果您正在使用 Web 伺服器陣列 (例如負載平衡)，且工作階段重新連線到不同的伺服器，則會開始新的工作階段。

為了取得儀表板的簽章 URL，請從應用程式伺服器呼叫 `generate-embed-url-for-anynymous-user`。這會傳回可嵌入的儀表板 URL。下列範例會顯示如何使用伺服器端呼叫，針對匿名造訪您的 Web 入口網站或應用程式的使用者，產生內嵌式儀表板的 URL。

```
aws quicksight generate-embed-url-for-anonymous-user \
--aws-account-id 111122223333 \
--namespace default-or-something-else \
--session-lifetime-in-minutes 15 \
--authorized-resource-arns '["dashboard-arn-1","dashboard-arn-2"]' \
--allowed-domains '["domain1","domain2"]' \
--session-tags '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]' \
--experience-configuration 'DashboardVisual={InitialDashboardVisualId={DashboardId=dashboard_id,SheetId=sheet_id,VisualId=visual_id}}'
```

如需使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

## 步驟 3：內嵌儀表板 URL
<a name="embedded-analytics-dashboards-with-anonymous-users-step-3"></a>


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下一節中，您可以了解如何使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript)，在網站或應用程式頁面的步驟 2 中內嵌儀表板 URL。您可以使用此 SDK 執行以下操作：
+ 將儀表板放在 HTML 頁面。
+ 將參數傳遞到儀表板。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

呼叫 `GenerateEmbedUrlForAnynymousUser` API 操作以產生可嵌入應用程式的 URL。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期為 10 小時。此 API 操作提供的 URL 附有可啟用單一登入工作階段的 `auth_code`。

以下是 `generate-embed-url-for-anynymous-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/embed/12345/dashboards/67890..",
            "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
        }
```

使用 [Amazon Quick Sight 內嵌 SDK ](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)或將此 URL 新增至 iframe，將此儀表板內嵌在您的網頁中。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制儀表板中的參數，並根據頁面載入完成和錯誤接收回呼。

即將託管內嵌式儀表板的域必須列在*允許清單*中，此為您的 Quick 訂閱已獲核准的域清單。這項要求將使未獲核准的網域無法託管嵌入儀表板，進而保護您的資料。如需為內嵌儀表板新增網域的詳細資訊，請參閱[使用 Amazon Quick Sight API 在執行時間允許列出網域](https://docs.aws.amazon.com/quicksight/latest/user/embedding-run-time.html)。

下列範例示範如何使用產生的 URL。此代碼駐留在您的應用程式伺服器上。

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

```
<!DOCTYPE html>
<html>

<head>
    <title>Dashboard 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 embedDashboard = 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>',
                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 = {
                parameters: [
                    {
                        Name: 'country',
                        Values: [
                            'United States'
                        ],
                    },
                    {
                        Name: 'states',
                        Values: [
                            'California',
                            'Washington'
                        ]
                    }
                ],
                locale: "en-US",
                sheetOptions: {
                    initialSheetId: '<YOUR_SHEETID>',
                    singleSheet: false,                        
                    emitSizeChangedEventOnSheetChange: false,
                },
                toolbarOptions: {
                    export: false,
                    undoRedo: false,
                    reset: false
                },
                attributionOptions: {
                    overlayContent: false,
                },
                onMessage: async (messageEvent, experienceMetadata) => {
                    switch (messageEvent.eventName) {
                        case 'CONTENT_LOADED': {
                            console.log("All visuals are loaded. The title of the document:", messageEvent.message.title);
                            break;
                        }
                        case 'ERROR_OCCURRED': {
                            console.log("Error occurred while rendering the experience. Error code:", messageEvent.message.errorCode);
                            break;
                        }
                        case 'PARAMETERS_CHANGED': {
                            console.log("Parameters changed. Changed parameters:", messageEvent.message.changedParameters);
                            break;
                        }
                        case 'SELECTED_SHEET_CHANGED': {
                            console.log("Selected sheet changed. Selected sheet:", messageEvent.message.selectedSheet);
                            break;
                        }
                        case 'SIZE_CHANGED': {
                            console.log("Size changed. New dimensions:", messageEvent.message);
                            break;
                        }
                        case 'MODAL_OPENED': {
                            window.scrollTo({
                                top: 0 // iframe top position
                            });
                            break;
                        }
                    }
                },
            };
            const embeddedDashboardExperience = await embeddingContext.embedDashboard(frameOptions, contentOptions);

            const selectCountryElement = document.getElementById('country');
            selectCountryElement.addEventListener('change', (event) => {
                embeddedDashboardExperience.setParameters([
                    {
                        Name: 'country',
                        Values: event.target.value
                    }
                ]);
            });
        };
    </script>
</head>

<body onload="embedDashboard()">
    <span>
        <label for="country">Country</label>
        <select id="country" name="country">
            <option value="United States">United States</option>
            <option value="Mexico">Mexico</option>
            <option value="Canada">Canada</option>
        </select>
    </span>
    <div id="experience-container"></div>
</body>

</html>
```

### SDK 1.0
<a name="embedded-analytics-dashboards-with-anonymous-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

<head>
    <title>Basic Embed</title>
    <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.0.15/dist/quicksight-embedding-js-sdk.min.js"></script>
    <script type="text/javascript">
        var dashboard
        function onDashboardLoad(payload) {
            console.log("Do something when the dashboard is fully loaded.");
        }

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

        function embedDashboard() {
            var containerDiv = document.getElementById("embeddingContainer");
            var options = {
                // replace this dummy url with the one generated via embedding API
                url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",
                container: containerDiv,
                parameters: {
                    country: "United States"
                },
                scrolling: "no",
                height: "700px",
                width: "1000px",
                locale: "en-US",
                footerPaddingEnabled: true
            };
            dashboard = QuickSightEmbedding.embedDashboard(options);
            dashboard.on("error", onError);
            dashboard.on("load", onDashboardLoad);
        }

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

<body onload="embedDashboard()">
    <span>
        <label for="country">Country</label>
        <select id="country" name="country" onchange="onCountryChange(this)">
            <option value="United States">United States</option>
            <option value="Mexico">Mexico</option>
            <option value="Canada">Canada</option>
        </select>
    </span>
    <div id="embeddingContainer"></div>
</body>

</html>
```

若要讓此範例運作，請務必使用 Amazon Quick Sight 內嵌 SDK，使用 JavaScript 在您的網站上載入內嵌儀表板。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)：// 下載最新的 Amazon Quick Sight 內嵌 SDK 版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

# 在嵌入式儀表板中啟用執行摘要
<a name="embedded-analytics-genbi-executive-summaries-dashboard"></a>


|  | 
| --- |
|  適用於：企業版本  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

您可以在您的嵌入式儀表板中啟用執行摘要。啟用時，已註冊的使用者可產生執行摘要，提供 Amazon Quick Sight 為儀表板產生之所有洞見的摘要。執行摘要可讓讀者更輕鬆地找到有關儀表板的關鍵洞察與資訊。如需使用者如何產生儀表板的執行摘要的詳細資訊，請參閱[產生 Amazon Quick Sight 儀表板的執行摘要](https://docs.aws.amazon.com/quicksight/latest/user/use-executive-summaries.html)。

**注意**  
僅已註冊使用者在嵌入式儀表板可使用執行摘要，匿名或未註冊使用者在嵌入式儀表板中無法使用此功能。

**在嵌入式儀表板中為已註冊使用者啟用執行摘要**
+ 請依照[內嵌 Amazon Quick Sight 儀表板中的步驟，讓已註冊的使用者](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics-dashboards-for-authenticated-users.html)內嵌具有下列變更的儀表板：

  1. 在步驟 2 中產生 URL 時，請在 [GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html) 或 [GenerateEmbedUrlForRegisteredUserWithIdentity](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUserWithIdentity.html) 中的 `ExecutiveSummary` 參數中設定 `Enabled: true`，如下列範例所示：

     ```
     ExperienceConfiguration: {
             Dashboard: {
                 InitialDashboardId: dashboard_id,
                 FeatureConfigurations: {
                     AmazonQInQuickSight: {
                         ExecutiveSummary: {
                             Enabled: true
                         }
                     }
                 }
             }
         }
     }
     ```

  1. 在步驟 3 中使用 Amazon Quick Sight 內嵌 SDK 內嵌儀表板 URL 時，請在 `executiveSummary: true`中設定 `contentOptions`，如下列範例所示：

     ```
     const contentOptions = {
         toolbarOptions: {
             executiveSummary: true
         }
     };
     ```

# 使用 Amazon Quick Sight APIs 內嵌 Amazon Quick Sight 視覺效果
<a name="embedding-visuals"></a>

您可以使用 Amazon Quick Sight API，在應用程式中嵌入屬於已發佈儀表板一部分的個別視覺效果。

**Topics**
+ [

# 內嵌已註冊使用者的 Amazon Quick Sight 視覺效果
](embedded-analytics-visuals-for-authenticated-users.md)
+ [

# 為匿名 （未註冊） 使用者嵌入 Amazon Quick Sight 視覺效果
](embedded-analytics-visuals-for-everyone.md)

# 內嵌已註冊使用者的 Amazon Quick Sight 視覺效果
<a name="embedded-analytics-visuals-for-authenticated-users"></a>


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下列各節中，您可以找到如何為 Amazon Quick Sight 註冊使用者設定內嵌 Amazon Quick Sight 視覺效果的詳細資訊。

**Topics**
+ [

## 步驟 1：設定許可
](#embedded-visuals-for-authenticated-users-step-1)
+ [

## 步驟 2：產生帶有身分驗證碼的 URL
](#embedded-visuals-for-authenticated-users-step-2)
+ [

## 步驟 3：內嵌視覺效果 URL
](#embedded-visuals-for-authenticated-users-step-3)

## 步驟 1：設定許可
<a name="embedded-visuals-for-authenticated-users-step-1"></a>

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可。這個任務需要有 IAM 的管理存取權。

每個存取視覺效果的使用者都會擔任一個角色，為他們提供視覺效果的 Amazon Quick Sight 存取權和許可。若要實現此目的，請在 中建立 IAM 角色 AWS 帳戶。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。IAM 角色需要提供許可，以擷取特定使用者集區的內嵌 URL。藉助萬用字元 *\$1*，您可以授予許可，以便為特定命名空間中的所有使用者，或特定命名空間中的使用者子集產生 URL。對於這一點，您新增 `quicksight:GenerateEmbedUrlForRegisteredUser`。

您可以在 IAM 政策中建立條件，以限制開發人員可在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 參數中列出的域。`AllowedDomains` 參數是選用參數。它授予您作為開發人員覆寫**管理 Amazon Quick Sight **選單中設定的靜態網域的選項。您則最多可以列出三個可存取產生之 URL 的域或子網域。然後，此 URL 將嵌入您建立的網站中。只有參數中列出的域可以存取內嵌式儀表板。如果沒有這種情況，您可以在 `AllowedDomains` 參數中列出網際網路上的任何域。

若要限制開發人員可搭配此參數使用的域，請在 IAM 政策中新增 `AllowedEmbeddingDomains` 條件。如需 `AllowedDomains` 參數的詳細資訊，請參閱《*Amazon Quick Sight API 參考*》中的 [GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。

**IAM 條件運算子的安全最佳實務**  
設定不當的 IAM 條件運算子可能會允許透過 URL 變化未經授權存取您的內嵌 Quick 資源。在 IAM 政策中使用 `quicksight:AllowedEmbeddingDomains`條件金鑰時，請使用允許特定網域或拒絕未特別允許的所有網域的條件運算子。如需 IAM 條件運算子的詳細資訊，請參閱《IAM [使用者指南》中的 IAM JSON 政策元素：條件運算子](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
許多不同的 URL 變化可以指向相同的資源。例如，下列 URLs全部解析為相同的內容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的政策使用未考慮這些 URL 變化的運算子，攻擊者可以透過提供同等的 URL 變化來繞過您的限制。  
您必須驗證 IAM 政策是否使用適當的條件運算子來防止繞過漏洞，並確保只有預期的網域可以存取您的內嵌資源。

下列範例政策提供這些許可。

此外，如果您要建立將成為 Amazon Quick Sight 讀者的第一次使用者，請務必在政策中新增 `quicksight:RegisterUser`許可。

下列範例政策提供許可，以擷取第一次成為 Amazon Quick Sight 讀取器之使用者的內嵌 URL。

最後，您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可以代表使用者擔任該角色，並在 Amazon Quick Sight 中佈建使用者。範例信任政策如下所示。

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

------

如需 OpenID Connect 或 SAML 身分驗證的信任政策詳細資訊，請參閱 *IAM 使用者指南*的下列各節：
+ [建立 Web 身分或 OpenID Connect 聯合身分的角色 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [建立 SAML 2.0 聯合身分的角色 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

## 步驟 2：產生帶有身分驗證碼的 URL
<a name="embedded-visuals-for-authenticated-users-step-2"></a>

在下一節中，您可以了解如何驗證 Amazon Quick Sight 使用者，並在應用程式伺服器上取得可內嵌的視覺化 URL。如果您打算內嵌 IAM 或 Amazon Quick Sight 身分類型的視覺效果，請與 Amazon Quick Sight 使用者共用視覺效果。

當 Amazon Quick Sight 使用者存取您的應用程式時，應用程式會代表 Amazon Quick Sight 使用者擔任 IAM 角色。然後，如果該 Amazon Quick Sight 使用者尚未存在，它會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

執行所述的步驟可確保視覺效果的每個檢視器在 Amazon Quick Sight 中唯一佈建。它還會強制執行個別使用者設定，例如資料列層級的安全性和參數的動態預設值。

下列範例代表 Amazon Quick Sight 使用者執行 IAM 身分驗證。此代碼在您的應用程式伺服器上運行。

### Java
<a name="embedded-visuals-for-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.DashboardVisualId;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserResult;
import com.amazonaws.services.quicksight.model.RegisteredUserDashboardVisualEmbeddingConfiguration;
import com.amazonaws.services.quicksight.model.RegisteredUserEmbeddingExperienceConfiguration;

import java.util.List;

/**
 * Class to call QuickSight AWS SDK to get url for Visual embedding.
 */
public class GenerateEmbedUrlForRegisteredUserTest {

    private final AmazonQuickSight quickSightClient;

    public GenerateEmbedUrlForRegisteredUserTest() {
        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 getEmbedUrl(
            final String accountId, // AWS Account ID
            final String dashboardId, // Dashboard ID of the dashboard to embed
            final String sheetId, // Sheet ID of the sheet to embed
            final String visualId, // Visual ID of the visual to embed
            final List<String> allowedDomains, // Runtime allowed domains for embedding
            final String userArn // Registered user arn of the user that you want to provide embedded visual. Refer to Get Embed Url section in developer portal to find out how to get user arn for a QuickSight user.
    ) throws Exception {
        final DashboardVisualId dashboardVisual = new DashboardVisualId()
            .withDashboardId(dashboardId)
            .withSheetId(sheetId)
            .withVisualId(visualId);
        final RegisteredUserDashboardVisualEmbeddingConfiguration registeredUserDashboardVisualEmbeddingConfiguration
            = new RegisteredUserDashboardVisualEmbeddingConfiguration()
                .withInitialDashboardVisualId(dashboardVisual);
        final RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
            = new RegisteredUserEmbeddingExperienceConfiguration()
                .withDashboardVisual(registeredUserDashboardVisualEmbeddingConfiguration);
        final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest
            = new GenerateEmbedUrlForRegisteredUserRequest()
                .withAwsAccountId(accountId)
                .withUserArn(userArn)
                .withExperienceConfiguration(registeredUserEmbeddingExperienceConfiguration)
                .withAllowedDomains(allowedDomains);

        final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);

        return generateEmbedUrlForRegisteredUserResult.getEmbedUrl();
    }
}
```

### JavaScript
<a name="embedded-visuals-for-authenticated-users-js"></a>

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

function generateEmbedUrlForRegisteredUser(
    accountId, // Your AWS account ID
    dashboardId, // Dashboard ID to which the constructed URL points
    sheetId, // Sheet ID to which the constructed URL points
    visualId, // Visual ID to which the constructed URL points
    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 getDashboardParams = {
                "AwsAccountId": accountId,
                "ExperienceConfiguration": {
                    "DashboardVisual": {
                        "InitialDashboardVisualId": {
                            "DashboardId": dashboardId,
                            "SheetId": sheetId,
                            "VisualId": visualId
                        }
                    }
                },
                "UserArn": userArn,
                "AllowedDomains": allowedDomains,
                "SessionLifetimeInMinutes": 600
            };

            const quicksightGetDashboard = 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
                }
            });

            quicksightGetDashboard.generateEmbedUrlForRegisteredUser(getDashboardParams, 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);
                }
            });
        }
    });
}
```

### Python3
<a name="embedded-visuals-for-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
# dashboardId: Dashboard ID to embed
# sheetId: SHEET ID to embed from the dashboard 
# visualId: Id for the Visual you want to embedded from the dashboard sheet. 
# 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, dashboardId, sheetId, visualId, 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 = {
                    'DashboardVisual': {
                        'InitialDashboardVisualId': {
                            'DashboardId': dashboardId,
                            'SheetId': sheetId,
                            'VisualId': visualId
                        }
                    },
                },
                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-visuals-for-authenticated-users-node"></a>

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
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': { 
        'DashboardVisual': {
            'InitialDashboardVisualId': {
                'DashboardId': 'dashboard_id',
                'SheetId': 'sheet_id',
                'VisualId': 'visual_id'
            }
        }
    },
    'UserArn': 'REGISTERED_USER_ARN',
    'AllowedDomains': allowedDomains,
    'SessionLifetimeInMinutes': 100
}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

**Example**  

```
//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/C\$1
<a name="embedded-visuals-for-authenticated-users-cs"></a>

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
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
            {
                DashboardVisualId dashboardVisual = new DashboardVisualId
                {
                    DashboardId = "dashboard_id",
                    SheetId = "sheet_id",
                    VisualId = "visual_id"
                };

                RegisteredUserDashboardVisualEmbeddingConfiguration registeredUserDashboardVisualEmbeddingConfiguration
                    = new RegisteredUserDashboardVisualEmbeddingConfiguration
                    {
                        InitialDashboardVisualId = dashboardVisual                        
                    };               
                    
                RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                    = new RegisteredUserEmbeddingExperienceConfiguration
                    {
                        DashboardVisual = registeredUserDashboardVisualEmbeddingConfiguration
                    };
                    
                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-visuals-for-authenticated-users-cli"></a>

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用 SAML 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GenerateEmbedUrlForRegisteredUser` 的許可。如果您正在採取即時方法在使用者第一次開啟儀表板時新增使用者，則該角色也需要啓用 `quicksight:RegisterUser` 的許可。

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

`assume-role` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。如果您使用 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_visual_role/john.doe@example.com`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個使用者設定適當的許可。還能避免對使用者存取進行任何調節。*調節*是一項安全功能，可防止相同的使用者從多個位置存取 Amazon Quick Sight。

角色工作階段 ID 也會成為 Amazon Quick Sight 中的使用者名稱。您可以使用此模式提前在 Amazon Quick Sight 中佈建使用者，或在使用者第一次存取儀表板時佈建他們。

以下範例顯示可用來佈建使用者的 CLI 命令。如需 [RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html) 和其他 Amazon Quick Sight API 操作的詳細資訊，請參閱 [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_visual_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` 設定他們。相反地，他們應在第一次存取 Amazon Quick Sight 時自動訂閱。若是 Microsoft AD 使用者，您可以使用 `DescribeUser` 取得使用者的 ARN。

使用者第一次存取 Amazon Quick Sight 時，您也可以將此使用者新增至共用視覺效果的群組。以下範例顯示用於將使用者新增至群組的 CLI 命令。

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

您現在擁有的應用程式使用者，同時也是 Amazon Quick Sight 的使用者，而且可存取視覺效果。

最後，為了取得視覺效果的簽章 URL，請從應用程式伺服器呼叫 `generate-embed-url-for-registered-user`。這會傳回可內嵌的視覺效果 URL。下列範例示範如何使用伺服器端呼叫為透過 AWS Managed Microsoft AD 或單一登入 (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_visual_role/embeddingsession \
    --allowed-domains '["domain1","domain2"]' \
    --experience-configuration 'DashboardVisual={InitialDashboardVisualId={DashboardId=dashboard_id,SheetId=sheet_id,VisualId=visual_id}}'
```

如需使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

## 步驟 3：內嵌視覺效果 URL
<a name="embedded-visuals-for-authenticated-users-step-3"></a>

在下一節中，您可以了解如何使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript)，在網站或應用程式頁面中嵌入步驟 3 的視覺化 URL。您可以使用此 SDK 執行以下操作：
+ 將視覺效果放置在 HTML 頁面上。
+ 將參數傳遞到視覺效果中。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

呼叫 `GenerateEmbedUrlForRegisteredUser` API 操作以產生可嵌入應用程式的 URL。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期最長為 10 小時。此 API 操作提供的 URL 附有可啟用單一登入工作階段的 `auth_code`。

以下是 `generate-embed-url-for-registered-user` 的回應範例。此範例中`quicksightdomain`的 是您用來存取 Amazon Quick Sight 帳戶的 URL。

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

使用 [Amazon Quick Sight 內嵌 SDK 或將此 URL 新增至 iframe，將此視覺效果內嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)在您的網頁中。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制視覺效果中的參數，並根據頁面載入完成和錯誤接收回呼。

將託管內嵌視覺效果和儀表板的網域必須列在*允許清單*上，即 Quick 訂閱的已核准網域清單。這項要求將使未獲核准的域無法託管內嵌視覺效果和儀表板，進而保護您的資料。如需為內嵌視覺效果和儀表板新增網域的詳細資訊，請參閱[使用 Amazon Quick Sight API 在執行時間允許列出網域](https://docs.aws.amazon.com/quicksight/latest/user/embedding-run-time.html)。

下列範例示範如何使用產生的 URL。此代碼在您的應用程式伺服器上生成。

### SDK 2.0
<a name="embedded-visuals-for-authenticated-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Visual 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 embedVisual = 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 = {
                    parameters: [
                        {
                            Name: 'country',
                            Values: ['United States'],
                        },
                        {
                            Name: 'states',
                            Values: [
                                'California',
                                'Washington'
                            ]
                        }
                    ],
                    locale: "en-US",
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'CONTENT_LOADED': {
                                console.log("All visuals are loaded. The title of the document:", messageEvent.message.title);
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Error occurred while rendering the experience. Error code:", messageEvent.message.errorCode);
                                break;
                            }
                            case 'PARAMETERS_CHANGED': {
                                console.log("Parameters changed. Changed parameters:", messageEvent.message.changedParameters);
                                break;
                            }
                            case 'SIZE_CHANGED': {
                                console.log("Size changed. New dimensions:", messageEvent.message);
                                break;
                            }
                        }
                    },
                };
                const embeddedVisualExperience = await embeddingContext.embedVisual(frameOptions, contentOptions);

                const selectCountryElement = document.getElementById('country');
                selectCountryElement.addEventListener('change', (event) => {
                    embeddedVisualExperience.setParameters([
                        {
                            Name: 'country',
                            Values: event.target.value
                        }
                    ]);
                });
            };
        </script>
    </head>

    <body onload="embedVisual()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="experience-container"></div>
    </body>

</html>
```

### SDK 1.0
<a name="embedded-visuals-for-authenticated-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Visual Embedding Example</title>
        <!-- You can download the latest QuickSight embedding SDK version from https://www.npmjs.com/package/amazon-quicksight-embedding-sdk -->
        <!-- Or you can do "npm install amazon-quicksight-embedding-sdk", if you use npm for javascript dependencies -->
        <script src="./quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            let embeddedVisualExperience;
            function onVisualLoad(payload) {
                console.log("Do something when the visual is fully loaded.");
            }

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

            function embedVisual() {
                const containerDiv = document.getElementById("embeddingContainer");
                const options = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: containerDiv,
                    parameters: {
                        country: "United States"
                    },
                    height: "700px",
                    width: "1000px",
                    locale: "en-US"
                };
                embeddedVisualExperience = QuickSightEmbedding.embedVisual(options);
                embeddedVisualExperience.on("error", onError);
                embeddedVisualExperience.on("load", onVisualLoad);
            }

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

    <body onload="embedVisual()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country" onchange="onCountryChange(this)">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="embeddingContainer"></div>
    </body>

</html>
```

若要讓此範例運作，請務必使用 Amazon Quick Sight 內嵌 SDK，使用 JavaScript 在您的網站上載入內嵌視覺效果。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

# 為匿名 （未註冊） 使用者嵌入 Amazon Quick Sight 視覺效果
<a name="embedded-analytics-visuals-for-everyone"></a>


|  | 
| --- |
|  適用於：企業版本  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下列各節中，您可以找到有關如何為匿名 （未註冊） 使用者設定內嵌 Amazon Quick Sight 視覺效果的詳細資訊。

**Topics**
+ [

## 步驟 1：設定許可
](#embedded-analytics-visuals-with-anonymous-users-step-1)
+ [

## 步驟 2：產生帶有身分驗證碼的 URL
](#embedded-analytics-visuals-with-anonymous-users-step-2)
+ [

## 步驟 3：內嵌視覺效果 URL
](#embedded-analytics-visuals-with-anonymous-users-step-3)

## 步驟 1：設定許可
<a name="embedded-analytics-visuals-with-anonymous-users-step-1"></a>


|  | 
| --- |
|  適用於：企業版本  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可。這個任務需要有 IAM 的管理存取權。

每個存取視覺效果的使用者都會擔任一個角色，為他們提供視覺效果的 Amazon Quick Sight 存取權和許可。若要實現此目的，請在 中建立 IAM 角色 AWS 帳戶。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。

您可以在 IAM 政策中建立條件，以限制開發人員可在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 參數中列出的域。`AllowedDomains` 參數是選用參數。它可讓您以開發人員身分選擇覆寫**管理 Amazon Quick Sight **選單中設定的靜態網域。您則最多可以列出三個可存取產生之 URL 的域或子網域。然後，此 URL 將嵌入您建立的網站中。只有參數中列出的域可以存取內嵌式儀表板。如果沒有這種情況，您可以在 `AllowedDomains` 參數中列出網際網路上的任何域。

若要限制開發人員可搭配此參數使用的域，請在 IAM 政策中新增 `AllowedEmbeddingDomains` 條件。如需 `AllowedDomains` 參數的詳細資訊，請參閱《*Amazon Quick Sight API 參考*》中的 [GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)。

**IAM 條件運算子的安全最佳實務**  
設定不當的 IAM 條件運算子可能會允許透過 URL 變化未經授權存取您的內嵌 Quick 資源。在 IAM 政策中使用 `quicksight:AllowedEmbeddingDomains`條件金鑰時，請使用允許特定網域或拒絕未明確允許的所有網域的條件運算子。如需 IAM 條件運算子的詳細資訊，請參閱《IAM [使用者指南》中的 IAM JSON 政策元素：條件運算子](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
許多不同的 URL 變化可以指向相同的資源。例如，下列 URLs全部解析為相同的內容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的政策使用未考慮這些 URL 變化的運算子，攻擊者可以透過提供同等的 URL 變化來繞過您的限制。  
您必須驗證 IAM 政策是否使用適當的條件運算子來防止繞過漏洞，並確保只有您預期的網域可以存取您的內嵌資源。

您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可代表使用者擔任該角色，並開啟視覺效果。範例信任政策如下所示。

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

------

如需有關信任政策的詳細資訊，請參閱**《IAM 使用者指南》中的[ IAM 中的臨時安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。

## 步驟 2：產生帶有身分驗證碼的 URL
<a name="embedded-analytics-visuals-with-anonymous-users-step-2"></a>


|  | 
| --- |
|  適用於：企業版本  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下一章節，您可以了解如何在您的應用程式伺服器上代表匿名訪客進行身分驗證，以及取得可內嵌的視覺效果 URL。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，它會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

下列範例會代表使用者執行 IAM 身分驗證。它傳遞識別符當作唯一的角色工作階段 ID。此代碼在您的應用程式伺服器上運行。

### Java
<a name="embedded-analytics-visuals-with-anonymous-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.AnonymousUserDashboardVisualEmbeddingConfiguration;
import com.amazonaws.services.quicksight.model.AnonymousUserEmbeddingExperienceConfiguration;
import com.amazonaws.services.quicksight.model.DashboardVisualId;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserResult;
import com.amazonaws.services.quicksight.model.SessionTag;

import java.util.List;

/**
 * Class to call QuickSight AWS SDK to get url for Visual embedding.
 */
public class GenerateEmbedUrlForAnonymousUserTest {
    private final AmazonQuickSight quickSightClient;

    public GenerateEmbedUrlForAnonymousUserTest() {
        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 getEmbedUrl(
            final String accountId, // AWS Account ID
            final String namespace, // Anonymous embedding required specifying a valid namespace for which you want the enbedding URL
            final List<String> authorizedResourceArns, // Dashboard arn list of dashboard visuals to embed
            final String dashboardId, // Dashboard ID of the dashboard to embed
            final String sheetId, // Sheet ID of the sheet to embed
            final String visualId, // Visual ID of the visual to embed
            final List<String> allowedDomains, // Runtime allowed domains for embedding
            final List<SessionTag> sessionTags // Session tags used for row-level security
    ) throws Exception {
        final DashboardVisualId dashboardVisual = new DashboardVisualId()
            .withDashboardId(dashboardId)
            .withSheetId(sheetId)
            .withVisualId(visualId);
        final AnonymousUserDashboardVisualEmbeddingConfiguration anonymousUserDashboardVisualEmbeddingConfiguration
            = new AnonymousUserDashboardVisualEmbeddingConfiguration()
                .withInitialDashboardVisualId(dashboardVisual);
        final AnonymousUserEmbeddingExperienceConfiguration anonymousUserEmbeddingExperienceConfiguration
            = new AnonymousUserEmbeddingExperienceConfiguration()
                .withDashboardVisual(anonymousUserDashboardVisualEmbeddingConfiguration);
        final GenerateEmbedUrlForAnonymousUserRequest generateEmbedUrlForAnonymousUserRequest
            = new GenerateEmbedUrlForAnonymousUserRequest()
                .withAwsAccountId(accountId)
                .withNamespace(namespace)
                // authorizedResourceArns should contain ARN of dashboard used below in ExperienceConfiguration
                .withAuthorizedResourceArns(authorizedResourceArns)
                .withExperienceConfiguration(anonymousUserEmbeddingExperienceConfiguration)
                .withAllowedDomains(allowedDomains)
                .withSessionTags(sessionTags)
                .withSessionLifetimeInMinutes(600L);

        final GenerateEmbedUrlForAnonymousUserResult generateEmbedUrlForAnonymousUserResult
            = quickSightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserRequest);

        return generateEmbedUrlForAnonymousUserResult.getEmbedUrl();
    }
}
```

### JavaScript
<a name="embedded-analytics-visuals-with-anonymous-users-js"></a>

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

function generateEmbedUrlForAnonymousUser(
    accountId, // Your AWS account ID
    dashboardId, // Dashboard ID to which the constructed url points
    sheetId, // Sheet ID to which the constructed url points
    visualId, // Visual ID to which the constructed url points
    quicksightNamespace, // valid namespace where you want to do embedding
    authorizedResourceArns, // dashboard arn list of dashboard visuals to embed
    allowedDomains, // runtime allowed domains for embedding
    sessionTags, // session tags used for row-level security
    generateEmbedUrlForAnonymousUserCallback, // success callback method
    errorCallback // error callback method
    ) {
    const experienceConfiguration = {
        "DashboardVisual": {
            "InitialDashboardVisualId": {
                "DashboardId": dashboardId,
                "SheetId": sheetId,
                "VisualId": visualId
            }
        }
    };
    
    const generateEmbedUrlForAnonymousUserParams = {
        "AwsAccountId": accountId,
        "Namespace": quicksightNamespace,
        // authorizedResourceArns should contain ARN of dashboard used below in ExperienceConfiguration
        "AuthorizedResourceArns": authorizedResourceArns,
        "AllowedDomains": allowedDomains,
        "ExperienceConfiguration": experienceConfiguration,
        "SessionTags": sessionTags,
        "SessionLifetimeInMinutes": 600
    };

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

    quicksightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserParams, 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 THIS API
                    "Access-Control-Allow-Headers": "Content-Type"
                },
                "body": JSON.stringify(data),
                "isBase64Encoded": false
            }
            generateEmbedUrlForAnonymousUserCallback(result);
        }
    });
}
```

### Python3
<a name="embedded-analytics-visuals-with-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
# quicksightNamespace: VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
# authorizedResourceArns: DASHBOARD ARN LIST TO EMBED
# allowedDomains: RUNTIME ALLOWED DOMAINS FOR EMBEDDING
# experienceConfiguration: DASHBOARD ID, SHEET ID and VISUAL ID TO WHICH THE CONSTRUCTED URL POINTS
# Example experienceConfig -> 'DashboardVisual': {
#     'InitialDashboardVisualId': {
#         'DashboardId': 'dashboardId',
#         'SheetId': 'sheetId',
#         'VisualId': 'visualId'
#     }
# },
# sessionTags: SESSION TAGS USED FOR ROW-LEVEL SECURITY
def generateEmbedUrlForAnonymousUser(accountId, quicksightNamespace, authorizedResourceArns, allowedDomains, experienceConfiguration, sessionTags):
    try:
        response = quicksightClient.generate_embed_url_for_anonymous_user(
            AwsAccountId = accountId,
            Namespace = quicksightNamespace,
            AuthorizedResourceArns = authorizedResourceArns,
            AllowedDomains = allowedDomains,
            ExperienceConfiguration = experienceConfiguration,
            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-visuals-with-anonymous-users-node"></a>

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
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.generateEmbedUrlForAnonymousUser({
    'AwsAccountId': '111122223333',
    'Namespace' : 'default',
    // authorizedResourceArns should contain ARN of dashboard used below in ExperienceConfiguration
    'AuthorizedResourceArns': authorizedResourceArns,
    'ExperienceConfiguration': { 
        'DashboardVisual': {
            'InitialDashboardVisualId': {
                'DashboardId': 'dashboard_id',
                'SheetId': 'sheet_id',
                'VisualId': 'visual_id'
            }
        }
    },
    'AllowedDomains': allowedDomains,    
    'SessionTags': sessionTags,
    'SessionLifetimeInMinutes': 600

}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

**Example**  

```
//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/C\$1
<a name="embedded-analytics-visuals-with-anonymous-users-cs"></a>

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

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

namespace GenerateDashboardEmbedUrlForAnonymousUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                DashboardVisualId dashboardVisual = new DashboardVisualId
                {
                    DashboardId = "dashboard_id",
                    SheetId = "sheet_id",
                    VisualId = "visual_id"
                };

                AnonymousUserDashboardVisualEmbeddingConfiguration anonymousUserDashboardVisualEmbeddingConfiguration
                    = new AnonymousUserDashboardVisualEmbeddingConfiguration
                    {
                        InitialDashboardVisualId = dashboardVisual                        
                    };               
                    
                AnonymousUserEmbeddingExperienceConfiguration anonymousUserEmbeddingExperienceConfiguration
                    = new AnonymousUserEmbeddingExperienceConfiguration
                    {
                        DashboardVisual = anonymousUserDashboardVisualEmbeddingConfiguration
                    }; 
                    
                Console.WriteLine(
                    quicksightClient.GenerateEmbedUrlForAnonymousUserAsync(new GenerateEmbedUrlForAnonymousUserRequest
                    {
                        AwsAccountId = "111222333444",
                        Namespace = default,
                        // authorizedResourceArns should contain ARN of dashboard used below in ExperienceConfiguration
                        AuthorizedResourceArns = { "dashboard_id" },
                        ExperienceConfiguration = anonymousUserEmbeddingExperienceConfiguration,
                        SessionTags = sessionTags,
                        SessionLifetimeInMinutes = 600,
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
```

### AWS CLI
<a name="embedded-analytics-visuals-with-anonymous-users-cli"></a>

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用安全性聲明標記語言 (SAML) 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GenerateEmbedUrlForAnonymousUser` 的許可。

```
aws sts assume-role \
    --role-arn "arn:aws:iam::11112222333:role/QuickSightEmbeddingAnonymousPolicy" \
    --role-session-name anonymous caller
```

`assume-role` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。如果您使用 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_visual_role/QuickSightEmbeddingAnonymousPolicy`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個訪問使用者設定適當的許可。它還使每個會話獨立且不同。如果您正在使用 Web 伺服器陣列 (例如負載平衡)，且工作階段重新連線到不同的伺服器，則會開始新的工作階段。

為了取得視覺效果的簽章 URL，請從應用程式伺服器呼叫 `generate-embed-url-for-anynymous-user`。這會傳回可內嵌的視覺效果 URL。下列範例顯示如何使用伺服器端呼叫，針對匿名造訪您的 Web 入口網站或應用程式的使用者，產生內嵌視覺效果的 URL。

```
aws quicksight generate-embed-url-for-anonymous-user \
    --aws-account-id 111122223333 \
    --namespace default-or-something-else \
    --session-lifetime-in-minutes 15 \
    --authorized-resource-arns '["dashboard-arn-1","dashboard-arn-2"]' \
    --allowed-domains '["domain1","domain2"]' \
    --session-tags '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]' \
    --experience-configuration 'DashboardVisual={InitialDashboardVisualId={DashboardId=dashboard_id,SheetId=sheet_id,VisualId=visual_id}}'
```

如需使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

## 步驟 3：內嵌視覺效果 URL
<a name="embedded-analytics-visuals-with-anonymous-users-step-3"></a>


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下一節中，您可以了解如何使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript)，在網站或應用程式頁面中嵌入步驟 2 的視覺化 URL。您可以使用此 SDK 執行以下操作：
+ 將視覺效果放置在 HTML 頁面上。
+ 將參數傳遞到視覺效果中。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

呼叫 `GenerateEmbedUrlForAnonymousUser` API 操作以產生可嵌入應用程式的 URL。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期為 10 小時。API 操作為 URL 提供的授權 (auth) 代碼將啟用單一登入工作階段。

以下是 `generate-embed-url-for-anonymous-user` 的回應範例。此範例中`quicksightdomain`的 是您用來存取 Amazon Quick Sight 帳戶的 URL。

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

使用 Amazon Quick Sight [內嵌 SDK 或將此 URL 新增至 iframe，將此視覺效果內嵌](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)在您的網頁中。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制視覺效果中的參數，並在視覺效果載入完成和錯誤方面接收回呼。

即將託管內嵌視覺效果的網域必須列在*允許清單*中，此為您的 Quick 訂閱已獲核准的域清單。這項要求將使未獲核准的域無法託管內嵌視覺效果和儀表板，進而保護您的資料。如需為內嵌視覺效果和儀表板新增網域的詳細資訊，請參閱[使用 Amazon Quick Sight API 在執行時間允許列出網域](https://docs.aws.amazon.com/quicksight/latest/user/embedding-run-time.html)。

下列範例示範如何使用產生的 URL。此代碼駐留在您的應用程式伺服器上。

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

```
<!DOCTYPE html>
<html>

    <head>
        <title>Visual 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 embedVisual = 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 = {
                    parameters: [
                        {
                            Name: 'country',
                            Values: ['United States'],
                        },
                        {
                            Name: 'states',
                            Values: [
                                'California',
                                'Washington'
                            ]
                        }
                    ],
                    locale: "en-US",
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'CONTENT_LOADED': {
                                console.log("All visuals are loaded. The title of the document:", messageEvent.message.title);
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Error occurred while rendering the experience. Error code:", messageEvent.message.errorCode);
                                break;
                            }
                            case 'PARAMETERS_CHANGED': {
                                console.log("Parameters changed. Changed parameters:", messageEvent.message.changedParameters);
                                break;
                            }
                            case 'SIZE_CHANGED': {
                                console.log("Size changed. New dimensions:", messageEvent.message);
                                break;
                            }
                        }
                    },
                };
                const embeddedVisualExperience = await embeddingContext.embedVisual(frameOptions, contentOptions);

                const selectCountryElement = document.getElementById('country');
                selectCountryElement.addEventListener('change', (event) => {
                    embeddedVisualExperience.setParameters([
                        {
                            Name: 'country',
                            Values: event.target.value
                        }
                    ]);
                });
            };
        </script>
    </head>

    <body onload="embedVisual()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="experience-container"></div>
    </body>

</html>
```

### SDK 1.0
<a name="embedded-analytics-visuals-with-anonymous-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Visual Embedding Example</title>
        <!-- You can download the latest QuickSight embedding SDK version from https://www.npmjs.com/package/amazon-quicksight-embedding-sdk -->
        <!-- Or you can do "npm install amazon-quicksight-embedding-sdk", if you use npm for javascript dependencies -->
        <script src="./quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            let embeddedVisualExperience;
            function onVisualLoad(payload) {
                console.log("Do something when the visual is fully loaded.");
            }

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

            function embedVisual() {
                const containerDiv = document.getElementById("embeddingContainer");
                const options = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: containerDiv,
                    parameters: {
                        country: "United States"
                    },
                    height: "700px",
                    width: "1000px",
                    locale: "en-US"
                };
                embeddedVisualExperience = QuickSightEmbedding.embedVisual(options);
                embeddedVisualExperience.on("error", onError);
                embeddedVisualExperience.on("load", onVisualLoad);
            }

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

    <body onload="embedVisual()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country" onchange="onCountryChange(this)">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="embeddingContainer"></div>
    </body>

</html>
```

若要讓此範例運作，請務必使用 Amazon Quick Sight 內嵌 SDK，使用 JavaScript 在您的網站上載入內嵌視覺效果。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的 QuickSight 內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

# 為已註冊使用者嵌入 Amazon Quick Sight 主控台的完整功能
<a name="embedded-analytics-full-console-for-authenticated-users"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 API 操作： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` API 操作來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需使用舊 API 操作內嵌的詳細資訊，請參閱[使用 GetDashboardEmbedURL和 GetSessionEmbedURL API 操作內嵌分析](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics-deprecated.html)。


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

使用企業版，除了提供唯讀儀表板之外，您還可以在自訂品牌撰寫入口網站中提供 Amazon Quick Sight 主控台體驗。使用這種方法，可以讓使用者建立資料來源、資料集和分析。在相同的界面中，他們可以建立、發布和檢視儀表板。如果您想限制其中一些許可，也可以這樣做。

透過內嵌主控台存取 Amazon Quick Sight 的使用者需要屬於作者或管理員安全群組。讀者沒有足夠的存取權來使用 Amazon Quick Sight 主控台進行撰寫，無論它是內嵌或 的一部分 AWS 管理主控台。但是，作者和管理員仍然可以存取內嵌式儀表板。如果您想要限制某些編寫特徵的許可，可以使用 [UpdateUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_UpdateUser.html) API 操作將自訂許可設定檔新增至使用者。使用 [RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html) API 操作來新增附加自訂許可設定檔的新使用者。如需詳細資訊，請參閱下列章節：
+ 如需透過定義自訂主控台許可來建立自訂角色的資訊，請參閱[自訂 Amazon Quick Sight 主控台的存取權](https://docs.aws.amazon.com/quicksight/latest/user/customizing-permissions-to-the-quicksight-console.html)。
+ 如需使用命名空間隔離多租戶使用者、群組和 Amazon Quick Sight 資產的相關資訊，請參閱 [Amazon Quick Sight 命名空間](https://docs.aws.amazon.com/quicksight/latest/APIReference/controlling-access.html#namespaces.html)。
+ 如需將自有品牌新增至內嵌 Amazon Quick Sight 主控台的詳細資訊，請參閱[在 Amazon Quick Sight 中使用佈景主題](https://docs.aws.amazon.com/quicksight/latest/user/themes-in-quicksight.html)和 [QuickSight 佈景主題 API 操作](https://docs.aws.amazon.com/quicksight/latest/APIReference/qs-assets.html#themes)。

在下列各節中，您可以找到有關如何為已註冊使用者設定內嵌 Amazon Quick Sight 儀表板的詳細資訊。

**Topics**
+ [

## 步驟 1：設定許可
](#embedded-analytics-full-console-for-authenticated-users-step-1)
+ [

## 步驟 2：產生帶有身分驗證碼的 URL
](#embedded-analytics-full-console-for-authenticated-users-step-2)
+ [

## 步驟 3：嵌入主控台工作階段 URL
](#embedded-analytics-full-console-for-authenticated-users-step-3)
+ [

# 在嵌入式主控台中為已註冊使用者啟用生成式 BI 功能
](embedding-consoles-genbi.md)

## 步驟 1：設定許可
<a name="embedded-analytics-full-console-for-authenticated-users-step-1"></a>

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可。這個任務需要有 IAM 的管理存取權。

每個存取 Amazon Quick Sight 的使用者都會擔任一個角色，為他們提供主控台工作階段的 Amazon Quick Sight 存取權和許可。若要實現這一點，請在 AWS 您的帳戶中建立 IAM 角色。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。新增`quicksight:RegisterUser`許可，以確保讀者可以唯讀方式存取 Amazon Quick Sight，而且無法存取任何其他資料或建立功能。IAM 角色也需要提供可擷取主控台工作階段 URL 的許可。對於這一點，您新增 `quicksight:GenerateEmbedUrlForRegisteredUser`。

您可以在 IAM 政策中建立條件，以限制開發人員可在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 參數中列出的域。`AllowedDomains` 參數是選用參數。它可讓您以開發人員身分選擇覆寫**管理 Amazon Quick Sight **選單中設定的靜態網域。您則最多可以列出三個可存取產生之 URL 的域或子網域。然後，此 URL 將嵌入您建立的網站中。只有參數中列出的域可以存取內嵌式儀表板。如果沒有這種情況，您可以在 `AllowedDomains` 參數中列出網際網路上的任何域。

**IAM 條件運算子的安全最佳實務**  
設定不當的 IAM 條件運算子可能會允許透過 URL 變化未經授權存取您的內嵌 Quick 資源。在 IAM 政策中使用 `quicksight:AllowedEmbeddingDomains`條件金鑰時，請使用允許特定網域或拒絕未特別允許的所有網域的條件運算子。如需 IAM 條件運算子的詳細資訊，請參閱《IAM [使用者指南》中的 IAM JSON 政策元素：條件運算子](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
許多不同的 URL 變化可以指向相同的資源。例如，下列 URLs全部解析為相同的內容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的政策使用未考慮這些 URL 變化的運算子，攻擊者可以透過提供同等的 URL 變化來繞過您的限制。  
您必須驗證 IAM 政策是否使用適當的條件運算子來防止繞過漏洞，並確保只有預期的網域可以存取您的內嵌資源。

下列範例政策提供這些許可。

下列範例政策提供擷取主控台工作階段 URL 的許可。如果您要在使用者存取內嵌工作階段之前建立使用者，則可以不帶 `quicksight:RegisterUser` 使用原則。

最後，您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可以代表使用者擔任該角色，並在 Amazon Quick Sight 中佈建使用者。範例信任政策如下所示。

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

------

如需 OpenID Connect 或 SAML 身分驗證的信任政策詳細資訊，請參閱 *IAM 使用者指南*的下列各節：
+ [建立 Web 身分或 OpenID Connect 聯合身分的角色 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [建立 SAML 2.0 聯合身分的角色 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

## 步驟 2：產生帶有身分驗證碼的 URL
<a name="embedded-analytics-full-console-for-authenticated-users-step-2"></a>

在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌主控台工作階段的 URL。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，它會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

執行所述的步驟可確保主控台工作階段的每個檢視器在 Amazon Quick Sight 中都是唯一的佈建。它還會強制執行個別使用者設定，例如資料列層級的安全性和參數的動態預設值。

下列範例會代表使用者執行 IAM 身分驗證。此代碼在您的應用程式伺服器上運行。

### Java
<a name="embedded-analytics-full-console-for-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.RegisteredUserQuickSightConsoleEmbeddingConfiguration;

/**
 * Class to call QuickSight AWS SDK to get url for QuickSight console embedding.
 */
public class GetQuicksightEmbedUrlRegisteredUserQSConsoleEmbedding {

    private final AmazonQuickSight quickSightClient;

    public GetQuicksightEmbedUrlRegisteredUserQSConsoleEmbedding() {
        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,
            final String userArn, // Registered user arn to use for embedding. Refer to Get Embed Url section in developer portal to find out how to get user arn for a QuickSight user.
            final List<String> allowedDomains, // Runtime allowed domain for embedding
            final String initialPath
    ) throws Exception {
        final RegisteredUserEmbeddingExperienceConfiguration experienceConfiguration = new RegisteredUserEmbeddingExperienceConfiguration()
                .withQuickSightConsole(new RegisteredUserQuickSightConsoleEmbeddingConfiguration().withInitialPath(initialPath));
        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-full-console-for-authenticated-users-js"></a>

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

function generateEmbedUrlForRegisteredUser(
    accountId,
    dashboardId,
    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 getDashboardParams = {
                "AwsAccountId": accountId,
                "ExperienceConfiguration": {
                    "QuickSightConsole": {
                        "InitialPath": '/start'
                    }
                },
                "UserArn": userArn,
                "AllowedDomains": allowedDomains,
                "SessionLifetimeInMinutes": 600
            };

            const quicksightGetDashboard = 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
                }
            });

            quicksightGetDashboard.generateEmbedUrlForRegisteredUser(getDashboardParams, 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);
                }
            });
        }
    });
}
```

### Python3
<a name="embedded-analytics-full-console-for-authenticated-users-py"></a>

```
import json
import boto3
from botocore.exceptions import ClientError

# Create QuickSight and STS clients
qs = boto3.client('quicksight', region_name='us-east-1')
sts = boto3.client('sts')

# Function to generate embedded URL  
# accountId: AWS account ID
# 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 generateEmbeddingURL(accountId, 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-east-1')
            
            experienceConfiguration = {
                "QuickSightConsole": {
                    "InitialPath": "/start"
                }
            }
            response = quickSightClient.generate_embed_url_for_registered_user(
                 AwsAccountId = accountId,
                 ExperienceConfiguration = experienceConfiguration,
                 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-full-console-for-authenticated-users-node"></a>

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來產生內嵌主控台工作階段的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示主控台工作階段。

**Example**  

```
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': {
        'QuickSightConsole': {
            'InitialPath': '/start'
        }
    },
    'UserArn': 'REGISTERED_USER_ARN',
    'AllowedDomains': allowedDomains,
    'SessionLifetimeInMinutes': 100
}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

**Example**  

```
// 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..,
        RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713'
    }
```

### .NET/C\$1
<a name="embedded-analytics-full-console-for-authenticated-users-cs"></a>

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來產生內嵌主控台工作階段的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示主控台。

**Example**  

```
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
            {
                RegisteredUserQuickSightConsoleEmbeddingConfiguration registeredUserQuickSightConsoleEmbeddingConfiguration
                    = new RegisteredUserQuickSightConsoleEmbeddingConfiguration
                    {
                        InitialPath = "/start"
                    };
                RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                    = new RegisteredUserEmbeddingExperienceConfiguration
                    {
                        QuickSightConsole = registeredUserQuickSightConsoleEmbeddingConfiguration
                    };
                
                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-full-console-for-authenticated-users-cli"></a>

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用 SAML 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GenerateEmbedUrlForRegisteredUser` 的許可。如果您在第一次開啟 Amazon Quick Sight 時採取just-in-time方法來新增使用者，該角色也需要為 啟用許可`quicksight:RegisterUser`。

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

`assume-role` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。如果您使用 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_console_session_role/john.doe@example.com`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個使用者設定適當的許可。還能避免對使用者存取進行任何調節。調節是一項安全功能，可防止相同的使用者從多個位置存取 Amazon Quick Sight。

角色工作階段 ID 也會成為 Amazon Quick Sight 中的使用者名稱。您可以使用此模式提前在 Amazon Quick Sight 中佈建使用者，或在使用者第一次存取主控台工作階段時佈建他們。

以下範例顯示可用來佈建使用者的 CLI 命令。如需 [RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html) 和其他 Amazon Quick Sight API 操作的詳細資訊，請參閱 [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_dashboard_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` 設定他們。相反地，他們應在第一次存取 Amazon Quick Sight 時自動訂閱。若是 Microsoft AD 使用者，您可以使用 `DescribeUser` 取得使用者的 ARN。

使用者第一次存取 Amazon Quick Sight 時，您也可以將此使用者新增至適當的群組。以下範例顯示用於將使用者新增至群組的 CLI 命令。

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

您現在擁有的應用程式使用者也是 Amazon Quick Sight 的使用者，以及可存取 Amazon Quick Sight 主控台工作階段的使用者。

最後，為了取得主控台工作階段的簽章 URL，請從應用程式伺服器呼叫 `generate-embed-url-for-registered-user`。這將返回可嵌入的主控台工作階段 URL。下列範例示範如何使用伺服器端呼叫為透過 AWS Managed Microsoft AD 或單一登入 (IAM Identity Center) 驗證的使用者產生內嵌主控台工作階段的 URL。

```
aws quicksight generate-embed-url-for-registered-user \
    --aws-account-id 111122223333 \
    --entry-point the-url-for--the-console-session \
    --session-lifetime-in-minutes 600 \
    --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_dashboard_role/embeddingsession
	--allowed-domains '["domain1","domain2"]' \
    --experience-configuration QuickSightConsole={InitialPath="/start"}
```

如需使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

## 步驟 3：嵌入主控台工作階段 URL
<a name="embedded-analytics-full-console-for-authenticated-users-step-3"></a>

在下一節中，您可以了解如何使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript)，在網站或應用程式頁面的步驟 3 中內嵌主控台工作階段 URL。您可以使用此 SDK 執行以下操作：
+ 將主控台工作階段放置在 HTML 頁面上。
+ 將參數傳遞至主控台工作階段。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

呼叫 `GenerateEmbedUrlForRegisteredUser` API 操作以產生可嵌入應用程式的 URL。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期最長為 10 小時。此 API 操作提供的 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/start...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 Amazon Quick Sight [內嵌 SDK ](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)或將此 URL 新增至 iframe，將此主控台工作階段內嵌在您的網頁中。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制主控台工作階段中的參數，並根據頁面載入完成和錯誤接收回呼。

要託管內嵌儀表板的網域必須位於*允許清單*上，即 Quick 訂閱的已核准網域清單。這項要求將使未獲核准的網域無法託管嵌入儀表板，進而保護您的資料。如需為內嵌主控台新增網域的詳細資訊，請參閱[使用 Amazon Quick Sight API 在執行時間允許列出網域](https://docs.aws.amazon.com/quicksight/latest/user/embedding-run-time.html)。

下列範例示範如何使用產生的 URL。此代碼在您的應用程式伺服器上生成。

### SDK 2.0
<a name="embedded-analytics-full-console-for-authenticated-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Console 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 embedSession = 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 = {
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'ERROR_OCCURRED': {
                                console.log("Do something when the embedded experience fails loading.");
                                break;
                            }
                        }
                    }
                };
                const embeddedConsoleExperience = await embeddingContext.embedConsole(frameOptions, contentOptions);
            };
        </script>
    </head>

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

</html>
```

### SDK 1.0
<a name="embedded-analytics-full-console-for-authenticated-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>QuickSight Console Embedding</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.0.15/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 embedSession() {
                var containerDiv = document.getElementById("embeddingContainer");
                var options = {
                    // replace this dummy url with the one generated via embedding API
                    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,
                    parameters: {
                        country: "United States"
                    },
                    scrolling: "no",
                    height: "700px",
                    width: "1000px",
                    locale: "en-US",
                    footerPaddingEnabled: true,
                    defaultEmbeddingVisualType: "TABLE", // this option only applies to QuickSight console embedding and is not used for dashboard embedding
                };
                session = QuickSightEmbedding.embedSession(options);
                session.on("error", onError);
            }

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

    <body onload="embedSession()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country" onchange="onCountryChange(this)">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="embeddingContainer"></div>
    </body>

</html>
```

若要讓此範例運作，請務必使用 Amazon Quick Sight 內嵌 SDK，使用 JavaScript 在您的網站上載入內嵌主控台工作階段。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

# 在嵌入式主控台中為已註冊使用者啟用生成式 BI 功能
<a name="embedding-consoles-genbi"></a>


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

您可以在嵌入式主控台中啟用下列生成式 BI 功能：
+ 執行摘要：啟用時，已註冊的 Author Pro 和 Reader Pro 使用者可以產生執行摘要，提供 Amazon Quick Sight 為儀表板產生的所有洞見摘要，以輕鬆探索關鍵洞見。
+ 編寫：啟用後，「作者專業版」使用者可以使用生成式 BI 來建置計算欄位，並建置與精簡視覺效果。
+ 問答：啟用後，「作者專業版」和「讀者專業版」使用者可以使用 AI 支援的問答來建議與回答與其資料相關的問題。
+ 資料故事：啟用後，「作者專業版」和「讀者專業版」使用者可以提供詳細資訊，以快速產生其資料故事的第一份草稿。

**在嵌入式主控台中為已註冊使用者啟用生成式 BI 功能**
+ 請遵循[內嵌 Amazon Quick Sight 主控台的完整功能中的步驟，讓已註冊的使用者](https://docs.aws.amazon.com/quicksight/latest/user/embedded-analytics-full-console-for-authenticated-users.html)內嵌具有下列變更的主控台：

  1. 在步驟 2 中產生 URL 時，請針對要啟用的每個功能，在 [GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html) 或 [GenerateEmbedUrlForRegisteredUserWithIdentity](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUserWithIdentity.html) API 中，在 `FeatureConfigurations` 參數中設定 `Enabled: true`，如下列範例所示。如果未提供組態，則依預設會停用這些功能。

     ```
     ExperienceConfiguration: {
             QuickSightConsole: {
                 InitialPath: "initial_path",
                 AmazonQInQuickSight: {
                     FeatureConfigurations: { 
                         COMMENT: Enable executive summaries
                         ExecutiveSummary: {
                             Enabled: true
                         },
                         COMMENT: Enable Generative BI authoring
                         GenerativeAuthoring: {
                             Enabled: true
                         },
                         COMMENT: Enable Q&A
                         DataQnA: {
                             Enabled: true
                         },
                         COMMENT: Enable data stories
                         DataStories: {
                             Enabled: true
                         }       
                     }
                 }
             }
         }
     }
     ```

  1. 在步驟 3 中使用 Amazon Quick Sight 內嵌 SDK 內嵌主控台 URL 時，視需要設定下列範例中的值。如果未提供組態，則依預設會停用這些功能。
**注意**  
沒有用於啟用資料故事的 SDK 選項。如果透過 API 啟用資料故事(如上一個步驟所示)，已註冊的使用者將可以使用資料故事。

     ```
     const contentOptions = {
         toolbarOptions: {
             executiveSummary: true, // Enable executive summaries
             buildVisual: true, // Enable Generative BI authoring
             dataQnA: true // Enable Q&A
         }
     };
     ```

# 在 Amazon Quick Sight 生成式問答體驗中嵌入 Amazon Q
<a name="embedding-gen-bi"></a>


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下列各節中，您可以找到有關如何設定使用 LLM 提供之增強型 NLQ 功能的嵌入生成式問答功能的詳細資訊。生成式問答功能是嵌入式 Q 搜尋列的建議替代項目，並為使用者提供更新的 BI 體驗。

**Topics**
+ [

## 為註冊使用者嵌入 Amazon Quick Sight 生成式問答體驗
](#embedded-analytics-gen-bi-authenticated-users)
+ [

## 為匿名 （未註冊） 使用者嵌入 Amazon Q in Quick Generative Q&A 體驗
](#embedded-analytics-gen-bi-anonymous-users)

## 為註冊使用者嵌入 Amazon Quick Sight 生成式問答體驗
<a name="embedded-analytics-gen-bi-authenticated-users"></a>

在下列各節中，您可以找到有關如何為 Amazon Quick Sight 註冊使用者設定內嵌生成式問答體驗的詳細資訊。

**Topics**
+ [

### 步驟 1：設定許可
](#embedded-analytics-gen-bi-authenticated-users-step-1)
+ [

### 步驟 2：產生帶有身分驗證碼的 URL
](#embedded-analytics-gen-bi-authenticated-users-step-2)
+ [

### 步驟 3：嵌入生成式問答功能 URL
](#embedded-analytics-gen-bi-authenticated-users-step-3)
+ [

### 選用的嵌入生成式問答功能功能
](#embedded-analytics-gen-bi-authenticated-users-step-4)

### 步驟 1：設定許可
<a name="embedded-analytics-gen-bi-authenticated-users-step-1"></a>

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可，以嵌入生成式問答功能。此任務需要 AWS Identity and Access Management (IAM) 的管理存取權。

每個存取生成式問答體驗的使用者都會擔任一個角色，為他們提供 Amazon Quick Sight 存取和許可。為了實現這一點，請在您的 AWS 帳戶中建立 IAM 角色。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。IAM 角色需要提供許可，以擷取特定使用者集區的內嵌 URL。

藉助萬用字元 *\$1*，您可以授予許可，以便為特定命名空間中的所有使用者產生 URL。或者，您可以授予許可來為特定命名空間中的使用者子集產生 URL。對於這一點，您新增 `quicksight:GenerateEmbedUrlForRegisteredUser`。

您可以在 IAM 政策中建立條件，以限制開發人員可在 `GenerateEmbedUrlForRegisteredUser` API 操作的 `AllowedDomains` 參數中列出的域。`AllowedDomains` 參數是選用參數。它授予開發人員覆寫在**管理 Amazon Quick Sight **選單中設定的靜態網域的選項，並改為列出最多三個可存取產生 URL 的網域或子網域。然後將此 URL 內嵌到開發人員的網站中。只有在參數中列出的網域可以存取嵌入生成式問答功能。如果沒有這種情況，開發人員可以在 `AllowedDomains` 參數中列出網際網路上的任何域。

若要限制開發人員可搭配此參數使用的網域，請在 IAM 政策中新增 `AllowedEmbeddingDomains` 條件。如需 `AllowedDomains` 參數的詳細資訊，請參閱《*Amazon Quick Sight API 參考*》中的 [GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。

**IAM 條件運算子的安全最佳實務**  
設定不當的 IAM 條件運算子可能會允許透過 URL 變化未經授權存取您的內嵌 Quick 資源。在 IAM 政策中使用 `quicksight:AllowedEmbeddingDomains`條件金鑰時，請使用允許特定網域或拒絕未明確允許的所有網域的條件運算子。如需 IAM 條件運算子的詳細資訊，請參閱《IAM [使用者指南》中的 IAM JSON 政策元素：條件運算子](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
許多不同的 URL 變化可以指向相同的資源。例如，下列 URLs全部解析為相同的內容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的政策使用未考慮這些 URL 變化的運算子，攻擊者可以透過提供同等的 URL 變化來繞過您的限制。  
您必須驗證 IAM 政策是否使用適當的條件運算子來防止繞過漏洞，並確保只有您預期的網域可以存取您的內嵌資源。

下列範例政策提供這些許可。

此外，如果您要建立將成為 Amazon Quick Sight 讀者的第一次使用者，請務必在政策中新增 `quicksight:RegisterUser`許可。

下列範例政策提供許可，以擷取初次成為 Amazon Quick Sight 讀取器之使用者的內嵌 URL。

最後，您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可以代表使用者擔任該角色，並在 Amazon Quick Sight 中佈建使用者。

範例信任政策如下所示。

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

------

如需 OpenID Connect 或安全性聲明標記語言 (SAML) 身分驗證的信任政策詳細資訊，請參閱《IAM 使用者指南》**的下列各章節：
+ [建立 Web 身分的角色或 OpenID Connect 聯合身分 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [為 SAML 2.0 聯合身分建立角色 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

### 步驟 2：產生帶有身分驗證碼的 URL
<a name="embedded-analytics-gen-bi-authenticated-users-step-2"></a>

在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌的 Q 主題 URL。如果您打算嵌入 IAM 或 Amazon Quick Sight 身分類型的生成式問答體驗，請與使用者共用 Q 主題。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，應用程式會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

執行所述的步驟可確保 Q 主題的每個檢視器都是在 Amazon Quick Sight 中唯一佈建。它還會強制執行個別使用者設定，例如資料列層級的安全性和參數的動態預設值。標籤型資料列層級安全性可用於 Q 列的匿名使用者嵌入。

下列範例會代表使用者執行 IAM 身分驗證。此代碼在您的應用程式伺服器上運行。

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

**注意**  
無法直接從瀏覽器呼叫嵌入式 URL 產生 API。請改為參閱 Node.JS 範例。

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

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

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

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來產生嵌入式 Q 搜尋列的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示 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>

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用 SAML 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GenerateEmbedUrlForRegisteredUser` 的許可。如果您正在採取即時方法在使用者使用 Q 搜尋列中的主題時新增使用者，則該角色還需要啟用 `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` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。對於 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_q_search_bar_role/john.doe@example.com`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個使用者設定適當的許可。還能避免對使用者存取進行任何調節。*調節*是一項安全功能，可防止相同的使用者從多個位置存取 Amazon Quick Sight。

角色工作階段 ID 也會成為 Amazon Quick Sight 中的使用者名稱。您可以使用此模式提前在 Amazon Quick Sight 中佈建使用者，或在他們第一次存取生成式問答體驗時佈建使用者。

以下範例顯示可用來佈建使用者的 CLI 命令。如需 [RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html) 和其他 Amazon Quick Sight API 操作的詳細資訊，請參閱 [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
```

如果使用者是透過 Microsoft AD 進行身分驗證，您就不需要使用 `RegisterUser` 設定他們。反之，他們應該在第一次存取 Amazon Quick Sight 時自動訂閱。若是 Microsoft AD 使用者，您可以使用 `DescribeUser` 取得使用者的 Amazon Resource Name (ARN)。

使用者第一次存取 Amazon Quick Sight 時，您也可以將此使用者新增至與儀表板共用的群組。以下範例顯示用於將使用者新增至群組的 CLI 命令。

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

您現在擁有應用程式的使用者，他們也是 Amazon Quick Sight 的使用者，以及有權存取儀表板的使用者。

最後，為了取得儀表板的簽章 URL，請從應用程式伺服器呼叫 `generate-embed-url-for-registered-user`。這會傳回可嵌入的儀表板 URL。下列範例示範如何使用伺服器端呼叫為透過 AWS Managed Microsoft AD 或單一登入 (IAM Identity Center) 驗證的使用者產生內嵌儀表板的 URL。

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

如需使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

### 步驟 3：嵌入生成式問答功能 URL
<a name="embedded-analytics-gen-bi-authenticated-users-step-3"></a>

在下一章節，您可以了解如何在網站或應用程式頁面中嵌入生成式問答功能 URL。您可以使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 來執行此操作。您可以使用此 SDK 執行以下操作：
+ 將生成式問答功能放置在 HTML 頁面上。
+ 自訂嵌入功能的版面配置和外觀，以符合您的應用程式需求。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

若要產生可以內嵌到應用程式中的 URL，請呼叫 `GenerateEmbedUrlForRegisteredUser` API 操作。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期最長為 10 小時。此 API 操作提供的 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"
}
```

使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 或將此 URL 新增至 iframe，在您的網頁中嵌入生成式問答體驗。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。

請確定託管內嵌生成式問答體驗的網域列於*允許清單*上，即 Amazon Quick Sight 訂閱的已核准網域清單。這項要求將使未獲核准的網域無法託管嵌入儀表板，進而保護您的資料。如需為嵌入生成式問答功能新增網域的詳細資訊，請參閱[管理網域](manage-domains.md)。

您可以使用 Amazon Quick Sight 內嵌 SDK 自訂內嵌生成式問答體驗的配置和外觀，以符合您的應用程式。使用 `panelType` 屬性設定生成式問答功能在應用程式中轉譯時的登陸狀態。將 `panelType` 屬性設定為 `'FULL'`，以轉譯完整的生成式問答功能面板。此面板類似 Amazon Quick Sight 使用者在 Amazon Quick Sight 主控台中擁有的體驗。面板的影格高度不會根據使用者互動而變更，並且會遵守您在 `frameOptions.height` 屬性中設定的值。下圖顯示當您將 `panelType` 值設定為 `'FULL'` 時轉譯的生成式問答功能面板。

將 `panelType` 屬性設定為 `'SEARCH_BAR'`，以搜尋列形式轉譯生成式問答功能。此搜尋列類似於 Q 搜尋列在嵌入應用程式時轉譯的方式。生成式問答搜尋列會展開為較大面板，顯示主題選取選項、問題建議清單、答案面板或 Pinboard。

嵌入式資產載入時，會轉譯生成式問答搜尋列的預設最小高度。建議您將 `frameOptions.height` 值設定為 `"38px"`，以最佳化搜尋列體驗。使用 `focusedHeight` 屬性來設定主題選取下拉式清單與問題建議清單的最佳大小。使用 `expandedHeight` 屬性來設定答案面板和 Pinboard 的最佳大小。如果您選擇 `'SEARCH_BAR'` 選項，建議您使用位置來設定父系容器的樣式；絕對要避免應用程式中不必要的內容轉移。下圖顯示當您將 `panelType` 值設定為 `'SEARCH_BAR'` 時轉譯的生成式問答功能搜尋列。

設定 `panelType` 屬性之後，請使用 Amazon Quick Sight 內嵌 SDK 來自訂生成式問答體驗的下列屬性。
+ 生成式問答面板的標題 (僅適用於 `panelType: FULL` 選項)。
+ 搜尋列的預留位置文字。
+ 是否允許主題選取。
+ 是否顯示或隱藏主題名稱。
+ 是否顯示或隱藏 Amazon Q 圖示 (僅適用於 `panelType: FULL` 選項)。
+ 是否顯示為隱藏 Pinboard。
+ 使用者是否可以將生成式問答面板最大化為全螢幕。
+ 生成式問答面板的佈景主題。自訂佈景主題 ARN 可在 SDK 中傳遞，以變更影格內容的外觀。內嵌生成 BI 面板不支援 Amazon Quick Sight 入門主題。若要使用 Amazon Quick Sight 入門佈景主題，請在 Amazon Quick Sight 中將其儲存為自訂佈景主題。

當您使用 Amazon Quick Sight 內嵌 SDK 時，頁面上的生成式問答體驗會根據 狀態動態調整大小。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制生成式問答體驗中的參數，並在頁面載入完成、狀態變更和錯誤方面接收回呼。

下列範例示範如何使用產生的 URL。此代碼在您的應用程式伺服器上生成。

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

若要讓此範例運作，請務必使用 Amazon Quick Sight 內嵌 SDK，透過 JavaScript 在您的網站上載入內嵌的生成式問答體驗。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

### 選用的嵌入生成式問答功能功能
<a name="embedded-analytics-gen-bi-authenticated-users-step-4"></a>

下列選用功能可在使用嵌入式 SDK 的嵌入生成式問答功能中使用。

#### 調用生成式問答搜尋列動作
<a name="w2aac35c27c21c43c29b9c21b5"></a>
+ 設定問題：此功能會將問題傳送至生成式問答功能，並立即查詢問題。

  ```
  embeddedGenerativeQnExperience.setQuestion('show me monthly revenue');
  ```
+ 關閉答案面板 (適用於生成式問答搜尋列選項)：此功能會關閉答案面板，並將 iframe 回復至原始搜尋列狀態。

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

如需詳細資訊，請參閱 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

## 為匿名 （未註冊） 使用者嵌入 Amazon Q in Quick Generative Q&A 體驗
<a name="embedded-analytics-gen-bi-anonymous-users"></a>


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在以下章節中，您可以找到有關如何為匿名 (未註冊) 使用者設定嵌入生成式問答功能的詳細資訊。

**Topics**
+ [

### 步驟 1：設定許可
](#embedded-analytics-gen-bi-anonymous-users-step-1)
+ [

### 步驟 2：產生帶有身分驗證碼的 URL
](#embedded-analytics-gen-bi-anonymous-users-step-2)
+ [

### 步驟 3：嵌入生成式問答功能 URL
](#embedded-analytics-gen-bi-anonymous-users-step-3)
+ [

### 選用的嵌入生成式問答功能功能
](#embedded-analytics-gen-bi-anonymous-users-step-4)

### 步驟 1：設定許可
<a name="embedded-analytics-gen-bi-anonymous-users-step-1"></a>

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可，以嵌入生成式問答功能。此任務需要 AWS Identity and Access Management (IAM) 的管理存取權。

每個存取生成式問答體驗的使用者都會擔任一個角色，為他們提供 Amazon Quick Sight 存取和許可。為了實現這一點，請在您的 AWS 帳戶中建立 IAM 角色。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。IAM 角色需要提供許可，以擷取特定使用者集區的內嵌 URL。

藉助萬用字元 *\$1*，您可以授予許可，以便為特定命名空間中的所有使用者產生 URL。或者，您可以授予許可來為特定命名空間中的使用者子集產生 URL。對於這一點，您新增 `quicksight:GenerateEmbedUrlForAnonymousUser`。

您可以在 IAM 政策中建立條件，以限制開發人員可在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 參數中列出的域。`AllowedDomains` 參數是選用參數。它可讓開發人員選擇覆寫在**管理 Amazon Quick Sight **選單中設定的靜態網域，並改為列出最多三個可存取產生 URL 的網域或子網域。然後將此 URL 內嵌到開發人員的網站中。只有參數中列出的域可以存取內嵌 Q 搜尋列。如果沒有這種情況，開發人員可以在 `AllowedDomains` 參數中列出網際網路上的任何域。

若要限制開發人員可搭配此參數使用的網域，請在 IAM 政策中新增 `AllowedEmbeddingDomains` 條件。如需 `AllowedDomains` 參數的詳細資訊，請參閱《*Amazon Quick Sight API 參考*》中的 [GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)。

**IAM 條件運算子的安全最佳實務**  
設定不當的 IAM 條件運算子可能會允許透過 URL 變化未經授權存取您的內嵌 Quick 資源。在 IAM 政策中使用 `quicksight:AllowedEmbeddingDomains`條件金鑰時，請使用允許特定網域或拒絕未明確允許的所有網域的條件運算子。如需 IAM 條件運算子的詳細資訊，請參閱《IAM [使用者指南》中的 IAM JSON 政策元素：條件運算子](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
許多不同的 URL 變化可以指向相同的資源。例如，下列 URLs全部解析為相同的內容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的政策使用未考慮這些 URL 變化的運算子，攻擊者可以透過提供同等的 URL 變化來繞過您的限制。  
您必須驗證 IAM 政策是否使用適當的條件運算子來防止繞過漏洞，並確保只有您預期的網域可以存取您的內嵌資源。

您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可代表使用者擔任該角色，並載入生成式問答功能。範例回應如下所示。

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

------

如需有關信任政策的詳細資訊，請參閱**《IAM 使用者指南》中的[ IAM 中的臨時安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)

### 步驟 2：產生帶有身分驗證碼的 URL
<a name="embedded-analytics-gen-bi-anonymous-users-step-2"></a>

在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌的 Q 主題 URL。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，應用程式會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

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

**注意**  
無法直接從瀏覽器呼叫嵌入式 URL 產生 API。請改為參閱 Node.JS 範例。

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

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

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

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來產生嵌入式 Q 搜尋列的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示 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>

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用 SAML 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `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` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。對於 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_q_search_bar_role/QuickSightEmbeddingAnonymousPolicy`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個使用者設定適當的許可。還能避免對使用者存取進行任何調節。*調節*是一項安全功能，可防止相同的使用者從多個位置存取 Amazon Quick Sight。此外，它使每個會話獨立且不同。如果您正在使用 Web 伺服器陣列 (例如負載平衡)，且工作階段重新連線到不同的伺服器，則會開始新的工作階段。

為了取得儀表板的簽章 URL，請從應用程式伺服器呼叫 `generate-embed-url-for-anynymous-user`。這會傳回可嵌入的儀表板 URL。下列範例會顯示如何使用伺服器端呼叫，針對匿名造訪您的 Web 入口網站或應用程式的使用者，產生內嵌式儀表板的 URL。

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

如需使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

### 步驟 3：嵌入生成式問答功能 URL
<a name="embedded-analytics-gen-bi-anonymous-users-step-3"></a>

在下一章節，您可以了解如何在網站或應用程式頁面中嵌入生成式問答功能 URL。您可以使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 來執行此操作。您可以使用此 SDK 執行以下操作：
+ 將生成式問答功能放置在 HTML 頁面上。
+ 自訂嵌入功能的版面配置和外觀，以符合您的應用程式需求。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

若要產生可以內嵌到應用程式中的 URL，請呼叫 `GenerateEmbedUrlForAnonymousUser` API 操作。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期最長為 10 小時。此 API 操作提供的 URL 附有可啟用單一登入工作階段的 `auth_code` 值。

以下是 `generate-embed-url-for-anonymous-user` 的回應範例。

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

使用 [Amazon Quick Sight 內嵌 SDK ](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)或將此 URL 新增至 iframe，在您的網頁中嵌入生成式問答體驗。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。

請確定託管生成式問答體驗的網域列於*允許清單*上，即 Amazon Quick Sight 訂閱的已核准網域清單。這項要求將使未獲核准的網域無法託管嵌入生成式問答功能，進而保護您的資料。如需為嵌入生成式問答功能新增網域的詳細資訊，請參閱[管理網域](manage-domains.md)。

您可以使用 Amazon Quick Sight 內嵌 SDK 自訂內嵌生成式問答體驗的配置和外觀，以符合您的應用程式。使用 `panelType` 屬性設定生成式問答功能在應用程式中轉譯時的登陸狀態。將 `panelType` 屬性設定為 `'FULL'`，以轉譯完整的生成式問答功能面板。此面板類似 Amazon Quick Sight 使用者在 Amazon Quick Sight 主控台中擁有的體驗。面板的影格高度不會根據使用者互動而變更，並且會遵守您在 `frameOptions.height` 屬性中設定的值。下圖顯示當您將 `panelType` 值設定為 `'FULL'` 時轉譯的生成式問答功能面板。

將 `panelType` 屬性設定為 `'SEARCH_BAR'`，以搜尋列形式轉譯生成式問答功能。此搜尋列類似於 Q 搜尋列在嵌入應用程式時轉譯的方式。生成式問答搜尋列會展開為較大面板，顯示主題選取選項、問題建議清單、答案面板或 Pinboard。

嵌入式資產載入時，會轉譯生成式問答搜尋列的預設最小高度。建議您將 `frameOptions.height` 值設定為 `"38px"`，以最佳化搜尋列體驗。使用 `focusedHeight` 屬性來設定主題選取下拉式清單與問題建議清單的最佳大小。使用 `expandedHeight` 屬性來設定答案面板和 Pinboard 的最佳大小。如果您選擇 `'SEARCH_BAR'` 選項，建議您使用位置來設定父系容器的樣式；絕對要避免應用程式中不必要的內容轉移。下圖顯示當您將 `panelType` 值設定為 `'SEARCH_BAR'` 時轉譯的生成式問答功能搜尋列。

設定 `panelType` 屬性之後，請使用 Amazon Quick Sight 內嵌 SDK 來自訂生成式問答體驗的下列屬性。
+ 生成式問答面板的標題 (僅適用於 `panelType: FULL` 選項)。
+ 搜尋列的預留位置文字。
+ 是否允許主題選取。
+ 是否顯示或隱藏主題名稱。
+ 是否顯示或隱藏 Amazon Q 圖示 (僅適用於 `panelType: FULL` 選項)。
+ 是否顯示為隱藏 Pinboard。
+ 使用者是否可以將生成式問答面板最大化為全螢幕。
+ 生成式問答面板的佈景主題。自訂佈景主題 ARN 可在 SDK 中傳遞，以變更影格內容的外觀。內嵌生成 BI 面板不支援 Amazon Quick Sight 入門主題。若要使用 Amazon Quick Sight 入門佈景主題，請在 Amazon Quick Sight 中將其儲存為自訂佈景主題。

當您使用 Amazon Quick Sight 內嵌 SDK 時，頁面上的生成式問答體驗會根據 狀態動態調整大小。使用 Amazon Quick Sight 內嵌 SDK，您也可以控制生成式問答體驗中的參數，並在頁面載入完成、狀態變更和錯誤方面接收回呼。

下列範例示範如何使用產生的 URL。此代碼在您的應用程式伺服器上生成。

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

若要讓此範例運作，請務必使用 Amazon Quick Sight 內嵌 SDK，透過 JavaScript 在您的網站上載入內嵌的生成式問答體驗。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

### 選用的嵌入生成式問答功能功能
<a name="embedded-analytics-gen-bi-anonymous-users-step-4"></a>

下列選用功能可在使用嵌入式 SDK 的嵌入生成式問答功能中使用。

#### 調用生成式問答搜尋列動作
<a name="w2aac35c27c21c43c29c13c25b5"></a>
+ 設定問題：此功能會將問題傳送至生成式問答功能，並立即查詢問題。

  ```
  embeddedGenerativeQnExperience.setQuestion('show me monthly revenue');
  ```
+ 關閉答案面板 (適用於生成式問答搜尋列選項)：此功能會關閉答案面板，並將 iframe 回復至原始搜尋列狀態。

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

如需詳細資訊，請參閱 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

# 內嵌 Amazon Quick Sight Q 搜尋列 （傳統）
<a name="embedding-quicksight-q"></a>


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

使用下列主題來了解如何使用 Amazon Quick Sight APIs 內嵌 Amazon Quick Sight Q 搜尋列。

**Topics**
+ [

# 內嵌已註冊使用者的 Amazon Quick Sight Q 搜尋列
](embedded-analytics-q-search-bar-for-authenticated-users.md)
+ [

# 為匿名 （未註冊） 使用者嵌入 Amazon Quick Sight Q 搜尋列
](embedded-analytics-q-search-bar-for-anonymous-users.md)

# 內嵌已註冊使用者的 Amazon Quick Sight Q 搜尋列
<a name="embedded-analytics-q-search-bar-for-authenticated-users"></a>


|  | 
| --- |
|  適用於：企業版本  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在下列各節中，您可以找到有關如何為 Amazon Quick Sight 註冊使用者設定內嵌 Amazon Quick Sight Q 搜尋列的詳細資訊。

**Topics**
+ [

## 步驟 1：設定許可
](#embedded-q-bar-for-authenticated-users-step-1)
+ [

## 步驟 2：產生帶有身分驗證碼的 URL
](#embedded-q-bar-for-authenticated-users-step-2)
+ [

## 步驟 3：內嵌 Q 搜尋列 URL
](#embedded-q-bar-for-authenticated-users-step-3)
+ [

## 選用的 Amazon Quick Sight Q 搜尋列內嵌功能
](#embedded-q-bar-for-authenticated-users-step-4)

## 步驟 1：設定許可
<a name="embedded-q-bar-for-authenticated-users-step-1"></a>

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可以嵌入 Q 搜尋列。此任務需要 AWS Identity and Access Management (IAM) 的管理存取權。

每個存取儀表板的使用者都會擔任一個角色，為他們提供儀表板的 Amazon Quick Sight 存取權和許可。若要實現此目的，請在 中建立 IAM 角色 AWS 帳戶。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。IAM 角色需要提供許可，以擷取特定使用者集區的內嵌 URL。

藉助萬用字元 *\$1*，您可以授予許可，以便為特定命名空間中的所有使用者產生 URL。或者，您可以授予許可來為特定命名空間中的使用者子集產生 URL。對於這一點，您新增 `quicksight:GenerateEmbedUrlForRegisteredUser`。

您可以在 IAM 政策中建立條件，以限制開發人員可在 `GenerateEmbedUrlForRegisteredUser` API 操作的 `AllowedDomains` 參數中列出的域。`AllowedDomains` 參數是選用參數。它可讓開發人員選擇覆寫在**管理 Amazon Quick Sight **選單中設定的靜態網域，並改為列出最多三個可存取產生 URL 的網域或子網域。然後將此 URL 內嵌到開發人員的網站中。只有參數中列出的域可以存取內嵌 Q 搜尋列。如果沒有這種情況，開發人員可以在 `AllowedDomains` 參數中列出網際網路上的任何域。

若要限制開發人員可搭配此參數使用的網域，請在 IAM 政策中新增 `AllowedEmbeddingDomains` 條件。如需 `AllowedDomains` 參數的詳細資訊，請參閱《*Amazon Quick Sight API 參考*》中的 [GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。

**IAM 條件運算子的安全最佳實務**  
設定不當的 IAM 條件運算子可能會允許透過 URL 變化未經授權存取您的內嵌 Quick 資源。在 IAM 政策中使用 `quicksight:AllowedEmbeddingDomains`條件金鑰時，請使用允許特定網域或拒絕未明確允許的所有網域的條件運算子。如需 IAM 條件運算子的詳細資訊，請參閱《IAM [使用者指南》中的 IAM JSON 政策元素：條件運算子](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
許多不同的 URL 變化可以指向相同的資源。例如，下列 URLs全部解析為相同的內容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的政策使用未考慮這些 URL 變化的運算子，攻擊者可以透過提供同等的 URL 變化來繞過您的限制。  
您必須驗證 IAM 政策是否使用適當的條件運算子來防止繞過漏洞，並確保只有您預期的網域可以存取您的內嵌資源。

下列範例政策提供這些許可。

此外，如果您要建立將成為 Amazon Quick Sight 讀者的第一次使用者，請務必在政策中新增 `quicksight:RegisterUser`許可。

下列範例政策提供許可，以擷取初次成為 Amazon Quick Sight 讀取器之使用者的內嵌 URL。

最後，您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可以代表使用者擔任該角色，並在 Amazon Quick Sight 中佈建使用者。

範例信任政策如下所示。

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

------

如需 OpenID Connect 或安全性聲明標記語言 (SAML) 身分驗證的信任政策詳細資訊，請參閱《IAM 使用者指南》**的下列各章節：
+ [建立 Web 身分的角色或 OpenID Connect 聯合身分 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [為 SAML 2.0 聯合身分建立角色 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

## 步驟 2：產生帶有身分驗證碼的 URL
<a name="embedded-q-bar-for-authenticated-users-step-2"></a>

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可嵌入的 Q 主題 URL。如果您打算內嵌 IAM 或 Amazon Quick Sight 身分類型的 Q 列，請與使用者共用 Q 主題。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，應用程式會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

執行所述的步驟可確保 Q 主題的每個檢視器都是在 Amazon Quick Sight 中唯一佈建。它還會強制執行個別使用者設定，例如資料列層級的安全性和參數的動態預設值。

下列範例會代表使用者執行 IAM 身分驗證。此代碼在您的應用程式伺服器上運行。

### Java
<a name="embedded-q-bar-for-embedded-q-bar-for-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.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();
            }
        }
```

### JavaScript
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-js"></a>

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

### Python3
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-python"></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 = {
                    "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)
```

### Node.js
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-node"></a>

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

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

**Example**  

```
//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/C\$1
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-cs"></a>

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來產生嵌入式 Q 搜尋列的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示 Q 搜尋列。

**Example**  

```
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 CLI
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-cli"></a>

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用 SAML 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GenerateEmbedUrlForRegisteredUser` 的許可。如果您正在採取即時方法在使用者使用 Q 搜尋列中的主題時新增使用者，則該角色還需要啟用 `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\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。對於 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_q_search_bar_role/john.doe@example.com`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個使用者設定適當的許可。還能避免對使用者存取進行任何調節。*調節*是一項安全功能，可防止相同的使用者從多個位置存取 Amazon Quick Sight。

角色工作階段 ID 也會成為 Amazon Quick Sight 中的使用者名稱。您可以使用此模式提前在 Amazon Quick Sight 中佈建您的使用者，或在他們第一次存取 Q 搜尋列時佈建他們。

以下範例顯示可用來佈建使用者的 CLI 命令。如需 [RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html) 和其他 Amazon Quick Sight API 操作的詳細資訊，請參閱 [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_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` 設定他們。反之，他們應該在第一次存取 Amazon Quick Sight 時自動訂閱。若是 Microsoft AD 使用者，您可以使用 `DescribeUser` 取得使用者的 Amazon Resource Name (ARN)。

使用者第一次存取 Amazon Quick Sight 時，您也可以將此使用者新增至與儀表板共用的群組。以下範例顯示用於將使用者新增至群組的 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"
```

您現在擁有應用程式的使用者，他們也是 Amazon Quick Sight 的使用者，以及有權存取儀表板的使用者。

最後，為了取得儀表板的簽章 URL，請從應用程式伺服器呼叫 `generate-embed-url-for-registered-user`。這會傳回可嵌入的儀表板 URL。下列範例示範如何使用伺服器端呼叫為透過 AWS Managed Microsoft AD 或單一登入 (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}
```

如需使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

## 步驟 3：內嵌 Q 搜尋列 URL
<a name="embedded-q-bar-for-authenticated-users-step-3"></a>

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在下一章節，您可以了解如何將步驟 3 中的 Q 搜尋列 URL 嵌入到網站或應用程式頁面中。您可以使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 來執行此操作。您可以使用此 SDK 執行以下操作：
+ 將 Q 搜尋列放置在 HTML 頁面上。
+ 將參數傳遞至 Q 搜尋列。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

若要產生可以內嵌到應用程式中的 URL，請呼叫 `GenerateEmbedUrlForRegisteredUser` API 操作。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期最長為 10 小時。此 API 操作提供的 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"
}
```

使用 [Amazon Quick Sight 內嵌 SDK ](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)或將此 URL 新增至 iframe，在網頁中內嵌 Q 搜尋列。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。

若要這樣做，請確定託管內嵌 Q 搜尋列的網域位於*允許清單*上，即 Amazon Quick Sight 訂閱的已核准網域清單。這項要求將使未獲核准的網域無法託管嵌入儀表板，進而保護您的資料。如需為內嵌 Q 搜尋列新增網域的詳細資訊，請參閱[管理網域和內嵌](https://docs.aws.amazon.com/quicksight/latest/user/manage-qs-domains-and-embedding.html)。

當您使用 Amazon Quick Sight 內嵌 SDK 時，頁面上的 Q 搜尋列會根據狀態動態調整大小。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制 Q 搜尋列中的參數，並根據頁面載入完成和錯誤接收回呼。

下列範例示範如何使用產生的 URL。此代碼在您的應用程式伺服器上生成。

### SDK 2.0
<a name="embedded-q-bar-for-authenticated-users-sdkv2"></a>

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

### SDK 1.0
<a name="embedded-q-bar-for-authenticated-users-sdkv1"></a>

```
<!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 Quick Sight 內嵌 SDK，使用 JavaScript 在您的網站上載入內嵌儀表板。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

## 選用的 Amazon Quick Sight Q 搜尋列內嵌功能
<a name="embedded-q-bar-for-authenticated-users-step-4"></a>

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

下列選用功能可供使用嵌入 SDK 的嵌入式 Q 搜尋列使用。

### 調用 Q 搜尋列動作
<a name="w2aac35c27c21c43c31c15c21b7"></a>

下列選項僅支援 Q 搜尋列內嵌。
+ 設定 Q 搜尋列問題 – 此功能會將問題傳送至 Q 搜尋列，並立即查詢問題。它也會自動開啟 Q 快顯。

  ```
  qBar.setQBarQuestion('show me monthly revenue');
  ```
+ 關閉 Q 快顯 – 此功能關閉 Q 快顯窗口，並將 iframe 回復至原來的 Q 搜尋列大小。

  ```
  qBar.closeQPopover();
  ```

如需詳細資訊，請參閱 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

# 為匿名 （未註冊） 使用者嵌入 Amazon Quick Sight Q 搜尋列
<a name="embedded-analytics-q-search-bar-for-anonymous-users"></a>


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在下列各節中，您可以找到有關如何為匿名 （未註冊） 使用者設定內嵌 Amazon Quick Sight Q 搜尋列的詳細資訊。

**Topics**
+ [

## 步驟 1：設定許可
](#embedded-q-bar-for-anonymous-users-step-1)
+ [

## 步驟 2：產生帶有身分驗證碼的 URL
](#embedded-q-bar-for-anonymous-users-step-2)
+ [

## 步驟 3：內嵌 Q 搜尋列 URL
](#embedded-q-bar-for-anonymous-users-step-3)
+ [

## 選用的 Amazon Quick Sight Q 搜尋列內嵌功能
](#embedded-q-bar-for-anonymous-users-step-4)

## 步驟 1：設定許可
<a name="embedded-q-bar-for-anonymous-users-step-1"></a>

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可以嵌入 Q 搜尋列。此任務需要 AWS Identity and Access Management (IAM) 的管理存取權。

每個存取 Q 搜尋列的使用者都會擔任一個角色，該角色會授予他們 Amazon Quick Sight 存取和 Q 搜尋列的許可。若要實現這一點，請在 中建立 IAM 角色 AWS 帳戶。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。IAM 角色需要提供許可，以擷取特定使用者集區的內嵌 URL。

藉助萬用字元 *\$1*，您可以授予許可，以便為特定命名空間中的所有使用者產生 URL。或者，您可以授予許可來為特定命名空間中的使用者子集產生 URL。對於這一點，您新增 `quicksight:GenerateEmbedUrlForAnonymousUser`。

您可以在 IAM 政策中建立條件，以限制開發人員可在 `GenerateEmbedUrlForAnonymousUser` API 操作的 `AllowedDomains` 參數中列出的域。`AllowedDomains` 參數是選用參數。它可讓開發人員選擇覆寫在**管理 Amazon Quick Sight **選單中設定的靜態網域，並改為列出最多三個可以存取產生 URL 的網域或子網域。然後將此 URL 內嵌到開發人員的網站中。只有參數中列出的域可以存取內嵌 Q 搜尋列。如果沒有這種情況，開發人員可以在 `AllowedDomains` 參數中列出網際網路上的任何域。

若要限制開發人員可搭配此參數使用的網域，請在 IAM 政策中新增 `AllowedEmbeddingDomains` 條件。如需 `AllowedDomains` 參數的詳細資訊，請參閱《*Amazon Quick Sight API 參考*》中的 [GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)。

**IAM 條件運算子的安全最佳實務**  
設定不當的 IAM 條件運算子可能會允許透過 URL 變化未經授權存取您的內嵌 Quick 資源。在 IAM 政策中使用 `quicksight:AllowedEmbeddingDomains`條件金鑰時，請使用允許特定網域或拒絕未明確允許的所有網域的條件運算子。如需 IAM 條件運算子的詳細資訊，請參閱《IAM [使用者指南》中的 IAM JSON 政策元素：條件運算子](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)。  
許多不同的 URL 變化可以指向相同的資源。例如，下列 URLs都會解析為相同的內容：  
`https://example.com`
`https://example.com/`
`https://Example.com`
如果您的政策使用未考慮這些 URL 變化的運算子，攻擊者可以透過提供同等的 URL 變化來繞過您的限制。  
您必須驗證 IAM 政策是否使用適當的條件運算子來防止繞過漏洞，並確保只有您預期的網域可以存取您的內嵌資源。

您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可代表使用者擔任該角色，並開啟 Q 搜尋列。範例回應如下所示。

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

------

如需有關信任政策的詳細資訊，請參閱**《IAM 使用者指南》中的[ IAM 中的臨時安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)

## 步驟 2：產生帶有身分驗證碼的 URL
<a name="embedded-q-bar-for-anonymous-users-step-2"></a>

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可嵌入的 Q 主題 URL。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，應用程式會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

如需詳細資訊，請參閱[https://docs.aws.amazon.com/quicksight/latest/APIReference/AnonymousUserQSearchBarEmbeddingConfiguration.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/AnonymousUserQSearchBarEmbeddingConfiguration.html)。

### Java
<a name="embedded-q-bar-for-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.AnonymousUserQSearchBarEmbeddingConfiguration;
        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 SEARCHBAR PREPOPULATES INITIALLY
                final String namespace, // ANONYMOUS EMBEDDING REQUIRES SPECIFYING A VALID NAMESPACE FOR WHICH YOU WANT THE EMBEDDING URL
                final List<String> authorizedResourceArns, // Q SEARCHBAR 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();
                AnonymousUserQSearchBarEmbeddingConfiguration qSearchBarConfiguration = new AnonymousUserQSearchBarEmbeddingConfiguration();
                qSearchBarConfiguration.setInitialTopicId(initialTopicId);
                experienceConfiguration.setQSearchBar(qSearchBarConfiguration);

                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 qSearchBarEmbedUrl = quickSightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserRequest);

                return qSearchBarEmbedUrl.getEmbedUrl();
            }

        }
```

### JavaScript
<a name="embedded-q-bar-for-anonymous-users-js"></a>

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

function generateEmbedUrlForAnonymousUser(
    accountId, // YOUR AWS ACCOUNT ID
    initialTopicId, // Q TOPIC ID TO WHICH THE CONSTRUCTED URL POINTS
    quicksightNamespace, // VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
    authorizedResourceArns, // Q SEARCHBAR TOPIC ARN LIST TO EMBED
    allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
    sessionTags, // SESSION TAGS USED FOR ROW-LEVEL SECURITY
    generateEmbedUrlForAnonymousUserCallback, // SUCCESS CALLBACK METHOD
    errorCallback // ERROR CALLBACK METHOD
    ) {
    const experienceConfiguration = {
        "QSearchBar": {
            "InitialTopicId": initialTopicId // TOPIC ID CAN BE FOUND IN THE URL ON THE TOPIC AUTHOR PAGE
        }
    };
    
    const generateEmbedUrlForAnonymousUserParams = {
        "AwsAccountId": accountId,
        "Namespace": quicksightNamespace,
        "AuthorizedResourceArns": authorizedResourceArns,
        "AllowedDomains": allowedDomains,
        "ExperienceConfiguration": experienceConfiguration,
        "SessionTags": sessionTags,
        "SessionLifetimeInMinutes": 600
    };

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

    quicksightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserParams, 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 THIS API
                    "Access-Control-Allow-Headers": "Content-Type"
                },
                "body": JSON.stringify(data),
                "isBase64Encoded": false
            }
            generateEmbedUrlForAnonymousUserCallback(result);
        }
    });
}
```

### Python3
<a name="embedded-q-bar-for-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
# quicksightNamespace: VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
# authorizedResourceArns: TOPIC ARN LIST TO EMBED
# allowedDomains: RUNTIME ALLOWED DOMAINS FOR EMBEDDING
# experienceConfiguration: configuration which specifies the TOPIC ID to point URL to
# sessionTags: SESSION TAGS USED FOR ROW-LEVEL SECURITY
def generateEmbedUrlForAnonymousUser(accountId, quicksightNamespace, authorizedResourceArns, allowedDomains, experienceConfiguration, sessionTags):
    try:
        response = quicksightClient.generate_embed_url_for_anonymous_user(
            AwsAccountId = accountId,
            Namespace = quicksightNamespace,
            AuthorizedResourceArns = authorizedResourceArns,
            AllowedDomains = allowedDomains,
            ExperienceConfiguration = experienceConfiguration,
            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-q-bar-for-anonymous-users-nodejs"></a>

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來產生嵌入式儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
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.generateEmbedUrlForAnonymousUser({
    'AwsAccountId': '111122223333',
    'Namespace': 'DEFAULT'
    'AuthorizedResourceArns': '["topic-arn-topicId1","topic-arn-topicId2"]',
    'AllowedDomains': allowedDomains,
    'ExperienceConfiguration': { 
        'QSearchBar': {
            '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);
});
```

**Example**  

```
//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/C\$1
<a name="embedded-q-bar-for-anonymous-users-cs"></a>

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來產生嵌入式 Q 搜尋列的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示 Q 搜尋列。

**Example**  

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

namespace GenerateQSearchBarEmbedUrlForAnonymousUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                AnonymousUserQSearchBarEmbeddingConfiguration anonymousUserQSearchBarEmbeddingConfiguration
                    = new AnonymousUserQSearchBarEmbeddingConfiguration
                    {
                        InitialTopicId = "U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f"
                    };
                AnonymousUserEmbeddingExperienceConfiguration anonymousUserEmbeddingExperienceConfiguration
                    = new AnonymousUserEmbeddingExperienceConfiguration
                    {
                        QSearchBar = anonymousUserQSearchBarEmbeddingConfiguration
                    }; 
                
                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-q-bar-for-anonymous-users-cli"></a>

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用 SAML 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GenerateEmbedUrlForAnonymousUser` 的許可。

```
aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_search_bar_role" \
     --role-session-name anonymous caller
```

`assume-role` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。對於 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_q_search_bar_role/QuickSightEmbeddingAnonymousPolicy`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個使用者設定適當的許可。還能避免對使用者存取進行任何調節。*調節*是一項安全功能，可防止相同的使用者從多個位置存取 Amazon Quick Sight。此外，它使每個會話獨立且不同。如果您正在使用 Web 伺服器陣列 (例如負載平衡)，且工作階段重新連線到不同的伺服器，則會開始新的工作階段。

為了取得儀表板的簽章 URL，請從應用程式伺服器呼叫 `generate-embed-url-for-anynymous-user`。這會傳回可嵌入的儀表板 URL。下列範例會顯示如何使用伺服器端呼叫，針對匿名造訪您的 Web 入口網站或應用程式的使用者，產生內嵌式儀表板的 URL。

```
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 'QSearchBar={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
```

如需使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

## 步驟 3：內嵌 Q 搜尋列 URL
<a name="embedded-q-bar-for-anonymous-users-step-3"></a>

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

在下一章節，您可以了解如何將步驟 3 中的 Q 搜尋列 URL 嵌入到網站或應用程式頁面中。您可以使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript) 來執行此操作。您可以使用此 SDK 執行以下操作：
+ 將 Q 搜尋列放置在 HTML 頁面上。
+ 將參數傳遞至 Q 搜尋列。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

若要產生可以內嵌到應用程式中的 URL，請呼叫 `GenerateEmbedUrlForAnonymousUser` API 操作。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期最長為 10 小時。此 API 操作提供的 URL 附有可啟用單一登入工作階段的 `auth_code` 值。

以下是 `generate-embed-url-for-anonymous-user` 的回應範例。

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

使用 [Amazon Quick Sight 內嵌 SDK ](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)或將此 URL 新增至 iframe，在網頁中內嵌 Q 搜尋列。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。

若要這樣做，請確定託管內嵌 Q 搜尋列的網域位於*允許清單*上，即 Amazon Quick Sight 訂閱的已核准網域清單。這項要求將使未獲核准的域無法託管內嵌 Q 搜尋列，進而保護您的資料。如需為內嵌 Q 搜尋列新增網域的詳細資訊，請參閱[管理網域和內嵌](https://docs.aws.amazon.com/quicksight/latest/user/manage-qs-domains-and-embedding.html)。

當您使用 Amazon Quick Sight 內嵌 SDK 時，頁面上的 Q 搜尋列會根據狀態動態調整大小。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制 Q 搜尋列中的參數，並根據頁面載入完成和錯誤接收回呼。

下列範例示範如何使用產生的 URL。此代碼在您的應用程式伺服器上生成。

### SDK 2.0
<a name="embedded-q-bar-for-anonymous-users-sdkv2"></a>

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

### SDK 1.0
<a name="embedded-q-bar-for-anonymous-users-sdkv1"></a>

```
<!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 Quick Sight 內嵌 SDK，使用 JavaScript 在您的網站上載入內嵌的 Q 搜尋列。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

## 選用的 Amazon Quick Sight Q 搜尋列內嵌功能
<a name="embedded-q-bar-for-anonymous-users-step-4"></a>

**注意**  
內嵌的 Amazon Quick Sight Q 搜尋列提供傳統 Amazon Quick Sight Q&A 體驗。Amazon Quick Sight 與 Amazon Q Business 整合，以啟動新的生成式問答體驗。建議開發人員使用新的生成式問答功能。如需內嵌生成式問答體驗的詳細資訊，請參閱[在 Amazon Quick Sight 生成式問答體驗中內嵌 Amazon Q](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html)。

下列選用功能可供使用嵌入 SDK 的嵌入式 Q 搜尋列使用。

### 調用 Q 搜尋列動作
<a name="w2aac35c27c21c43c31c17c21b7"></a>

下列選項僅支援 Q 搜尋列內嵌。
+ 設定 Q 搜尋列問題 – 此功能會將問題傳送至 Q 搜尋列，並立即查詢問題。它也會自動開啟 Q 快顯。

  ```
  qBar.setQBarQuestion('show me monthly revenue');
  ```
+ 關閉 Q 快顯 – 此功能關閉 Q 快顯窗口，並將 iframe 回復至原來的 Q 搜尋列大小。

  ```
  qBar.closeQPopover();
  ```

如需詳細資訊，請參閱 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

# 使用 GetDashboardEmbedURL 和 GetSessionEmbedURL API 操作內嵌分析
<a name="embedded-analytics-deprecated"></a>


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

下列用於內嵌 Amazon Quick Sight 儀表板和 Amazon Quick Sight 主控台的 API 操作已由 GenerateEmbedUrlForAnonymousUser和 GenerateEmbedUrlForRegisteredUser API 操作取代。您仍然可以使用它們在應用程式中內嵌分析，但它們不再維護，也不包含最新的內嵌特性或功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)
+ [GetDashboardEmbedUrl](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetDashboardEmbedUrl.html) API 操作可內嵌互動式儀表板。
+ [GetSessionEmbedUrl](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetSessionEmbedUrl.html) API 操作內嵌 Amazon Quick Sight 主控台。

**Topics**
+ [

# 使用 GetDashboardEmbedURL (舊 API) 為所有人內嵌儀表板
](embedded-analytics-dashboards-with-anonymous-users-get.md)
+ [

# 使用 GetDashboardEmbedUrl (舊 API) 為已註冊使用者內嵌儀表板
](embedded-analytics-dashboards-for-authenticated-users-get.md)
+ [

# 使用 嵌入 Amazon Quick Sight 主控台 GetSessionEmbedUrl（舊 API)
](embedded-analytics-full-console-for-authenticated-users-get.md)

# 使用 GetDashboardEmbedURL (舊 API) 為所有人內嵌儀表板
<a name="embedded-analytics-dashboards-with-anonymous-users-get"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下列各節中，您可以找到如何使用 GetDashboardEmbedURL 為每個人 （未驗證的使用者） 設定內嵌 Amazon Quick Sight 儀表板的詳細資訊。

**Topics**
+ [

# 步驟 1：設定許可
](embedded-analytics-dashboards-with-anonymous-users-get-step-1.md)
+ [

# 步驟 2：獲取帶有身分驗證碼的 URL
](embedded-analytics-dashboards-with-anonymous-users-get-step-2.md)
+ [

# 步驟 3：內嵌儀表板 URL
](embedded-analytics-dashboards-with-anonymous-users-get-step-3.md)

# 步驟 1：設定許可
<a name="embedded-analytics-dashboards-with-anonymous-users-get-step-1"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可。這個任務需要有 IAM 的管理存取權。

每個存取儀表板的使用者都會擔任一個角色，為他們提供儀表板的 Amazon Quick Sight 存取權和許可。若要實現這一點，請在 AWS 您的帳戶中建立 IAM 角色。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。

下列範例政策提供搭配 `IdentityType=ANONYMOUS` 使用的許可。若要使用此方法，您也需要在 AWS 帳戶中使用工作階段套件或工作階段容量定價。否則，當使用者嘗試存取儀表板時，會傳回錯誤 `UnsupportedPricingPlanException`。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
              "quicksight:GetDashboardEmbedUrl",
              "quickSight:GetAnonymousUserEmbedUrl"
            ],
            "Resource": "*"
        }
    ]
}
```

------

您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可代表使用者擔任該角色，並開啟儀表板。以下範例顯示稱為 `QuickSightEmbeddingAnonymousPolicy` 的角色，其前面有範例政策做為資源。

如需有關信任政策的詳細資訊，請參閱**《IAM 使用者指南》中的[ IAM 中的臨時安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。

# 步驟 2：獲取帶有身分驗證碼的 URL
<a name="embedded-analytics-dashboards-with-anonymous-users-get-step-2"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下一章節，您可以了解如何在您的應用程式伺服器上代表匿名訪客進行身分驗證，以及取得可內嵌的儀表板 URL。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，它會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

下列範例會代表使用者執行 IAM 身分驗證。它傳遞識別符當作唯一的角色工作階段 ID。此代碼在您的應用程式伺服器上運行。

------
#### [ Java ]

```
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.GetDashboardEmbedUrlRequest;
import com.amazonaws.services.quicksight.model.GetDashboardEmbedUrlResult;

/**
 * Class to call QuickSight AWS SDK to get url for dashboard embedding.
 */
public class GetQuicksightEmbedUrlNoAuth {

    private static String ANONYMOUS = "ANONYMOUS";

    private final AmazonQuickSight quickSightClient;

    public GetQuicksightEmbedUrlNoAuth() {
        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, // YOUR AWS ACCOUNT ID
            final String dashboardId, // YOUR DASHBOARD ID TO EMBED
            final String addtionalDashboardIds, // ADDITIONAL DASHBOARD-1 ADDITIONAL DASHBOARD-2
            final boolean resetDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
            final boolean undoRedoDisabled // OPTIONAL PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
    ) throws Exception {
        GetDashboardEmbedUrlRequest getDashboardEmbedUrlRequest = new GetDashboardEmbedUrlRequest()
                .withDashboardId(dashboardId)
                .withAdditionalDashboardIds(addtionalDashboardIds)
                .withAwsAccountId(accountId)
                .withNamespace("default") // Anonymous embedding requires specifying a valid namespace for which you want the embedding url
                .withIdentityType(ANONYMOUS)
                .withResetDisabled(resetDisabled)
                .withUndoRedoDisabled(undoRedoDisabled);

        GetDashboardEmbedUrlResult dashboardEmbedUrl = quickSightClient.getDashboardEmbedUrl(getDashboardEmbedUrlRequest);

        return dashboardEmbedUrl.getEmbedUrl();
    }
}
```

------
#### [ JavaScript ]

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

function getDashboardEmbedURL(
    accountId, // YOUR AWS ACCOUNT ID
    dashboardId, // YOUR DASHBOARD ID TO EMBED
    additionalDashboardIds, // ADDITIONAL DASHBOARD-1 ADDITIONAL DASHBOARD-2
    quicksightNamespace, // VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
    resetDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
    undoRedoDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
    getEmbedUrlCallback, // GETEMBEDURL SUCCESS CALLBACK METHOD
    errorCallback // GETEMBEDURL ERROR CALLBACK METHOD
    ) {
    const getDashboardParams = {
        AwsAccountId: accountId,
        DashboardId: dashboardId,
        AdditionalDashboardIds: additionalDashboardIds,
        Namespace: quicksightNamespace,
        IdentityType: 'ANONYMOUS',
        ResetDisabled: resetDisabled,
        SessionLifetimeInMinutes: 600,
        UndoRedoDisabled: undoRedoDisabled
    };

    const quicksightGetDashboard = new AWS.QuickSight({
        region: process.env.AWS_REGION,
    });

    quicksightGetDashboard.getDashboardEmbedUrl(getDashboardParams, 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);
        }
    });
}
```

------
#### [ Python3 ]

```
import json
import boto3
from botocore.exceptions import ClientError
import time

# Create QuickSight and STS clients
qs = boto3.client('quicksight',region_name='us-east-1')
sts = boto3.client('sts')

# Function to generate embedded URL
# accountId: YOUR AWS ACCOUNT ID
# dashboardId: YOUR DASHBOARD ID TO EMBED
# additionalDashboardIds: ADDITIONAL DASHBOARD-1 ADDITIONAL DASHBOARD-2 WITHOUT COMMAS
# quicksightNamespace: VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
# resetDisabled: PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
# undoRedoDisabled: OPTIONAL PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
def getDashboardURL(accountId, dashboardId, quicksightNamespace, resetDisabled, undoRedoDisabled):
    try:
        response = qs.get_dashboard_embed_url(
            AwsAccountId = accountId,
            DashboardId = dashboardId,
            AdditionalDashboardIds = additionalDashboardIds,
            Namespace = quicksightNamespace,
            IdentityType = 'ANONYMOUS',
            SessionLifetimeInMinutes = 600,
            UndoRedoDisabled = undoRedoDisabled,
            ResetDisabled = resetDisabled
        )
            
        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 ]

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來取得嵌入儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
const AWS = require('aws-sdk');
            const https = require('https');
            
            var quicksight = new AWS.Service({
                apiConfig: require('./quicksight-2018-04-01.min.json'),
                region: 'us-east-1',
            });
            
            quicksight.getDashboardEmbedUrl({
                'AwsAccountId': '111122223333',
                'DashboardId': 'dashboard-id',
                'AdditionalDashboardIds': 'added-dashboard-id-1 added-dashboard-id-2 added-dashboard-id-3'
                'Namespace' : 'default',
                'IdentityType': 'ANONYMOUS',
                'SessionLifetimeInMinutes': 100,
                'UndoRedoDisabled': false,
                'ResetDisabled': true
            
            }, function(err, data) {
                console.log('Errors: ');
                console.log(err);
                console.log('Response: ');
                console.log(data);
            });
```

**Example**  

```
//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://dashboards.example.com/embed/620bef10822743fab329fb3751187d2d…
              RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' }
```

------
#### [ .NET/C\$1 ]

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來取得嵌入儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
            var client = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                sessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                Console.WriteLine(
                    client.GetDashboardEmbedUrlAsync(new GetDashboardEmbedUrlRequest
                    {
                        AwsAccountId = “111122223333”,
                        DashboardId = "dashboard-id",
                        AdditionalDashboardIds = "added-dashboard-id-1 added-dashboard-id-2 added-dashboard-id-3",
                        Namespace = default,
                        IdentityType = IdentityType.ANONYMOUS,
                        SessionLifetimeInMinutes = 600,
                        UndoRedoDisabled = false,
                        ResetDisabled = true
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
```

------
#### [ AWS CLI ]

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用安全性聲明標記語言 (SAML) 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GetDashboardEmbedURL` 的許可。

```
aws sts assume-role \
     --role-arn "arn:aws:iam::11112222333:role/QuickSightEmbeddingAnonymousPolicy" \
     --role-session-name anonymous caller
```

`assume-role` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。如果您使用 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_dashboard_role/QuickSightEmbeddingAnonymousPolicy`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個訪問使用者設定適當的許可。它還使每個會話獨立且不同。如果您正在使用 Web 伺服器陣列 (例如負載平衡)，且工作階段重新連線到不同的伺服器，則會開始新的工作階段。

為了取得儀表板的簽章 URL，請從應用程式伺服器呼叫 `get-dashboard-embed-url`。這會傳回可嵌入的儀表板 URL。下列範例顯示如何使用伺服器端呼叫，針對匿名造訪您的 Web 入口網站或應用程式的使用者，獲取內嵌式儀表板的 URL。

```
aws quicksight get-dashboard-embed-url \
     --aws-account-id 111122223333 \
     --dashboard-id dashboard-id \
     --additional-dashboard-ids added-dashboard-id-1 added-dashboard-id-2 added-dashboard-id-3
     --namespace default-or-something-else \
     --identity-type ANONYMOUS \
     --session-lifetime-in-minutes 30 \
     --undo-redo-disabled true \
     --reset-disabled true \
     --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/QuickSightEmbeddingAnonymousPolicy/embeddingsession
```

如需有關使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetDashboardEmbedUrl.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetDashboardEmbedUrl.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

------

# 步驟 3：內嵌儀表板 URL
<a name="embedded-analytics-dashboards-with-anonymous-users-get-step-3"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下一節中，您可以了解如何使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript)，在網站或應用程式頁面的步驟 2 中內嵌儀表板 URL。您可以使用此 SDK 執行以下操作：
+ 將儀表板放在 HTML 頁面。
+ 將參數傳遞到儀表板。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

呼叫 `GetDashboardEmbedUrl` API 操作以獲得可內嵌應用程式的 URL。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期為 10 小時。此 API 操作提供的 URL 附有可啟用單一登入工作階段的 `auth_code`。

以下是 `get-dashboard-embed-url` 的回應範例。

```
//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: //dashboards.example.com/embed/620bef10822743fab329fb3751187d2d...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 Amazon Quick Sight [內嵌 SDK ](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)或將此 URL 新增至 iframe，將此儀表板內嵌在您的網頁中。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制儀表板中的參數，並根據頁面載入完成和錯誤接收回呼。

下列範例示範如何使用產生的 URL。此代碼駐留在您的應用程式伺服器上。

```
<!DOCTYPE html>
<html>

<head>
    <title>Basic Embed</title>
    <!-- You can download the latest QuickSight embedding SDK version from https://www.npmjs.com/package/amazon-quicksight-embedding-sdk -->
    <!-- Or you can do "npm install amazon-quicksight-embedding-sdk", if you use npm for javascript dependencies -->
    <script src="./quicksight-embedding-js-sdk.min.js"></script>
    <script type="text/javascript">
        var dashboard;

        function embedDashboard() {
            var containerDiv = document.getElementById("embeddingContainer");
            var options = {
                // replace this dummy url with the one generated via embedding API
                url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",  
                container: containerDiv,
                scrolling: "no",
                height: "700px",
                width: "1000px",
                footerPaddingEnabled: true
            };
            dashboard = QuickSightEmbedding.embedDashboard(options);
        }
    </script>
</head>

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

</html>
```

若要讓此範例運作，請務必使用 Amazon Quick Sight 內嵌 SDK，使用 JavaScript 在您的網站上載入內嵌儀表板。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的 QuickSight 內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

# 使用 GetDashboardEmbedUrl (舊 API) 為已註冊使用者內嵌儀表板
<a name="embedded-analytics-dashboards-for-authenticated-users-get"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。

在下列各節中，您可以找到如何使用 為已註冊使用者設定內嵌 Amazon Quick Sight 儀表板的詳細資訊`GetDashboardEmbedUrl`。

**Topics**
+ [

# 步驟 1：設定許可
](embedded-dashboards-for-authenticated-users-get-step-1.md)
+ [

# 步驟 2：獲取帶有身分驗證碼的 URL
](embedded-dashboards-for-authenticated-users-get-step-2.md)
+ [

# 步驟 3：內嵌儀表板 URL
](embedded-dashboards-for-authenticated-users-get-step-3.md)

# 步驟 1：設定許可
<a name="embedded-dashboards-for-authenticated-users-get-step-1"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可。這個任務需要有 IAM 的管理存取權。

每個存取儀表板的使用者都會擔任一個角色，為他們提供儀表板的 Amazon Quick Sight 存取權和許可。若要實現這一點，請在 AWS 您的帳戶中建立 IAM 角色。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。IAM 角色需要提供擷取儀表板 URL 的許可。對於這一點，您新增 `quicksight:GetDashboardEmbedUrl`。

下列範例政策提供搭配 `IdentityType=IAM` 使用的許可。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "quicksight:GetDashboardEmbedUrl"
            ],
            "Resource": "*"
        }
    ]
}
```

------

下列範例政策提供擷取儀表板 URL 的許可。`quicksight:RegisterUser` 如果您要建立初次成為 Amazon Quick Sight 讀者的使用者，您可以將政策與 搭配使用。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Action": "quicksight:RegisterUser",
      "Resource": "*",
      "Effect": "Allow"
    },
    {
      "Action": "quicksight:GetDashboardEmbedUrl",
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}
```

------

如果您使用 `QUICKSIGHT` 作為您的 `identityType`，並提供使用者的 Amazon Resource Name (ARN)，您還需要在政策中允許 `quicksight:GetAuthCode` 動作。下列範例政策提供此許可。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "quicksight:GetDashboardEmbedUrl",
        "quicksight:GetAuthCode"
      ],
      "Resource": "*"
    }
  ]
}
```

------

您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可以代表使用者擔任該角色，並在 Amazon Quick Sight 中佈建使用者。以下範例顯示稱為 `embedding_quicksight_dashboard_role` 的角色，其前面有範例政策做為資源。

如需 OpenID Connect 或 SAML 身分驗證的信任政策詳細資訊，請參閱 *IAM 使用者指南*的下列各節：
+ [建立 Web 身分的角色或 OpenID Connect 聯合身分 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [為 SAML 2.0 聯合身分建立角色 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

# 步驟 2：獲取帶有身分驗證碼的 URL
<a name="embedded-dashboards-for-authenticated-users-get-step-2"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。

在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌的儀表板 URL。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，它會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

執行所述的步驟可確保儀表板的每個檢視器都是在 Amazon Quick Sight 中唯一佈建。它還會強制執行個別使用者設定，例如資料列層級的安全性和參數的動態預設值。

下列範例會代表使用者執行 IAM 身分驗證。此代碼在您的應用程式伺服器上運行。

------
#### [ Java ]

```
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicSessionCredentials;
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.GetDashboardEmbedUrlRequest;
import com.amazonaws.services.quicksight.model.GetDashboardEmbedUrlResult;
import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
import com.amazonaws.services.securitytoken.model.AssumeRoleRequest;
import com.amazonaws.services.securitytoken.model.AssumeRoleResult;

/**
 * Class to call QuickSight AWS SDK to get url for dashboard embedding.
 */
public class GetQuicksightEmbedUrlIAMAuth {

    private static String IAM = "IAM";

    private final AmazonQuickSight quickSightClient;

    private final AWSSecurityTokenService awsSecurityTokenService;

    public GetQuicksightEmbedUrlIAMAuth(final AWSSecurityTokenService awsSecurityTokenService) {
        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();
        this.awsSecurityTokenService = awsSecurityTokenService;
    }

    public String getQuicksightEmbedUrl(
            final String accountId, // YOUR AWS ACCOUNT ID
            final String dashboardId, // YOUR DASHBOARD ID TO EMBED
            final String openIdToken, // TOKEN TO ASSUME ROLE WITH ROLEARN
            final String roleArn, // IAM USER ROLE TO USE FOR EMBEDDING
            final String sessionName, // SESSION NAME FOR THE ROLEARN ASSUME ROLE
            final boolean resetDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
            final boolean undoRedoDisabled // OPTIONAL PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
    ) throws Exception {
        AssumeRoleRequest request = new AssumeRoleRequest()
                .withRoleArn(roleArn)
                .withRoleSessionName(sessionName)
                .withTokenCode(openIdToken)
                .withDurationSeconds(3600);
        AssumeRoleResult assumeRoleResult = awsSecurityTokenService.assumeRole(request);

        AWSCredentials temporaryCredentials = new BasicSessionCredentials(
                assumeRoleResult.getCredentials().getAccessKeyId(),
                assumeRoleResult.getCredentials().getSecretAccessKey(),
                assumeRoleResult.getCredentials().getSessionToken());
        AWSStaticCredentialsProvider awsStaticCredentialsProvider = new AWSStaticCredentialsProvider(temporaryCredentials);

        GetDashboardEmbedUrlRequest getDashboardEmbedUrlRequest = new GetDashboardEmbedUrlRequest()
                .withDashboardId(dashboardId)
                .withAwsAccountId(accountId)
                .withIdentityType(IAM)
                .withResetDisabled(resetDisabled)
                .withUndoRedoDisabled(undoRedoDisabled)
                .withRequestCredentialsProvider(awsStaticCredentialsProvider);

        GetDashboardEmbedUrlResult dashboardEmbedUrl = quickSightClient.getDashboardEmbedUrl(getDashboardEmbedUrlRequest);

        return dashboardEmbedUrl.getEmbedUrl();
    }
}
```

------
#### [ JavaScript ]

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

function getDashboardEmbedURL(
    accountId, // YOUR AWS ACCOUNT ID
    dashboardId, // YOUR DASHBOARD ID TO EMBED
    openIdToken, // TOKEN TO ASSUME ROLE WITH ROLEARN
    roleArn, // IAM USER ROLE TO USE FOR EMBEDDING
    sessionName, // SESSION NAME FOR THE ROLEARN ASSUME ROLE
    resetDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
    undoRedoDisabled, // OPTIONAL PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
    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 getDashboardParams = {
                AwsAccountId: accountId,
                DashboardId: dashboardId,
                IdentityType: 'IAM',
                ResetDisabled: resetDisabled,
                SessionLifetimeInMinutes: 600,
                UndoRedoDisabled: undoRedoDisabled
            };

            const quicksightGetDashboard = 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
                }
            });

            quicksightGetDashboard.getDashboardEmbedUrl(getDashboardParams, 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);
                }
            });
        }
    });
}
```

------
#### [ Python3 ]

```
import json
import boto3
from botocore.exceptions import ClientError

# Create QuickSight and STS clients
qs = boto3.client('quicksight',region_name='us-east-1')
sts = boto3.client('sts')

# Function to generate embedded URL  
# accountId: YOUR AWS ACCOUNT ID
# dashboardId: YOUR DASHBOARD ID TO EMBED
# openIdToken: TOKEN TO ASSUME ROLE WITH ROLEARN
# roleArn: IAM USER ROLE TO USE FOR EMBEDDING
# sessionName: SESSION NAME FOR THE ROLEARN ASSUME ROLE
# resetDisabled: PARAMETER TO ENABLE DISABLE RESET BUTTON IN EMBEDDED DASHBAORD
# undoRedoDisabled: PARAMETER TO ENABLE DISABLE UNDO REDO BUTTONS IN EMBEDDED DASHBAORD
def getDashboardURL(accountId, dashboardId, openIdToken, roleArn, sessionName, resetDisabled, undoRedoDisabled):
    try:
        assumedRole = sts.assume_role(
            RoleArn = roleArn,
            RoleSessionName = sessionName,
            WebIdentityToken = openIdToken
        )
    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:
            quickSight = assumedRoleSession.client('quicksight',region_name='us-east-1')
            
            response = quickSight.get_dashboard_embed_url(
                 AwsAccountId = accountId,
                 DashboardId = dashboardId,
                 IdentityType = 'IAM',
                 SessionLifetimeInMinutes = 600,
                 UndoRedoDisabled = undoRedoDisabled,
                 ResetDisabled = resetDisabled
            )
            
            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 embeddedURL: " + str(e)
```

------
#### [ Node.js ]

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來取得嵌入儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
const AWS = require('aws-sdk');
            const https = require('https');
            
            var quicksight = new AWS.Service({
                apiConfig: require('./quicksight-2018-04-01.min.json'),
                region: 'us-east-1',
            });
            
            quicksight.getDashboardEmbedUrl({
                'AwsAccountId': '111122223333',
                'DashboardId': '1c1fe111-e2d2-3b30-44ef-a0e111111cde',
                'IdentityType': 'IAM',
                'ResetDisabled': true,
                'SessionLifetimeInMinutes': 100,
                'UndoRedoDisabled': false,
                'StatePersistenceEnabled': true
            
            }, function(err, data) {
                console.log('Errors: ');
                console.log(err);
                console.log('Response: ');
                console.log(data);
            });
```

**Example**  

```
//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://dashboards.example.com/embed/620bef10822743fab329fb3751187d2d…
              RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' }
```

------
#### [ .NET/C\$1 ]

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來取得嵌入儀表板的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示儀表板。

**Example**  

```
            var client = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                sessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                Console.WriteLine(
                    client.GetDashboardEmbedUrlAsync(new GetDashboardEmbedUrlRequest
                    {
                        AwsAccountId = “111122223333”,
                        DashboardId = "1c1fe111-e2d2-3b30-44ef-a0e111111cde",
                        IdentityType = EmbeddingIdentityType.IAM,
                        ResetDisabled = true,
                        SessionLifetimeInMinutes = 100,
                        UndoRedoDisabled = false,
                        StatePersistenceEnabled = true
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
```

------
#### [ AWS CLI ]

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用 SAML 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GetDashboardEmbedURL` 的許可。如果您正在採取即時方法在使用者第一次開啟儀表板時新增使用者，則該角色也需要啓用 `quicksight:RegisterUser` 的許可。

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

`assume-role` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。如果您使用 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_dashboard_role/john.doe@example.com`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個使用者設定適當的許可。還能避免對使用者存取進行任何調節。*調節*是一項安全功能，可防止相同的使用者從多個位置存取 Amazon Quick Sight。

角色工作階段 ID 也會成為 Amazon Quick Sight 中的使用者名稱。您可以使用此模式提前在 Amazon Quick Sight 中佈建使用者，或在使用者第一次存取儀表板時佈建他們。

以下範例顯示可用來佈建使用者的 CLI 命令。如需 [RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html) 和其他 Amazon Quick Sight API 操作的詳細資訊，請參閱 [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_dashboard_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` 設定他們。相反地，他們應在第一次存取 Amazon Quick Sight 時自動訂閱。若是 Microsoft AD 使用者，您可以使用 `DescribeUser` 取得使用者的 ARN。

使用者第一次存取 Amazon Quick Sight 時，您也可以將此使用者新增至與儀表板共用的群組。以下範例顯示用於將使用者新增至群組的 CLI 命令。

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

您現在擁有應用程式的使用者，他們也是 Amazon Quick Sight 的使用者，以及有權存取儀表板的使用者。

最後，為了取得儀表板的簽章 URL，請從應用程式伺服器呼叫 `get-dashboard-embed-url`。這會傳回可嵌入的儀表板 URL。下列範例顯示如何使用透過 AWS Managed Microsoft AD 或 IAM Identity Center 驗證的使用者的伺服器端呼叫來取得內嵌儀表板的 URL。

```
aws quicksight get-dashboard-embed-url \
     --aws-account-id 111122223333 \
     --dashboard-id 1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89 \
     --identity-type IAM \
     --session-lifetime-in-minutes 30 \
     --undo-redo-disabled true \
     --reset-disabled true \
     --state-persistence-enabled true \
     --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_dashboard_role/embeddingsession
```

如需有關使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetDashboardEmbedUrl.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetDashboardEmbedUrl.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

------

# 步驟 3：內嵌儀表板 URL
<a name="embedded-dashboards-for-authenticated-users-get-step-3"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。

在下一節中，您可以了解如何使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript)，在網站或應用程式頁面的步驟 3 中內嵌儀表板 URL。您可以使用此 SDK 執行以下操作：
+ 將儀表板放在 HTML 頁面。
+ 將參數傳遞到儀表板。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

呼叫 `GetDashboardEmbedUrl` API 操作以獲得可內嵌應用程式的 URL。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期為 10 小時。此 API 操作提供的 URL 附有可啟用單一登入工作階段的 `auth_code`。

以下是 `get-dashboard-embed-url` 的回應範例。

```
//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: //dashboards.example.com/embed/620bef10822743fab329fb3751187d2d...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 或將此 URL 新增至 iframe，將此儀表板內嵌在您的網頁中。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制儀表板中的參數，並根據頁面載入完成和錯誤接收回呼。

下列範例示範如何使用產生的 URL。此代碼在您的應用程式伺服器上生成。

```
<!DOCTYPE html>
<html>

<head>
    <title>Basic Embed</title>

    <script src="./quicksight-embedding-js-sdk.min.js"></script>
    <script type="text/javascript">
        var dashboard;

        function embedDashboard() {
            var containerDiv = document.getElementById("embeddingContainer");
            var options = {
                // replace this dummy url with the one generated via embedding API
                url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",  
                container: containerDiv,
                scrolling: "no",
                height: "700px",
                width: "1000px",
                footerPaddingEnabled: true
            };
            dashboard = QuickSightEmbedding.embedDashboard(options);
        }
    </script>
</head>

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

</html>
```

若要讓此範例運作，請務必使用 Amazon Quick Sight 內嵌 SDK，使用 JavaScript 在您的網站上載入內嵌儀表板。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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

# 使用 嵌入 Amazon Quick Sight 主控台 GetSessionEmbedUrl（舊 API)
<a name="embedded-analytics-full-console-for-authenticated-users-get"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。


|  | 
| --- |
|  適用於：企業版  | 


|  | 
| --- |
|    目標對象：Amazon Quick 開發人員  | 

在下列各節中，您可以找到如何使用 `GetSessionEmbedUrl` API 在自訂品牌撰寫入口網站中為已註冊使用者提供 Amazon Quick Sight 主控台體驗的詳細資訊。

**Topics**
+ [

# 步驟 1：設定許可
](embedded-analytics-full-console-for-authenticated-users-get-step-1.md)
+ [

# 步驟 2：獲取帶有身分驗證碼的 URL
](embedded-analytics-full-console-for-authenticated-users-get-step-2.md)
+ [

# 步驟 3：嵌入主控台工作階段 URL
](embedded-analytics-full-console-for-authenticated-users-get-step-3.md)

# 步驟 1：設定許可
<a name="embedded-analytics-full-console-for-authenticated-users-get-step-1"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。

在以下章節中，您可以了解如何為後端應用程式或 Web 伺服器設定許可。這個任務需要有 IAM 的管理存取權。

每個存取 Amazon Quick Sight 的使用者都會擔任一個角色，為他們提供主控台工作階段的 Amazon Quick Sight 存取權和許可。若要實現這一點，請在 AWS 您的帳戶中建立 IAM 角色。將 IAM 政策與此角色建立關聯，以提供許可給擔任此角色的任何使用者。新增`quicksight:RegisterUser`許可，以確保讀者可以唯讀方式存取 Amazon Quick Sight，而且無法存取任何其他資料或建立功能。IAM 角色也需要提供可擷取主控台工作階段 URL 的許可。對於這一點，您新增 `quicksight:GetSessionEmbedUrl`。

下列範例政策提供搭配 `IdentityType=IAM` 使用的許可。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Action": "quicksight:RegisterUser",
      "Resource": "*",
      "Effect": "Allow"
    },
    {
      "Action": "quicksight:GetSessionEmbedUrl",
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}
```

------

下列範例政策提供擷取主控台工作階段 URL 的許可。如果您要在使用者存取內嵌工作階段之前建立使用者，則可以不帶 `quicksight:RegisterUser` 使用政策。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "quicksight:GetSessionEmbedUrl"
            ],
            "Resource": "*"
        }
    ]
}
```

------

如果您使用 `QUICKSIGHT` 作為您的 `identityType`，並提供使用者的 Amazon Resource Name (ARN)，您還需要在政策中允許 `quicksight:GetAuthCode` 動作。下列範例政策提供此許可。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "quicksight:GetSessionEmbedUrl",
        "quicksight:GetAuthCode"
      ],
      "Resource": "*"
    }
  ]
}
```

------

您的應用程式的 IAM 身分必須有相關聯的信任政策，以允許存取至您剛建立的角色。這表示當使用者存取您的應用程式時，您的應用程式可以代表使用者擔任該角色，並在 Amazon Quick Sight 中佈建使用者。以下範例顯示稱為 `embedding_quicksight_console_session_role` 的角色，其前面有範例政策做為資源。

如需 OpenID Connect 或 SAML 身分驗證的信任政策詳細資訊，請參閱 *IAM 使用者指南*的下列各節：
+ [建立 Web 身分的角色或 OpenID Connect 聯合身分 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [為 SAML 2.0 聯合身分建立角色 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

# 步驟 2：獲取帶有身分驗證碼的 URL
<a name="embedded-analytics-full-console-for-authenticated-users-get-step-2"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。

在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌主控台工作階段的 URL。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，它會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

執行所述的步驟可確保在 Amazon Quick Sight 中唯一佈建主控台工作階段的每個檢視器。它還會強制執行個別使用者設定，例如資料列層級的安全性和參數的動態預設值。

下列範例會代表使用者執行 IAM 身分驗證。此代碼在您的應用程式伺服器上運行。

------
#### [ Java ]

```
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.GetSessionEmbedUrlRequest;
import com.amazonaws.services.quicksight.model.GetSessionEmbedUrlResult;

/**
 * Class to call QuickSight AWS SDK to get url for session embedding.
 */
public class GetSessionEmbedUrlQSAuth {

    private final AmazonQuickSight quickSightClient;

    public GetSessionEmbedUrlQSAuth() {
        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, // YOUR AWS ACCOUNT ID
            final String userArn // REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
    ) throws Exception {
        GetSessionEmbedUrlRequest getSessionEmbedUrlRequest = new GetSessionEmbedUrlRequest()
                .withAwsAccountId(accountId)
                .withEntryPoint("/start")
                .withUserArn(userArn);

        GetSessionEmbedUrlResult sessionEmbedUrl = quickSightClient.getSessionEmbedUrl(getSessionEmbedUrlRequest);

        return sessionEmbedUrl.getEmbedUrl();
    }
}
```

------
#### [ JavaScript ]

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

function getSessionEmbedURL(
    accountId, // YOUR AWS ACCOUNT ID
    userArn, // REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
    getEmbedUrlCallback, // GETEMBEDURL SUCCESS CALLBACK METHOD
    errorCallback // GETEMBEDURL ERROR CALLBACK METHOD
    ) {
    const getSessionParams = {
        AwsAccountId: accountId,
        EntryPoint: "/start",
        UserArn: userArn,
        SessionLifetimeInMinutes: 600,
    };

    const quicksightGetSession = new AWS.QuickSight({
        region: process.env.AWS_REGION,
    });

    quicksightGetSession.getSessionEmbedUrl(getSessionParams, 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);
        }
    });
}
```

------
#### [ Python3 ]

```
import json
import boto3
from botocore.exceptions import ClientError
import time

# Create QuickSight and STS clients
qs = boto3.client('quicksight',region_name='us-east-1')
sts = boto3.client('sts')

# Function to generate embedded URL
# accountId: YOUR AWS ACCOUNT ID
# userArn: REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
def getSessionEmbedURL(accountId, userArn):
    try:
        response = qs.get_session_embed_url(
            AwsAccountId = accountId,
            EntryPoint = "/start",
            UserArn = userArn,
            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 ]

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來獲得內嵌主控台工作階段的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示主控台工作階段。

**Example**  

```
const AWS = require('aws-sdk');
            const https = require('https');
            
            var quicksight = new AWS.Service({
                apiConfig: require('./quicksight-2018-04-01.min.json'),
                region: 'us-east-1',
            });
            
            quicksight.GetSessionEmbedUrl({
                'AwsAccountId': '111122223333',
                'EntryPoint': 'https://url-for-console-page-to-open',
                'SessionLifetimeInMinutes': 600,
                'UserArn': 'USER_ARN'
            
            }, function(err, data) {
                console.log('Errors: ');
                console.log(err);
                console.log('Response: ');
                console.log(data);
            });
```

**Example**  

```
//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://dashboards.example.com/embed/620bef10822743fab329fb3751187d2d…
              RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' }
```

------
#### [ .NET/C\$1 ]

以下範例顯示的 .NET/C\$1 程式碼可在應用程式伺服器上用來產生內嵌主控台工作階段的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示主控台。

**Example**  

```
            var client = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                sessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                Console.WriteLine(
                    client.GetSessionEmbedUrlAsync(new GetSessionEmbedUrlRequest
                    {
                'AwsAccountId': '111122223333',
                'EntryPoint': 'https://url-for-console-page-to-open',
                'SessionLifetimeInMinutes': 600,
                'UserArn': 'USER_ARN'
                        AwsAccountId = 111122223333,
                        EntryPoint = https://url-for-console-page-to-open,
                        SessionLifetimeInMinutes = 600,
                        UserArn = 'USER_ARN'
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
```

------
#### [ AWS CLI ]

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) – 在使用 IAM 身分擔任角色的情況下使用此操作。
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) –在您使用 SAML 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 `quicksight:GetSessionEmbedUrl` 的許可。如果您在第一次開啟 Amazon Quick Sight 時採取just-in-time方法來新增使用者，該角色也需要為 啟用許可`quicksight:RegisterUser`。

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

`assume-role` 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

**注意**  
若您呼叫 `AssumeRole` 操作時收到 `ExpiredToken` 錯誤，原因可能是先前的 `SESSION TOKEN` 仍在環境變數中。設定以下變數便可清除此錯誤：  
*AWS\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

以下範例說明如何在 CLI 中設定這三個參數。如果您使用 Microsoft Windows 電腦，請使用 `set`，不要使用 `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"
```

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 `embedding_quicksight_console_session_role/john.doe@example.com`。角色工作階段 ID 由來自 `role-arn` 和 `role-session-name` 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個使用者設定適當的許可。還能避免對使用者存取進行任何調節。調節是一項安全功能，可防止相同的使用者從多個位置存取 Amazon Quick Sight。

角色工作階段 ID 也會成為 Amazon Quick Sight 中的使用者名稱。您可以使用此模式提前在 Amazon Quick Sight 中佈建使用者，或在使用者第一次存取主控台工作階段時佈建使用者。

以下範例顯示可用來佈建使用者的 CLI 命令。如需 [RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)、[DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html) 和其他 Amazon Quick Sight API 操作的詳細資訊，請參閱 [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_dashboard_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` 設定他們。相反地，他們應在第一次存取 Amazon Quick Sight 時自動訂閱。若是 Microsoft AD 使用者，您可以使用 `DescribeUser` 取得使用者的 ARN。

使用者第一次存取 Amazon Quick Sight 時，您也可以將此使用者新增至適當的群組。以下範例顯示用於將使用者新增至群組的 CLI 命令。

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

您現在擁有的應用程式使用者也是 Amazon Quick Sight 的使用者，以及可存取 Amazon Quick Sight 主控台工作階段的使用者。

最後，為了取得主控台工作階段的簽章 URL，請從應用程式伺服器呼叫 `get-session-embed-url`。這將返回可嵌入的主控台工作階段 URL。下列範例示範如何使用伺服器端呼叫，為透過 AWS Managed Microsoft AD 或單一登入 (IAM Identity Center) 驗證的使用者取得內嵌主控台工作階段的 URL。

```
aws quicksight get-dashboard-embed-url \
     --aws-account-id 111122223333 \
     --entry-point the-url-for--the-console-session \
     --session-lifetime-in-minutes 600 \
     --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_dashboard_role/embeddingsession
```

如需有關使用此操作的詳細資訊，請參閱 [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetSessionEmbedUrl.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GetSessionEmbedUrl.html)。您可以在您自己的程式碼中使用這個和其他 API 操作。

------

# 步驟 3：嵌入主控台工作階段 URL
<a name="embedded-analytics-full-console-for-authenticated-users-get-step-3"></a>

**重要**  
Amazon Quick Sight 有用於內嵌分析的新 APIs： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。  
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 [Amazon Quick Sight 分析內嵌至您的應用程式](https://docs.aws.amazon.com/quicksight/latest/user/embedding-overview.html)。

在下一節中，您可以了解如何使用 [Amazon Quick Sight 內嵌 SDK](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript)，在網站或應用程式頁面的步驟 3 中內嵌主控台工作階段 URL。您可以使用此 SDK 執行以下操作：
+ 將主控台工作階段放置在 HTML 頁面上。
+ 將參數傳遞至主控台工作階段。
+ 以針對您的應用程式而訂做的訊息來處理錯誤狀態。

呼叫 `GetSessionEmbedUrl` API 操作以獲得可內嵌應用程式的 URL。此 URL 的有效期為 5 分鐘，而產生的工作階段有效期為 10 小時。此 API 操作提供的 URL 附有可啟用單一登入工作階段的 `auth_code`。

以下是 `get-dashboard-embed-url` 的回應範例。

```
//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: //dashboards.example.com/embed/620bef10822743fab329fb3751187d2d...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

使用 Amazon Quick Sight [內嵌 SDK ](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk)或將此 URL 新增至 iframe，將此主控台工作階段內嵌在您的網頁中。如果您設定固定高度和寬度數字 （以像素為單位），Amazon Quick Sight 會使用這些值，而且不會隨著視窗調整大小而變更視覺效果。如果您設定相對百分比高度和寬度，Amazon Quick Sight 會提供隨著視窗大小變更而修改的回應式配置。透過使用 Amazon Quick Sight 內嵌 SDK，您也可以控制主控台工作階段中的參數，並根據頁面載入完成和錯誤接收回呼。

下列範例示範如何使用產生的 URL。此代碼在您的應用程式伺服器上生成。

```
<!DOCTYPE html>
<html>

<head>
    <title>Basic Embed</title>

    <script src="./quicksight-embedding-js-sdk.min.js"></script>
    <script type="text/javascript">
        var dashboard;

        function embedDashboard() {
            var containerDiv = document.getElementById("embeddingContainer");
            var options = {
                // replace this dummy url with the one generated via embedding API
                url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",  
                container: containerDiv,
                scrolling: "no",
                height: "700px",
                width: "1000px",
                footerPaddingEnabled: true
            };
            dashboard = QuickSightEmbedding.embedDashboard(options);
        }
    </script>
</head>

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

</html>
```

若要讓此範例運作，請務必使用 Amazon Quick Sight 內嵌 SDK，使用 JavaScript 在您的網站上載入內嵌主控台工作階段。為獲得您的版本，請執行以下其中一項操作：
+ 從 GitHub 下載 [Amazon Quick Sight 內嵌 SDK](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object)。此儲存庫由一組 Amazon Quick Sight 開發人員維護。
+ 從 [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) 下載最新的內嵌開發套件版本。
+ 如果您使用 JavaScript 相依性的 `npm`，請執行下列命令來下載並安裝它。

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