本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon Quick Sight 進行開發
我們提供 Amazon Quick Sight 的 API 操作，以及 AWS 的軟體開發套件 (SDKs)，可讓您從偏好的程式設計語言存取 Amazon Quick Sight。目前，您可以管理使用者和群組。在 Enterprise Edition 中，您還能將儀表板內嵌於網頁或應用程式。
若要監控對您 帳戶的 Amazon Quick Sight API 發出的呼叫，包括由 AWS 管理主控台、命令列工具和其他 服務發出的呼叫，請使用 AWS CloudTrail。如需詳細資訊，請參閱[「AWS CloudTrail 使用者指南」](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。
## 必要知識
如果您計劃透過 API 存取 Amazon Quick Sight，您應該熟悉以下內容：
+ JSON
+ Web 服務
+ HTTP 請求
+ 一種或多種程式設計語言，例如 JavaScript、Java、Python，或 C \$1。
我們建議您造訪 AWS [入門資源中心](https://aws.amazon.com/getting-started/tools-sdks/)，以瀏覽 提供的 AWS SDKs 和工具組。
儘管您可以使用終端和您喜歡的文字編輯器，但您可能會受益於整合式開發環境 (IDE) 更視覺化的 UI 體驗。我們在 *AWS 入門資源中心*的 [IDE 和 IDE 工具組](https://aws.amazon.com/getting-started/tools-sdks/#IDE_and_IDE_Toolkits)區段中提供了 IDE 清單。此網站提供 AWS 工具組，您可以針對偏好的 IDE 下載。一些 IDE 還提供教學，協助您進一步了解程式設計語言。
## Amazon Quick Sight 的可用 API 操作
AWS 為偏好使用特定語言 API 操作而非透過 HTTPS 提交請求的軟體開發人員提供程式庫、範本程式碼、教學課程和其他資源。這些程式庫提供可自動處理任務的基本功能，例如密碼編譯簽署請求、重試請求，以及處理錯誤回應。這些程式庫可協助您更輕鬆地入門。
如需下載 AWS SDKs的詳細資訊，請參閱 [AWS SDKs和工具](https://aws.amazon.com/tools/)。下列連結是可用的特定語言 API 文件的範例。
**AWS Command Line Interface**
+ [AWS CLI QuickSight 命令參考](https://docs.aws.amazon.com/cli/latest/reference/quicksight/index.html)
+ [AWS CLI 使用者指南](https://docs.aws.amazon.com/cli/latest/userguide/)
+ [AWS CLI 命令參考](https://docs.aws.amazon.com/cli/latest/reference/)
**適用於 .NET 的 AWS SDK**
+ [Amazon.Quicksight](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=QuickSight/NQuickSight.html)
+ [Amazon.Quicksight.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=QuickSight/NQuickSightModel.html)
**適用於 C\$1\$1 的 AWS SDK**
+ [Aws::QuickSight::QuickSightClient 類別參考](https://sdk.amazonaws.com/cpp/api/LATEST/class_aws_1_1_quick_sight_1_1_quick_sight_client.html)
**適用於 Go 的 AWS SDK**
+ [quicksight](https://docs.aws.amazon.com/sdk-for-go/api/service/quicksight/)
**適用於 Java 的 AWS SDK**
+ [com.amazonaws.services.quicksight](https://docs.aws.amazon.com/sdk-for-java/latest/reference/index.html?com/amazonaws/services/quicksight/package-summary.html)
+ [com.amazonaws.services.quicksight.model](https://docs.aws.amazon.com/sdk-for-java/latest/reference/index.html?com/amazonaws/services/quicksight/model/package-summary.html)
**適用於 JavaScript 的 AWS SDK**
+ [AWS.QuickSight](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/QuickSight.html)
**適用於 PHP 的 AWS SDK**
+ [QuickSightClient](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.QuickSight.QuickSightClient.html)
**適用於 Python (Boto3) 的 AWS SDK**
+ [Amazon Quick Sight](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/quicksight.html)
**適用於 Ruby 的 AWS SDK**
+ [Aws::QuickSight](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/QuickSight.html)
# 術語與概念
本節提供在 Amazon Quick Sight 中開發的術語清單。
**匿名 Amazon Quick Sight 使用者：**幾乎屬於命名空間的臨時 Amazon Quick Sight 使用者身分，且僅適用於內嵌。您可以使用以標籤為基礎的規則來為此類使用者實作列級安全性。
**發起人身分：**提出 API 請求的 AWS Identity and Access Management 使用者的身分。發起人的身分由 Amazon Quick Sight 使用連接到請求的簽章來決定。透過使用我們提供的軟體開發套件用戶端，您無須以手動方式產生簽章或將其附加至請求。不過，必要時您也可以手動執行上述操作。
**呼叫者身分：** – 除了呼叫者身分之外，但不能取代它，您可以在呼叫 Amazon Quick Sight 時，透過 IAM `AssumeRole` API 擔任呼叫者的身分。 AWS 會透過呼叫者的身分來核准呼叫者。這是為了避免必須明確新增屬於相同 Amazon Quick Sight 訂閱的多個帳戶。
**命名空間：**一個邏輯容器，讓您可以隔離使用者集區，以便於組織客戶、子公司、團隊等。如需詳細資訊，請參閱[使用隔離命名空間支援多租戶](https://docs.aws.amazon.com/quicksight/latest/user/namespaces.html)
**QuickSight ARN：**Amazon Resource Name (ARN)。Amazon Quick Sight 資源會使用其名稱或 ARN 來識別。例如，以下是名為 `MyGroup1` 的群組、名為 `User1` 的使用者及 ID 為 `1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89` 的儀表板的 ARN：
```
arn:aws:quicksight:us-east-1:111122223333:group/default/MyGroup1
arn:aws:quicksight:us-east-1:111122223333:user/default/User1
arn:aws:quicksight:us-west-2:111122223333:dashboard/1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89
```
以下範例顯示名為 `MyTemplate` 的範本和名為 `MyDashboard` 的儀表板的 ARN。
1. 範本的範例 ARN
```
arn:aws:quicksight:us-east-1:111122223333:template/MyTemplate
```
1. 範本的範例 ARN (參考範本的特定版本)
```
arn:aws:quicksight:us-east-1:111122223333:template/MyTemplate/version/10
```
1. 範本別名的範例 ARN
```
arn:aws:quicksight:us-east-1:111122223333:template/MyTemplate/alias/STAGING
```
1. 儀表板的範例 ARN
```
arn:aws:quicksight:us-east-1:111122223333:dashboard/MyDashboard
```
1. 儀表板的範例 ARN (參考儀表板的特定版本)
```
arn:aws:quicksight:us-east-1:111122223333:dashboard/MyDashboard/version/10
```
視情況而定，您可能需要提供實體的名稱、ID 或 ARN。如果您有名稱，您可以使用一些 Amazon Quick Sight API 操作來擷取 ARN。
**Amazon Quick Sight 儀表板：**識別從分析或範本建立的 Amazon Quick Sight 報告的實體。Amazon Quick Sight 儀表板是可分割的。具備適當的許可時，便可以從儀表板建立排程的電子郵件報告。`CreateDashboard` 和 `DescribeDashboard` API 操作作用於儀表板實體。
**Amazon Quick Sight 範本：** 封裝建立分析或儀表板所需中繼資料的實體。它透過用預留位置取代資料集來抽象化與分析相關的資料集。您可以使用範本建立儀表板，方法是使用與建立來源分析和範本相同結構描述的資料集取代資料集預留位置。
**Amazon Quick Sight 使用者：**– 這是 API 呼叫對 執行動作的 Amazon Quick Sight 使用者身分。此使用者與發起人身分不同，但可能是映射至 Amazon Quick Sight 內使用者的使用者。
# 使用 Amazon Quick Sight API 開發應用程式
您可以使用 AWS SDKs來存取專為您正在使用的程式設計語言或平台量身打造的 API，以管理部署的大部分層面。如需詳細資訊，請參閱 [AWS 開發套件](https://aws.amazon.com/tools/#SDKs)。
如需 API 操作的詳細資訊，請參閱 [Amazon Quick Sight API 參考](https://docs.aws.amazon.com/quicksight/index.html?id=docs_gateway)。
在您可以呼叫 Amazon Quick Sight API 操作之前，您需要連接到 IAM 身分的政策中的 `quicksight:operation-name` 許可。例如，若要呼叫 `list-users`，您必須具備 `quicksight:ListUsers` 許可。同樣的模式適用於所有操作。
如果您不確定必要的許可是什麼，可以嘗試進行呼叫。然後，用戶端會告訴您缺少的許可是什麼。您可以在許可原則的「資源」欄位中使用星號 (`*`)，而不指定明確的資源。但建議您盡可能限制每個許可。您可以使用 Amazon Quick Sight Amazon Resource Name (ARN) 識別符，在政策中指定或排除資源來限制使用者存取。
如需詳細資訊，請參閱下列內容：
+ [Amazon Quick Sight 的 IAM 政策範例](https://docs.aws.amazon.com/quicksight/latest/user/iam-policy-examples.html)
+ [動作、資源及條件索引鍵](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonquicksight.html)
+ [IAM JSON 政策元素](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html)
若要擷取使用者或群組的 ARN，請對相關資源使用 `Describe` 操作。您也可以在 IAM 中新增條件，進一步限制某些情況下的 API 存取。例如，將 `User1`新增至 時`Group1`，主要資源是 `Group1`，因此您可以允許或拒絕存取特定群組，但您也可以使用 IAM Amazon Quick Sight 金鑰來新增條件`quicksight:UserName`，以允許或防止特定使用者新增至該群組。
以下是政策的範例。這表示只要新增至群組的使用者名稱不是 `user1`，連接此政策的呼叫者就能在任何群組上呼叫 `CreateGroupMembership` 操作。
```
{
"Effect": "Allow",
"Action": "quicksight:CreateGroupMembership",
"Resource": "arn:aws:quicksight:us-east-1:aws-account-id:group/default/*",
"Condition": {
"StringNotEquals": {
"quicksight:UserName": "user1"
}
}
}
```
------
#### [ AWS CLI ]
下列程序說明如何透過 CLI 與 Amazon Quick Sight API AWS 操作互動。此說明內容已在 Bash 中進行過測試，但在其他命令列環境下應可得到同樣或類似的結果。
1. 在您的環境中安裝 AWS SDK。如需如何執行此操作的說明，請參閱 [AWS Command Line Interface](https://aws.amazon.com/cli/)。
1. 使用下列命令和後續指示來設定您的 AWS CLI 身分和區域。請使用具備適當許可的 IAM 身分或角色的登入資料。
```
aws configure
```
1. 發出下列命令，查看 Amazon Quick Sight SDK 說明：
```
aws quicksight help
```
1. 若要取得如何使用特定 API 的詳細說明，請輸入其名稱，後面加上 help，例如：
```
aws quicksight list-users help
```
1. 現在您可以呼叫 Amazon Quick Sight API 操作。此範例會傳回您帳戶中的 Amazon Quick Sight 使用者清單。
```
aws quicksight list-users --aws-account-id aws-account-id --namespace default --region us-east-1
```
------
#### [ Java SDK ]
使用下列程序來設定與 Amazon Quick Sight 互動的 Java 應用程式。
1. 若要開始使用，請在 IDE 中建立 Java 專案。
1. 將 Amazon Quick Sight SDK 匯入您的新專案，例如： `AWSQuickSightJavaClient-1.11.x.jar`
1. 一旦您的 IDE 為 Amazon Quick Sight SDK 編製索引，您應該能夠新增匯入列，如下所示：
```
import com.amazonaws.services.quicksight.AmazonQuickSight;
```
如果 IDE 未將其判別為有效語法，請確認您是否已匯入軟體開發套件。
1. 如同其他 AWS SDKs，Amazon Quick Sight SDK 需要外部相依性才能執行其許多函數。您必須下載依存項目並將之匯入同一專案。必要的依存項目如下：
+ `aws-java-sdk-1.11.402.jar` (AWS Java 開發套件和登入資料設定） — 請參閱[設定適用於 Java 的 AWS 開發套件 ](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-install.html)
+ `commons-logging-1.2.jar` – 請參閱 [ https://commons.apache.org/proper/commons-logging/download\$1logging.cgi ](https://commons.apache.org/proper/commons-logging/download_logging.cgi)
+ `jackson-annotations-2.9.6.jar`、`jackson-core-2.9.6.jar` 及 `jackson-databind-2.9.6.jar` – 請參閱 [ http://repo1.maven.org/maven2/com/fasterxml/jackson/core/ ](https://repo1.maven.org/maven2/com/fasterxml/jackson/core/)
+ `httpclient-4.5.6.jar`、`httpcore-4.4.10.jar` – 請參閱 [ https://hc.apache.org/downloads.cgi ](https://hc.apache.org/downloads.cgi)
+ `joda-time-2.1.jar` – 請參閱 [ https://mvnrepository.com/artifact/joda-time/joda-time/2.1 ](https://mvnrepository.com/artifact/joda-time/joda-time/2.1)
1. 現在，您已準備好建立 Amazon Quick Sight 用戶端。您可以使用能夠由用戶端與之通訊的預設公有端點，或是明確參考該端點。有多種方式可以提供您的 AWS 登入資料。以下範例介紹既直接又簡單的方法。底下的用戶端方法用於進行所有 API 呼叫：
```
private static AmazonQuickSight getClient() {
final AWSCredentialsProvider credsProvider = 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() {}
};
return AmazonQuickSightClientBuilder
.standard()
.withRegion(Regions.US_EAST_1.getName())
.withCredentials(credsProvider)
.build();
}
```
1. 現在，我們可以使用上述用戶端列出 Amazon Quick Sight 帳戶中的所有使用者。
**注意**
您必須提供用來訂閱 Amazon Quick Sight AWS 的帳戶 ID。這必須符合發起人身分 AWS 的帳戶 ID。目前不支援跨帳戶呼叫。此外，必要參數 `namespace` 應一律設為 *default*。
```
getClient().listUsers(new ListUsersRequest()
.withAwsAccountId("relevant_AWS_account_ID")
.withNamespace("default"))
.getUserList().forEach(user -> {
System.out.println(user.getArn());
});
```
1. 若要查看所有可能的 API 操作及其使用的請求物件清單，您可以在 IDE 中的用戶端物件上**按一下 CTRL**，以檢視 Amazon Quick Sight 介面。或者，在 Amazon Quick Sight JavaClient JAR 檔案中的 `com.amazonaws.services.quicksight`套件中找到它。
------
#### [ JavaScript (Node.js) SDK ]
使用下列程序來使用 Node.js 與 Amazon Quick Sight 互動。
1. 使用以下命令設定您的節點環境：
+ `npm install aws-sdk`
+ `npm install aws4 `
+ `npm install request`
+ `npm install url`
1. 如需有關使用 AWS SDK 設定 Node.js 和設定登入資料的資訊，請參閱--> [適用於 JavaScript 的 AWS SDK SDK v2 的開發人員指南](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html)。
1. 使用以下程式碼範例測試您的設定。HTTPS 為必要項目。此範例會顯示 Amazon Quick Sight 操作的完整清單及其 URL 請求參數，後面接著您帳戶中的 Amazon Quick Sight 使用者清單。
```
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',
});
console.log(quicksight.config.apiConfig.operations);
quicksight.listUsers({
// Enter your actual AWS account ID
'AwsAccountId': 'relevant_AWS_account_ID',
'Namespace': 'default',
}, function(err, data) {
console.log('---');
console.log('Errors: ');
console.log(err);
console.log('---');
console.log('Response: ');
console.log(data);
});
```
------
#### [ Python3 SDK ]
使用下列程序建立自訂建置`botocore`套件，以與 Amazon Quick Sight 互動。
1. 在 AWS 目錄中為您的環境建立登入資料檔案。在 Linux/Mac 環境中，該檔案名為 \$1/.aws/credentials，其內容如下：
```
[default]
aws_access_key_id = Your_IAM_access_key
aws_secret_access_key = Your_IAM_secret_key
```
1. 解壓縮 `botocore-1.12.10` 資料夾。將目錄切換到 `botocore-1.12.10`，然後進入 Python3 解譯器環境。
1. 回應將以字典物件的形式傳回。每次回應都會有 `ResponseMetadata` 項目，其中包含請求 ID 和回應狀態。其餘項目則視您所執行的操作類型而定。
1. 以下所示的範例應用程式將首先建立、刪除和列出群組，接著列出 Quicksight 帳戶中的使用者：
```
import botocore.session
default_namespace = 'default'
account_id = 'relevant_AWS_Account'
session = botocore.session.get_session()
client = session.create_client("quicksight", region_name='us-east-1')
print('Creating three groups: ')
client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup1')
client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup2')
client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup3')
print('Retrieving the groups and listing them: ')
response = client.list_groups(AwsAccountId = account_id, Namespace=default_namespace)
for group in response['GroupList']:
print(group)
print('Deleting our groups: ')
client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup1')
client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup2')
client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup3')
response = client.list_users(AwsAccountId = account_id, Namespace=default_namespace)
for user in response['UserList']:
print(user)
```
------
#### [ .NET/C\$1 SDK ]
使用下列程序來使用 C\$1 與 Amazon Quick Sight 互動。NET。此範例是由 Microsoft Visual Studio for Mac 所建構；視您的 IDE 及平台而定，說明內容可能略有不同。不過，程序應大致雷同。
1. 將 `nuget.zip` 檔案解壓縮到名為 `nuget` 的資料夾。
1. 在 Visual Studio 中建立新的**主控台應用程式**。
1. 在方案底下找出應用程式**相依性**，然後開啟內容功能表 (按滑鼠右鍵) 並選擇 **Add Packages (新增封裝)**。
1. 在來源清單中，選擇 **Configure Sources (設定來源)**。
1. 選擇 **Add (新增)**。然後將該來源命名為 `QuickSightSDK`。瀏覽至 `nuget` 資料夾並選擇 **Add Source (新增來源)**。
1. 選擇**確定**。然後，`QuickSightSDK`選取所有三個 Amazon Quick Sight 套件：
+ `AWSSDK.QuickSight`
+ `AWSSDK.Extensions.NETCore.Setup`
+ `AWSSDK.Extensions.CognitoAuthentication`
1. 按一下 **Add Package (新增封裝)**。
1. 複製以下範例應用程式並將其貼入您的主控台應用程式編輯器。
```
using System;
using Amazon.QuickSight.Model;
using Amazon.QuickSight;
namespace DotNetQuickSightSDKTest
{
class Program
{
private static readonly string AccessKey = "insert_your_access_key";
private static readonly string SecretAccessKey = "insert_your_secret_key";
private static readonly string AccountID = "AWS_account_ID";
private static readonly string Namespace = "default"; // leave this as default
static void Main(string[] args)
{
var client = new AmazonQuickSightClient(
AccessKey,
SecretAccessKey,
Amazon.RegionEndpoint.USEast1);
var listUsersRequest = new ListUsersRequest
{
AwsAccountId = AccountID,
Namespace = Namespace
};
client.ListUsersAsync(listUsersRequest).Result.UserList.ForEach(
user => Console.WriteLine(user.Arn)
);
var listGroupsRequest = new ListGroupsRequest
{
AwsAccountId = AccountID,
Namespace = Namespace
};
client.ListGroupsAsync(listGroupsRequest).Result.GroupList.ForEach(
group => Console.WriteLine(group.Arn)
);
}
}
}
```
------
# Amazon Quick Sight 事件整合
使用 Amazon EventBridge，您可以自動回應 Amazon Quick Sight 中的事件，例如建立新的儀表板或更新。這些事件會以接近即時的方式遞送到 EventBridge。作為開發人員，您可寫入簡單的規則，來指示感興趣的事件，以及當事件符合規則時採取的動作。透過使用事件，您可以完成使用案例，例如持續備份與部署。
**Topics**
+ [支援的事件](#events-supported)
+ [範例事件承載](#sample-events-payload)
+ [建立將 Amazon Quick Sight 事件傳送至 Amazon CloudWatch 的規則](events-send-cloudwatch.md)
+ [建立規則以將 Amazon Quick Sight 事件傳送至 AWS Lambda](events-send-lambda.md)
## 支援的事件
Amazon Quick Sight 目前支援下列事件。
| 資產類型設定 | Action | 事件詳細資訊類型 | 事件詳細資訊 |
| --- | --- | --- | --- |
| 儀表板 | 建立 | Amazon Quick Sight 儀表板建立成功 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1
} |
| 儀表板 | 建立 | Amazon Quick Sight 儀表板建立失敗 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1,
"errors": [
{
"Type": "PARAMETER_NOT_FOUND",
"Message": "Missing property abc"
},
{
"Type": "DATA_SET_NOT_FOUND",
"Message": "Cannot find dataset with id abc"
}
]
} |
| 儀表板 | 建立 | Amazon Quick Sight 儀表板許可已更新 | {"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83" } |
| 儀表板 | 更新 | Amazon Quick Sight 儀表板更新成功 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1
} |
| 儀表板 | 更新 | Amazon Quick Sight 儀表板更新失敗 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1,
"errors": [
{
"Type": "PARAMETER_NOT_FOUND",
"Message": "Missing property abc"
},
{
"Type": "DATA_SET_NOT_FOUND",
"Message": "Cannot find dataset with id abc"
}
]
} |
| 儀表板 | 更新 | Amazon Quick Sight 儀表板許可已更新 | {"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83"} |
| 儀表板 | 發布 | Amazon Quick Sight 儀表板發佈版本已更新 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 2
} |
| 儀表板 | 刪除 | 已刪除 Amazon Quick Sight 儀表板 | {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83"
} |
| 分析 | 建立 | Amazon Quick Sight 分析建立成功 | {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5"
} |
| 分析 | 建立 | Amazon Quick Sight Analysis Creation 失敗 | {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5",
"errors": [
{
"Type": "PARAMETER_NOT_FOUND",
"Message": "Missing property abc"
},
{
"Type": "DATA_SET_NOT_FOUND",
"Message": "Cannot find dataset with id abc"
}
]
} |
| 分析 | 建立 | Amazon Quick Sight 分析許可已更新 | {"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5" } |
| 分析 | 刪除 | 已刪除 Amazon Quick Sight 分析 | {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5"
} |
| 分析 | 更新 | Amazon Quick Sight 分析更新成功 | {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5"
} |
| 分析 | 更新 | Amazon Quick Sight 分析更新失敗 | {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5",
"errors": [
{
"Type": "PARAMETER_NOT_FOUND",
"Message": "Missing property abc"
},
{
"Type": "DATA_SET_NOT_FOUND",
"Message": "Cannot find dataset with id abc"
}
]
} |
| 分析 | 更新 | Amazon Quick Sight 分析許可已更新 | {"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5" } |
| VPC 連線 | 建立 | Amazon Quick Sight VPC 連線建立成功 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "CREATION_SUCCESSFUL"
} |
| VPC 連線 | 建立 | Amazon Quick Sight VPC 連線建立失敗 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "CREATION_FAILED"
} |
| VPC 連線 | 更新 | Amazon Quick Sight VPC 連線更新成功 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "UPDATE_SUCCESSFUL"
} |
| VPC 連線 | 更新 | Amazon Quick Sight VPC 連線更新失敗 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "UPDATE_FAILED"
} |
| VPC 連線 | 刪除 | Amazon Quick Sight VPC 連線刪除成功 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "DELETED"
} |
| VPC 連線 | 刪除 | Amazon Quick Sight VPC 連線刪除失敗 | {
"vpcConnectionId": "53d34238-57e7-488d-b99a-a0037d275a4e",
"availabilityStatus": "DELETION_FAILED"
} |
| 資料夾 | 建立 | 已建立 Amazon Quick Sight 資料夾 | {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be",
"parentFolderArn": "arn:aws:quicksight:us-east-1:123456789012:folder/098765432134"
} |
| 資料夾 | 建立 | Amazon Quick Sight 資料夾許可已更新 | {"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be" } |
| 資料夾 | 更新 | Amazon Quick Sight 資料夾已更新 | {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be"
} |
| 資料夾 | 更新 | Amazon Quick Sight 資料夾許可已更新 | {"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be" } |
| 資料夾 | 刪除 | 已刪除 Amazon Quick Sight 資料夾 | {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be"
} |
| 資料夾 | 成員資格更新 | Amazon Quick Sight 資料夾成員資格已更新 | {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be",
"membersAdded": ["arn:aws:quicksight:us-east-1:123456789012:analysis/e5f37119-e24c-4874-901a-af9032b729b5"],
"membersRemoved": []
} |
| 資料集 | 建立 | 已建立 Amazon Quick Sight 資料集 | {
"datasetId": "a6553a81-f97e-4ffa-a860-baea63196efa"
} |
| 資料集 | 建立 | Amazon Quick Sight 資料集許可已更新 | {"datasetId": "a6553a81-f97e-4ffa-a860-baea63196efa" } |
| 資料集 | 更新 | Amazon Quick Sight 資料集已更新 | {
"datasetId": "a6553a81-f97e-4ffa-a860-baea63196efa"
} |
| 資料集 | 更新 | Amazon Quick Sight 資料集許可已更新 | {"datasetId": "a6553a81-f97e-4ffa-a860-baea63196efa" } |
| 資料集 | 刪除 | 已刪除 Amazon Quick Sight 資料集 | {
"datasetId": "a6553a81-f97e-4ffa-a860-baea63196efa"
} |
| 資料來源 | 建立 | Amazon Quick Sight DataSource 建立成功 | {
"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824"
} |
| 資料來源 | 建立 | Amazon Quick Sight DataSource 建立失敗 | {
"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824",
"error": {
"message": "AMAZON_ELASTICSEARCH engine version 7.4 is lower than minimum supported version 7.7",
"type": "ENGINE_VERSION_NOT_SUPPORTED"
}
} |
| 資料來源 | 建立 | Amazon Quick Sight DataSource 許可已更新 | {"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824" } |
| 資料來源 | 更新 | Amazon Quick Sight DataSource 更新成功 | {
"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824"
} |
| 資料來源 | 更新 | Amazon Quick Sight DataSource 更新失敗 | {
"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824",
"error": {
"message": "AMAZON_ELASTICSEARCH engine version 7.4 is lower than minimum supported version 7.7",
"type": "ENGINE_VERSION_NOT_SUPPORTED"
}
} |
| 資料來源 | 更新 | Amazon Quick Sight DataSource 許可已更新 | {"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824" } |
| 資料來源 | 刪除 | 已刪除 Amazon Quick Sight DataSource | {
"datasourceId": "230caa6e-dc87-406b-91fb-037f29c32824"
} |
| 佈景主題 | 建立 | Amazon Quick Sight 主題建立成功 | {
""themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1"
} |
| 佈景主題 | 建立 | Amazon Quick Sight 佈景主題建立失敗 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1
} |
| 佈景主題 | 建立 | Amazon Quick Sight 佈景主題許可已更新 | {"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83" } |
| 佈景主題 | 更新 | Amazon Quick Sight 主題更新成功 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 2
} |
| 佈景主題 | 更新 | Amazon Quick Sight 主題更新失敗 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 2
} |
| 佈景主題 | 更新 | Amazon Quick Sight 佈景主題許可已更新 | {"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83" } |
| 佈景主題 | 刪除 | 已刪除 Amazon Quick Sight 主題 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83"
} |
| 佈景主題 | 別名建立 | Amazon Quick Sight 主題別名已建立 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"aliasName": "MyThemeAlias"
"versionNumber": 2
} |
| 佈景主題 | 別名更新 | Amazon Quick Sight 別名已更新 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"aliasName": "MyThemeAlias"
"versionNumber": 4
} |
| 佈景主題 | 別名刪除 | 已刪除 Amazon Quick Sight 佈景主題別名 | {
"themeId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"aliasName": "MyThemeAlias"
"versionNumber": 2
} |
## 範例事件承載
所有事件皆遵循標準 EventBridge [物件結構](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html)。詳細資訊欄位為包含更多事件相關資訊的 JSON 物件。
```
{
"version": "0",
"id": "3acb26c8-397c-4c89-a80a-ce672a864c55",
"detail-type": "QuickSight Dashboard Creation Successful",
"source": "aws.quicksight",
"account": "123456789012",
"time": "2023-10-30T22:06:31Z",
"region": "us-east-1",
"resources": ["arn:aws:quicksight:us-east-1:123456789012:dashboard/6fdbc328-ebbd-457f-aa02-9780173afc83"],
"detail": {
"dashboardId": "6fdbc328-ebbd-457f-aa02-9780173afc83",
"versionNumber": 1
}
}
```
# 建立將 Amazon Quick Sight 事件傳送至 Amazon CloudWatch 的規則
您可以撰寫簡單的規則來指出您對哪些 Amazon Quick Sight 事件感興趣，以及在事件符合規則時要採取哪些自動化動作。例如，您可以將 Amazon Quick Sight 設定為每當 Amazon Quick Sight 資產放置在資料夾中時，將事件傳送至 Amazon CloudWatch。如需詳細資訊，請參閱 [Amazon EventBridge user guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html)。
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在導覽窗格的 **Events (事件)** 中，選擇 **Rules (規則)**。
1. 選擇**建立規則**。
1. 輸入規則的名稱和描述。規則名稱在此區域內必須是唯一的。例如，輸入 `QuickSightAssetChangeRuleCloudWatch`。
1. 選擇**預設**事件匯流排。
1. 選擇**具有事件模式的規則**，然後選擇**下一步**。
1. 在**事件來源**欄位中，選擇 **AWS 事件或 EventBridge 合作夥伴事件**。
1. 在**建立方法**區段中，選擇**自訂模式 (JSON 編輯器)**。
1. 在**事件模式**文字方塊中，輸入下列程式碼片段，然後選擇**下一步**。
```
{
"source": ["aws.quicksight"]
}
```
或者，您可以建立僅訂閱 Amazon Quick Sight 中事件類型子集的規則。例如，只有在將資產新增至 ID 為 `77e307e8-b41b-472a-90e8-fe3f471537be` 的資料夾或從中移除資產時，才會觸發下列規則。
```
{
"source": ["aws.quicksight"],
"detail-type": ["QuickSight Folder Membership Updated"],
"detail": {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be"
}
}
```
1. 對於**目標**，選擇 **AWS 服務** > **CloudWatch 日誌群組。**
1. 從現有日誌群組中選擇，或透過輸入新的日誌群組名稱建立新的日誌群組。
1. 您可以選擇性地為此規則新增另一個目標。
1. 在 **Configure tags** (設定標籤) 中，選擇 **Next** (下一步)。
1. 選擇**建立規則**。
如需詳細資訊，請參閱 Amazon EventBridge user guide 中的 [Creating Amazon EventBridge rule that reacts To events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html)。
# 建立規則以將 Amazon Quick Sight 事件傳送至 AWS Lambda
在本教學課程中，您會建立 AWS Lambda 函數，記錄 Amazon Quick Sight 帳戶中的資產事件。然後，您可以建立每當資產變更時執行該函數的規則。本教學假設您已註冊 Amazon Quick Sight。
**步驟 1：建立 Lambda 函數**
建立 Lambda 函數以記錄狀態變更事件。當您在建立規則時指定此函數。
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/) 開啟 AWS Lambda 主控台。
1. 如果您是第一次使用 Lambda，將會看到歡迎頁面。選擇 **Get Started Now (立即開始)**。否則，請選擇 **Create function (建立函數)**。
1. 選擇 **Author from scratch (從頭開始撰寫)**。
1. 在「建立函數」頁面上，輸入 Lambda 函式的名稱與描述。例如，將函數命名為 `QuickSightAssetChangeFn`。
1. 在**執行時期**中，選取 **Node.js 18.x**。
1. 對於 **Architecture** (架構)，選擇 **x86\$164**。
1. 對於**執行角色**，選擇**建立具有基本 Lambda 許可的新角色**或**使用現有角色**，然後選擇您想要的角色。
1. 選擇**建立函數**。
1. 在 **QuickSightAssetChange** 頁面上，選擇 **index.js**。
1. 在 **index.js** 窗格中，刪除現有的程式碼。
1. 輸入下列程式碼片段。
```
console.log('Loading function');
exports.handler = async (event, context) => {
console.log('Received QuickSight event:', JSON.stringify(event));
};
```
1. 選擇**部署**。
**步驟 2：建立規則**
建立規則以在每次create/update/delete Amazon Quick Sight 資產時執行 Lambda 函數。
1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/)：// 開啟 Amazon EventBridge 主控台。
1. 在導覽窗格中，選擇**規則**。
1. 選擇**建立規則**。
1. 輸入規則的名稱和描述。例如，輸入 `QuickSightAssetChangeRule`。
1. 選取**預設**事件匯流排。
1. 選擇**具有事件模式的規則**，然後選擇**下一步**。
1. 在**事件來源**欄位中，選擇 **AWS 事件或 EventBridge 合作夥伴事件**。
1. 在**建立方法**區段中，選擇**自訂模式 (JSON 編輯器)**。
1. 在**事件模式**文字方塊中，輸入下列程式碼片段，然後選擇**下一步**。
```
{
"source": ["aws.quicksight"]
}
```
或者，您可以建立只訂閱 Amazon Quick Sight 中事件類型子集的規則。例如，只有在將資產新增至 ID 為 `77e307e8-b41b-472a-90e8-fe3f471537be` 的資料夾或從中移除資產時，才會觸發下列規則。
```
{
"source": ["aws.quicksight"],
"detail-type": ["QuickSight Folder Membership Updated"],
"detail": {
"folderId": "77e307e8-b41b-472a-90e8-fe3f471537be"
}
}
```
1. 對於**目標類型**，選擇 **AWS 服務**和 **Lambda 函式**。
1. 針對 **Function** (函數)，選擇您建立的 Lambda 函數。然後選擇**下一步**。
1. 在 **Configure tags** (設定標籤) 中，選擇 **Next** (下一步)。
1. 檢閱規則中的步驟。然後，選擇 **Create role** (建立角色)。
**步驟 3：測試規則**
若要測試您的規則，請建立分析。等待一分鐘後，驗證您的 Lambda 函式是否被調用。
1. 開啟位於 https：//[https://quicksight.aws.amazon.com/](https://quicksight.aws.amazon.com/) 的 Amazon Quick Sight 主控台。
1. 建立新的分析。
1. 在導覽窗格中，選擇 **Rules** (規則)，然後選擇您建立的規則名稱。
1. 在**規則詳細資料**中，選擇**監控**。
1. 系統會將您重新導向至 Amazon CloudWatch 主控台。如果未將您重新導向，請選擇**在 CloudWatch 中檢視指標**。
1. 在 **All metrics** (所有指標) 中，選擇您建立的規則名稱。該圖表指示該規則已被調用。
1. 在導覽窗格中，選擇 **Log groups** (日誌群組)。
1. 為您的 Lambda 函式選擇日誌群組名稱。例如 `/aws/lambda/function-name`。
1. 選擇日誌串流名稱以檢視函數為您啟動的執行個體所提供的資料。您應該會看到類似以下接收的事件：
```
{
"version": "0",
"id": "3acb26c8-397c-4c89-a80a-ce672a864c55",
"detail-type": "QuickSight Analysis Creation Successful",
"source": "aws.quicksight",
"account": "123456789012",
"time": "2023-10-30T22:06:31Z",
"region": "us-east-1",
"resources": ["arn:aws:quicksight:us-east-1:123456789012:analysis/e5f37119-e24c-4874-901a-af9032b729b5"],
"detail": {
"analysisId": "e5f37119-e24c-4874-901a-af9032b729b5"
}
}
```
如需 JSON 格式的 Amazon Quick Sight 事件範例，請參閱 [Amazon Quick Sight 的事件概觀](https://docs.aws.amazon.com/quicksight/latest/developerguide/events.html)。
# Amazon Quick Sight 的內嵌分析
**重要**
Amazon Quick Sight 有用於內嵌分析的新 API 操作： `GenerateEmbedUrlForAnonymousUser`和 `GenerateEmbedUrlForRegisteredUser`。
您仍然可以使用 `GetDashboardEmbedUrl`和 `GetSessionEmbedUrl` API 操作來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需使用舊 API 操作進行內嵌的詳細資訊，請參閱 [使用 GetDashboardEmbedURL 和 GetSessionEmbedURL API 操作內嵌分析](embedded-analytics-deprecated.md)。
| |
| --- |
| 適用於：企業版本 |
| |
| --- |
| 目標對象：Amazon Quick 開發人員 |
透過 Amazon Quick Sight 內嵌分析，您可以將資料驅動的體驗無縫整合到軟體應用程式中。您可以設定內嵌式元件的樣式以符合您的品牌。此功能可為您的最終使用者帶來 Amazon Quick Sight 的強大功能，他們可以分析資料並與之互動，而無需離開應用程式。通過降低認知複雜性來改善使用者體驗，令使用者可以獲得更深入的理解和更好的有效性。
Amazon Quick Sight 支援這些元素的內嵌：
+ Amazon Quick Sight 主控台 （已註冊使用者的完整撰寫體驗）
+ Amazon Quick Sight 儀表板和視覺效果 （適用於已註冊使用者、匿名使用者、公有最終使用者）
+ Amazon Quick Sight Q 搜尋列 （適用於已註冊使用者和匿名使用者）
使用內嵌的 Amazon Quick Sight 主控台，您可以嵌入完整的 Amazon Quick Sight 體驗。這樣做可讓您使用 Amazon Quick Sight 撰寫工具做為應用程式的一部分，而不是在 AWS 管理主控台 或獨立網站的內容中。內嵌 Amazon Quick Sight 主控台的使用者需要在 中註冊為 Amazon Quick Sight 作者或管理員 AWS 帳戶。他們也需要使用任何 Amazon Quick Sight 支援的身分驗證方法 AWS 帳戶，在相同的 中進行身分驗證。
透過內嵌 Amazon Quick Sight 儀表板或視覺效果，讀者可以獲得與在已發佈儀表板或視覺效果中相同的功能和互動性。若要使用內嵌式儀表板或視覺效果，讀者 (檢視者) 可以包含下列任何一項：
+ 透過 Amazon Quick Sight 支援的任何方法 AWS 帳戶 在 中驗證的 Amazon Quick Sight 使用者。
+ 網站或應用程式的未驗證訪客 – 此選項需要具有容量定價的工作階段套件。如需訂閱類型的相關資訊，請參閱[了解 Amazon Quick Sight 訂閱和角色](https://docs.aws.amazon.com/quicksight/latest/user/user-types.html#subscription-role-mapping)。
+ 多位最終使用者透過程式化存取在監視器或大螢幕上檢視顯示內容。
如果您的應用程式也位於 中 AWS，則應用程式不需要與 AWS 帳戶 Amazon Quick Sight 訂閱位於相同的 上。不過，應用程式需要能夠擔任您用於 API 呼叫的 AWS Identity and Access Management (IAM) 角色。
您必須先在 AWS 帳戶 計劃使用內嵌的 中使用 Amazon Quick Sight Enterprise Edition，才能內嵌內容。
Amazon Quick Sight 內嵌可在所有支援的 中使用 AWS 區域。
**Topics**
+ [將 Amazon Quick Sight 分析嵌入您的應用程式](embedding-overview.md)
+ [將自訂 Amazon Quick Sight 資產內嵌到您的應用程式](customize-and-personalize-embedded-analytics.md)
+ [使用一鍵式內嵌程式碼內嵌 Amazon Quick Sight 視覺效果和儀表板](1-click-embedding.md)
+ [使用 Amazon Quick Sight APIs 內嵌](embedded-analytics-api.md)
# 將 Amazon Quick Sight 分析嵌入您的應用程式
| |
| --- |
| 適用於：企業版 |
若要內嵌分析，您可以執行 Amazon Quick Sight 內嵌 API 來產生內嵌程式碼。或者，對於儀表板，您可以在 Amazon Quick Sight 中共用儀表板時複製內嵌程式碼。每個選項如下所述。
## 已註冊使用者可一鍵式嵌入
當您與帳戶中已註冊的使用者共用儀表板時，可以複製儀表板的內嵌程式碼，並將其貼到內部應用程式的 HTML 中。
當您想要在使用者需要驗證的內部應用程式中嵌入 Amazon Quick Sight 儀表板時，最好使用一鍵式企業內嵌。當您複製內嵌程式碼時，會取得不會變更的靜態內嵌程式碼。
如需詳細資訊，請參閱[使用一鍵式內嵌程式碼為已註冊使用者內嵌 Amazon Quick Sight 視覺效果和儀表板](embedded-analytics-1-click.md)。
## 使用 Amazon Quick Sight APIs 內嵌
當您想要將 Amazon Quick Sight 體驗內嵌在使用者必須驗證的內部應用程式中，或任何人都可以存取的外部應用程式中時，內嵌 Amazon Quick Sight API 最適合使用。當您使用嵌入 API 操作產生內嵌程式碼時，您會取得一次性程式碼。
如需詳細資訊，請參閱[使用 Amazon Quick Sight APIs 內嵌](embedded-analytics-api.md)。
# 將自訂 Amazon Quick Sight 資產內嵌到您的應用程式
您可以使用 Amazon Quick Sight 內嵌分析，將自訂 Amazon Quick Sight 資產嵌入您的應用程式，這些資產專為滿足您的業務需求而量身打造。對於內嵌儀表板和視覺效果，Amazon Quick Sight 作者可以新增篩選條件和深入探討，讀者可以在導覽儀表板或視覺效果時存取這些篩選條件和深入探討。Amazon Quick Sight 開發人員也可以使用 Amazon Quick Sight SDKs，在 SaaS 應用程式與其 Amazon Quick Sight 內嵌資產之間建立更緊密的整合，以在執行時間將資料點回呼動作新增至儀表板上的視覺效果。
如需 Amazon Quick Sight SDKs的詳細資訊，請參閱 [GitHub](https://github.com/awslabs/amazon-quicksight-embedding-sdk) 或 [NPM](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) `amazon-quicksight-embedding-sdk`上的 。
您可以在下面找到如何使用 Amazon Quick Sight SDKs自訂 Amazon Quick Sight 內嵌分析的說明。
**Topics**
+ [在 Amazon Quick Sight 中於執行時間新增內嵌回呼動作](embedding-custom-actions-callback.md)
+ [在執行時間篩選 Amazon Quick Sight 內嵌儀表板和視覺效果的資料](embedding-runtime-filtering.md)
+ [自訂 Amazon Quick Sight 內嵌儀表板和視覺效果的外觀和風格](embedding-runtime-theming.md)
+ [使用 Amazon Quick Sight 內嵌 SDK 啟用內嵌儀表板檢視的可共用連結](embedded-view-sharing.md)
# 在 Amazon Quick Sight 中於執行時間新增內嵌回呼動作
使用內嵌資料點回呼動作，在軟體即服務 (SaaS) 應用程式與 Amazon Quick Sight 內嵌儀表板和視覺效果之間建立更緊密的整合。開發人員可以使用 Amazon Quick Sight 內嵌 SDK 註冊要回呼的資料點。當您註冊視覺效果的回呼動作時，讀者可以在視覺效果上選取資料點，以接收提供所選資料點特定資料的回呼。此資訊可用於標記主要記錄、編譯資料點特定的原始資料、擷取記錄，以及編譯後端處理程序的資料。
自訂視覺內容、文字方塊或深入解析不支援內嵌回呼。
在您開始註冊回呼的資料點之前，請將內嵌開發套件更新至 2.3.0 版。如需使用 Amazon Quick Sight 內嵌 SDK 的詳細資訊，請參閱 GitHub 上的 [amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。
資料點回呼可以在執行時間透過 Amazon Quick Sight SDK 註冊至一或多個視覺效果。您也可以將資料點回呼註冊至 [VisualCustomAction](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_VisualCustomAction.html) API 結構支援的任何互動。這允許使用者在視覺效果上選取資料點時，或從資料點內容選單中選取資料點時，啟動資料點回呼。下列範例註冊讀者在視覺效果上選取資料點時所啟動的資料點回呼。
```
/const MY_GET_EMBED_URL_ENDPOINT =
"https://my.api.endpoint.domain/MyGetEmbedUrlApi"; // Sample URL
// The dashboard id to embed
const MY_DASHBOARD_ID = "my-dashboard"; // Sample ID
// The container element in your page that will have the embedded dashboard
const MY_DASHBOARD_CONTAINER = "#experience-container"; // Sample ID
// SOME HELPERS
const ActionTrigger = {
DATA_POINT_CLICK: "DATA_POINT_CLICK",
DATA_POINT_MENU: "DATA_POINT_MENU",
};
const ActionStatus = {
ENABLED: "ENABLED",
DISABLED: "DISABLED",
};
// This function makes a request to your endpoint to obtain an embed url for a given dashboard id
// The example implementation below assumes the endpoint takes dashboardId as request data
// and returns an object with EmbedUrl property
const myGetEmbedUrl = async (dashboardId) => {
const apiOptions = {
dashboardId,
};
const apiUrl = new URL(MY_GET_EMBED_URL_ENDPOINT);
apiUrl.search = new URLSearchParams(apiOptions).toString();
const apiResponse = await fetch(apiUrl.toString());
const apiResponseData = await apiResponse.json();
return apiResponseData.EmbedUrl;
};
// This function constructs a custom action object
const myConstructCustomActionModel = (
customActionId,
actionName,
actionTrigger,
actionStatus
) => {
return {
Name: actionName,
CustomActionId: customActionId,
Status: actionStatus,
Trigger: actionTrigger,
ActionOperations: [
{
CallbackOperation: {
EmbeddingMessage: {},
},
},
],
};
};
// This function adds a custom action on the first visual of first sheet of the embedded dashboard
const myAddVisualActionOnFirstVisualOfFirstSheet = async (
embeddedDashboard
) => {
// 1. List the sheets on the dashboard
const { SheetId } = (await embeddedDashboard.getSheets())[0];
// If you'd like to add action on the current sheet instead, you can use getSelectedSheetId method
// const SheetId = await embeddedDashboard.getSelectedSheetId();
// 2. List the visuals on the specified sheet
const { VisualId } = (await embeddedDashboard.getSheetVisuals(SheetId))[0];
// 3. Add the custom action to the visual
try {
const customActionId = "custom_action_id"; // Sample ID
const actionName = "Flag record"; // Sample name
const actionTrigger = ActionTrigger.DATA_POINT_CLICK; // or ActionTrigger.DATA_POINT_MENU
const actionStatus = ActionStatus.ENABLED;
const myCustomAction = myConstructCustomActionModel(
customActionId,
actionName,
actionTrigger,
actionStatus
);
const response = await embeddedDashboard.addVisualActions(
SheetId,
VisualId,
[myCustomAction]
);
if (!response.success) {
console.log("Adding visual action failed", response.errorCode);
}
} catch (error) {
console.log("Adding visual action failed", error);
}
};
const parseDatapoint = (visualId, datapoint) => {
datapoint.Columns.forEach((Column, index) => {
// FIELD | METRIC
const columnType = Object.keys(Column)[0];
// STRING | DATE | INTEGER | DECIMAL
const valueType = Object.keys(Column[columnType])[0];
const { Column: columnMetadata } = Column[columnType][valueType];
const value = datapoint.RawValues[index][valueType];
const formattedValue = datapoint.FormattedValues[index];
console.log(
`Column: ${columnMetadata.ColumnName} has a raw value of ${value}
and formatted value of ${formattedValue.Value} for visual: ${visualId}`
);
});
};
// This function is used to start a custom workflow after the end user selects a datapoint
const myCustomDatapointCallbackWorkflow = (callbackData) => {
const { VisualId, Datapoints } = callbackData;
parseDatapoint(VisualId, Datapoints);
};
// EMBEDDING THE DASHBOARD
const main = async () => {
// 1. Get embed url
let url;
try {
url = await myGetEmbedUrl(MY_DASHBOARD_ID);
} catch (error) {
console.log("Obtaining an embed url failed");
}
if (!url) {
return;
}
// 2. Create embedding context
const embeddingContext = await createEmbeddingContext();
// 3. Embed the dashboard
const embeddedDashboard = await embeddingContext.embedDashboard(
{
url,
container: MY_DASHBOARD_CONTAINER,
width: "1200px",
height: "300px",
resizeHeightOnSizeChangedEvent: true,
},
{
onMessage: async (messageEvent) => {
const { eventName, message } = messageEvent;
switch (eventName) {
case "CONTENT_LOADED": {
await myAddVisualActionOnFirstVisualOfFirstSheet(embeddedDashboard);
break;
}
case "CALLBACK_OPERATION_INVOKED": {
myCustomDatapointCallbackWorkflow(message);
break;
}
}
},
}
);
};
main().catch(console.error);
```
您也可以將上述範例設定為在使用者開啟內容選單時啟動資料點回呼。若要在上述範例中執行此操作，請將 `actionTrigger` 的值設定為 `ActionTrigger.DATA_POINT_MENU`。
註冊資料點回呼之後，它會套用至指定視覺效果上的大多數資料點。回呼不會套用至視覺效果上的總計或小計。當讀取器與資料點互動時，`CALLBACK_OPERATION_INVOKED`訊息會傳送到 Amazon Quick Sight 內嵌 SDK。`onMessage` 處理常式會擷取此訊息。此訊息包含與所選資料點相關聯的完整資料列的原始值和顯示值。它也包含具有資料點之視覺效果中所有資料欄的資料欄中繼資料。以下是 `CALLBACK_OPERATION_INVOKED` 訊息的範例。
```
{
CustomActionId: "custom_action_id",
DashboardId: "dashboard_id",
SheetId: "sheet_id",
VisualId: "visual_id",
DataPoints: [
{
RawValues: [
{
String: "Texas" // 1st raw value in row
},
{
Integer: 1000 // 2nd raw value in row
}
],
FormattedValues: [
{Value: "Texas"}, // 1st formatted value in row
{Value: "1,000"} // 2nd formatted value in row
],
Columns: [
{ // 1st column metadata
Dimension: {
String: {
Column: {
ColumnName: "State",
DatsetIdentifier: "..."
}
}
}
},
{ // 2nd column metadata
Measure: {
Integer: {
Column: {
ColumnName: "Cancelled",
DatsetIdentifier: "..."
},
AggregationFunction: {
SimpleNumericalAggregation: "SUM"
}
}
}
}
]
}
]
}
```
# 在執行時間篩選 Amazon Quick Sight 內嵌儀表板和視覺效果的資料
您可以使用 Amazon Quick Sight 內嵌 SDK 中的篩選方法，在執行時間利用軟體即服務 (SaaS) 應用程式內的 Amazon Quick Sight 篩選功能。執行期篩選條件可讓企業擁有者將其應用程式與內嵌的 Amazon Quick Sight 儀表板和視覺效果整合。若要達成此目的，請在應用程式中建立自訂篩選條件控制項，並根據應用程式的資料套用篩選預設。然後，開發人員可以在執行時期為最終使用者個人化篩選條件組態。
開發人員可以使用 Amazon Quick Sight 內嵌 SDK，在內嵌儀表板或視覺效果上建立、查詢、更新和移除 Amazon Quick Sight 篩選條件。使用 [FilterGroup](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_FilterGroup.html) 資料模型在應用程式中建立 Amazon Quick Sight 篩選物件，並使用篩選方法將其套用至內嵌儀表板和視覺效果。如需使用 Amazon Quick Sight 內嵌 SDK 的詳細資訊，請參閱 GitHub 上的 [amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。
**先決條件**
開始使用之前，請確定您使用的是 Amazon Quick Sight Embedding SDK 2.5.0 版或更新版本。
## 術語與概念
下列術語在使用嵌入式執行時期篩選時非常實用。
+ *篩選條件群組*：個別篩選條件的群組。位於 `FilterGroup` 中的篩選條件彼此進行 OR 運算彙總。[FilterGroup](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_FilterGroup.html) 中的篩選條件會套用到相同的工作表或視覺效果。
+ *篩選條件*：單一篩選條件。篩選條件可以是類別、數值或日期時間篩選條件類型。如需有關篩選條件的詳細資訊，請參閱[篩選條件](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_Filter.html)。
## 設定
在開始前，請確定您已準備好下列資產與資訊。
+ 您想要將 `FilterGroup` 的範圍限定在其中的工作表的 ID。這可透過「嵌入式 SDK」中的 `getSheets` 方法取得。
+ 您要篩選之資料集的資料集與資料欄識別碼。這可透過 [DescribeDashboardDefinition](https://docs.aws.amazon.com/APIReference/API_DescribeDashboardDefinition.html) API 操作取得。
根據您使用的資料欄類型，可能會限制可新增至嵌入式資產的篩選條件類型。如需有關篩選條件限制的詳細資訊，請參閱[篩選條件](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_Filter.html)。
+ 您想要將 `FilterGroup` 的範圍限定在其中的視覺效果的 ID (如適用)。這可以透過使用「嵌入式 SDK」中的 `getSheetVisuals` 方法取得。
除了 `getSheetVisuals` 方法之外，只能將您新增之 `FilterGroup` 的範圍限定在目前選取的工作表。
若要使用此功能，您必須已透過 Amazon Quick Sight Embedding SDK 將儀表板或視覺效果內嵌至您的應用程式。如需使用 Amazon Quick Sight 內嵌 SDK 的詳細資訊，請參閱 GitHub 上的 [amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。
## SDK 方法界面
**儀表板嵌入 getter 方法**
下表說明開發人員可以使用的不同儀表板嵌入 getter 方法。
| Method | Description |
| --- | --- |
| `getFilterGroupsForSheet(sheetId: string) ` | 傳回目前範圍限定在參數中提供之工作表的所有 FilterGroups。 |
| `getFilterGroupsForVisual(sheetId: string, visualId: string)` | 傳回範圍限定在參數中提供之視覺效果的所有 `FilterGroups`。 |
如果參數中提供的工作表不是嵌入式儀表板目前選取的工作表，上述方法會傳回錯誤。
**視覺效果嵌入 getter 方法**
下表說明開發人員可以使用的不同視覺效果嵌入 getter 方法。
| Method | Description |
| --- | --- |
| `getFilterGroups()` | 傳回目前範圍限定在嵌入式視覺效果的所有 `FilterGroups`。 |
**Setter 方法**
下表說明開發人員可用於儀表板或視覺效果嵌入的不同 Setter 方法。
| Method | Description |
| --- | --- |
| `addFilterGroups(filterGroups: FilterGroup[])` | 將提供的 **FilterGroups** 新增並套用到嵌入式儀表板或視覺效果。會傳回表明新增項目是否成功的 `ResponseMessage`。 |
| `updateFilterGroups(filterGroups: FilterGroup[])` | 更新嵌入式功能上的 `FilterGroups`，其中包含與參數中提供的 `FilterGroup` 相同的 `FilterGroupId`。會傳回表明更新是否成功的 `ResponseMessage`。 |
| `removeFilterGroups(filterGroupsOrIds: FilterGroup[] \| string[])` | 從儀表板移除提供的 FilterGroups，並傳回表明移除嘗試是否成功的 `ResponseMessage`。 |
提供的 `FilterGroup` 之範圍必須限定在目前選取的嵌入式工作表或視覺效果。
# 自訂 Amazon Quick Sight 內嵌儀表板和視覺效果的外觀和風格
您可以使用 Amazon Quick Sight 內嵌 SDK (2.5.0 版及更高版本），在執行時間變更內嵌 Amazon Quick Sight 儀表板和視覺效果。執行期它們可讓您更輕鬆地將軟體即服務 (SaaS) 應用程式與 Amazon Quick Sight 內嵌資產整合。執行期它們可讓您將內嵌內容的主題與內嵌 Amazon Quick Sight 資產的父應用程式主題同步。您也可以使用執行時期佈景主題設定，為讀者新增自訂選項。佈景主題設定變更可在初始化時或嵌入式儀表板或視覺效果的整個生命週期內套用至嵌入式資產。
如需有關佈景主題的詳細資訊，請參閱[在 Amazon Quick Sight 中使用佈景主題](themes-in-quicksight.md)。如需使用 Amazon Quick Sight 內嵌 SDK 的詳細資訊，請參閱 GitHub 上的 [amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。
**先決條件**
開始使用之前，請確定已滿足下列必要先決條件。
+ 您使用的是 Amazon Quick Sight 內嵌 SDK 2.5.0 版或更新版本。
+ 要使用之佈景主題的存取許可。若要在 Amazon Quick Sight 中授予佈景主題的許可，請進行 `UpdateThemePermissions` API 呼叫或使用 Amazon Quick Sight 主控台分析編輯器中佈景主題旁的**共用**圖示。
## 術語與概念
下列術語在使用嵌入執行時期佈景主題設定時非常實用。
+ *佈景主題*：您可以套用到多個分析和儀表板，以變更內容顯示方式的一組設定。
+ *佈景主題組態*：包含佈景主題所有顯示屬性的組態物件。
+ *佈景主題覆寫*：套用至作用中佈景主題的 `ThemeConfiguration` 物件，可覆寫內容顯示方式的部分或全部層面。
+ *佈景主題 ARN * – 識別 Amazon Quick Sight 佈景主題的 Amazon Resource Name (ARN)。下方是自訂佈景主題 ARN 的範例。
`arn:aws:quicksight:region:account-id:theme/theme-id`
Amazon Quick Sight 提供的入門佈景主題在其佈景主題 ARN 中沒有區域。下方是入門佈景主題 ARN 的範例。
`arn:aws:quicksight::aws:theme/CLASSIC`
## 設定
請確定您已準備好下列資訊，以開始使用執行時期佈景主題設定。
+ 想要使用之佈景主題的 ARN。您可以選擇現有的佈景主題，也可以建立新的佈景主題。若要取得 Amazon Quick Sight 帳戶中所有佈景主題和佈景主題 ARNs清單，請呼叫 [ListThemes](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_ListThemes.html) API 操作。如需預設 Amazon Quick Sight 主題的詳細資訊，請參閱 [使用 Amazon Quick APIs 設定 Amazon Quick 分析的預設佈景主題](customizing-quicksight-default-theme.md)。
+ 如果您使用的是已註冊的使用者嵌入，請確定使用者可存取您想要使用的佈景主題。
如果您使用匿名使用者嵌入，請將佈景主題 ARN 清單傳遞至 `GenerateEmbedUrlForAnonymousUser` API 的 `AuthorizedResourceArns` 參數。匿名使用者可存取 `AuthorizedResourceArns` 參數中列出的任何佈景主題。
## SDK 方法界面
**Setter 方法**
下表說明開發人員可用於執行時期佈景主題設定的不同 Setter 方法。
| Method | Description |
| --- | --- |
| `setTheme(themeArn: string)` | 以另一個佈景主題取代儀表板或視覺效果的作用中佈景主題。如果套用，則會移除佈景主題覆寫。 如果您無法存取佈景主題或佈景主題不存在，則會傳回錯誤。 |
| `setThemeOverride(themeOverride: ThemeConfiguration)` | 設定動態 `ThemeConfiguration` 以覆寫目前的作用中佈景主題。這會取代先前設定的佈景主題覆寫。任何未在新 `ThemeConfiguration` 中提供的值，都會預設為目前作用中佈景主題中的值。 如果您提供的 `ThemeConfiguration` 無效，則會傳回錯誤。 |
## 初始化使用佈景主題的嵌入式內容
若要初始化使用非預設佈景主題的嵌入式儀表板或視覺效果，請在 `DashboardContentOptions` 或 `VisualContentOptions` 參數上定義 `themeOptions` 物件，並將 `themeOptions` 中的 `themeArn` 屬性設定為所需的佈景主題 ARN。
下列範例會使用 `MIDNIGHT` 佈景主題初始化嵌入式儀表板。
```
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';
const embeddingContext = await createEmbeddingContext();
const {
embedDashboard,
} = embeddingContext;
const frameOptions = {
url: '',
container: '#experience-container',
};
const contentOptions = {
themeOptions: {
themeArn: "arn:aws:quicksight::aws:theme/MIDNIGHT"
}
};
// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```
## 初始化使用佈景主題覆寫的嵌入式內容
開發人員可以使用佈景主題覆寫，在執行時期定義嵌入式儀表板或視覺效果的佈景主題。這可讓儀表板或視覺效果從第三方應用程式繼承佈景主題，而不需要在 Amazon Quick Sight 中預先設定佈景主題。若要初始化使用佈景主題覆寫的嵌入式儀表板或視覺效果，請在 `DashboardContentOptions` 或 `VisualContentOptions` 參數中的 `themeOptions` 內設定 `themeOverride` 屬性。下列範例會將儀表板佈景主題的字型從預設字型覆寫為 `Amazon Ember`。
```
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';
const embeddingContext = await createEmbeddingContext();
const {
embedDashboard,
} = embeddingContext;
const frameOptions = {
url: '',
container: '#experience-container',
};
const contentOptions = {
themeOptions: {
"themeOverride":{"Typography":{"FontFamilies":[{"FontFamily":"Comic Neue"}]}}
}
};
// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```
## 初始化使用預先載入佈景主題的嵌入式內容
開發人員可以設定一組要在初始化時預先載入的儀表板佈景主題。這對於在不同檢視 (例如深色和淺色模式) 之間快速切換最有益處。嵌入式儀表板或視覺效果進行初始化時最多可使用 5 個預先載入佈景主題。若要使用預先載入佈景主題，請在 `DashboardContentOptions` 或 `VisualContentOptions` 中設定 `preloadThemes` 屬性，陣列最多可達 5 個 `themeArns`。下列範例會將 `Midnight` 和 `Rainier` 入門佈景主題預先載入到儀表板。
```
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';
const embeddingContext = await createEmbeddingContext();
const {
embedDashboard,
} = embeddingContext;
const frameOptions = {
url: '',
container: '#experience-container',
};
const contentOptions = {
themeOptions: {
"preloadThemes": ["arn:aws:quicksight::aws:theme/RAINIER", "arn:aws:quicksight::aws:theme/MIDNIGHT"]
}
};
// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```
# 使用 Amazon Quick Sight 內嵌 SDK 啟用內嵌儀表板檢視的可共用連結
Amazon Quick Sight 開發人員可以使用 Amazon Quick Sight 內嵌 SDK (2.8.0 版及更高版本） 來允許內嵌儀表板的讀者接收可共用連結並將其分發至其對內嵌儀表板的檢視。開發人員可以使用儀表板或主控台內嵌，透過使用 Amazon Quick Sight 內嵌 SDK 封裝的 Amazon Quick Sight 參考，產生可共用的應用程式頁面連結。然後，Amazon Quick Sight Readers 可以將此可共用連結傳送給其對等。當其對等存取共用連結時，它們會移至包含內嵌 Amazon Quick Sight 儀表板的應用程式上的 頁面。開發人員也可以產生和儲存儀表板檢視的可共用連結，這些連結可在使用匿名內嵌時做為 Amazon Quick Sight 匿名讀者的書籤。
**先決條件**
開始使用之前，請確定您使用的是 Amazon Quick Sight 內嵌 SDK 2.8.0 版或更新版本
**Topics**
+ [啟用 Amazon Quick Sight 內嵌分析`SharedView`的功能組態](embedded-view-sharing-set-up.md)
+ [使用 Amazon Quick Sight `createSharedView` API 建立共用檢視](embedded-view-sharing-sdk-create.md)
+ [使用共用的 Amazon Quick Sight 檢視](embedded-view-sharing-sdk-consume.md)
# 啟用 Amazon Quick Sight 內嵌分析`SharedView`的功能組態
當您使用 Amazon Quick Sight API 建立內嵌執行個體時，請將`FeatureConfigurations`承載`SharedView`中的 值設定為 `true`，如以下範例所示。 會`SharedView`覆寫存取內嵌儀表板的已註冊使用者`StatePersistence`組態。如果儀表板使用者已停用 `StatePersistence` 並啟用 `SharedView`，則其狀態仍將持續存在。
```
const generateNewEmbedUrl = async () => {
const generateUrlPayload = {
experienceConfiguration: {
QuickSightConsole: {
FeatureConfigurations: {
"SharedView": {
"Enabled": true
},
},
},
}
const result: GenerateEmbedUrlResult = await generateEmbedUrlForRegisteredUser(generateUrlPayload);
return result.url;
};
```
# 使用 Amazon Quick Sight `createSharedView` API 建立共用檢視
將嵌入式 SDK 更新至 2.8.0 版或更新版本後，請使用 `createSharedView` API 建立新的共用檢視。記錄操作傳回的 `sharedViewId` 和 `dashboardId`。下方範例會建立新的共用檢視。
```
const response = await embeddingFrame.createSharedView();
const sharedViewId = response.message.sharedViewId;
const dashboardId = response.message.dashboardId;
```
只有在使用者檢視儀表板時，才能呼叫 `createSharedView`。如果要建立主控台特定的共用檢視，請確定使用者位於儀表板頁面，然後再啟用 `createSharedView` 動作。您可以使用 `PAGE_NAVIGATION` 事件執行此操作，如下方範例所示。
```
const contentOptions = {
onMessage: async (messageEvent, metadata) => {
switch (messageEvent.eventName) {
case 'CONTENT_LOADED': {
console.log("Do something when the embedded experience is fully loaded.");
break;
}
case 'ERROR_OCCURRED': {
console.log("Do something when the embedded experience fails loading.");
break;
}
case 'PAGE_NAVIGATION': {
setPageType(messageEvent.message.pageType);
if (messageEvent.message.pageType === 'DASHBOARD') {
setShareEnabled(true);
} else {
setShareEnabled(false);
}
break;
}
}
}
};
```
# 使用共用的 Amazon Quick Sight 檢視
建立新的共用檢視後，請使用嵌入式 SDK 讓其他使用者也可使用共用檢視。以下範例為 Amazon Quick Sight 中的內嵌儀表板設定消耗性共用檢視。
------
#### [ With an appended URL ]
在 ` /views/{viewId}` 下，將 `sharedViewId` 附加至嵌入式 URL，並將此 URL 公開給您的使用者。使用者可以使用此 URL 來導覽至該共用檢視。
```
const response = await dashboardFrame.createSharedView();
const newEmbedUrl = await generateNewEmbedUrl();
const formattedUrl = new URL(newEmbedUrl);
formattedUrl.pathname = formattedUrl.pathname.concat('/views/' + response.message.sharedViewId);
const baseUrl = formattedUrl.href;
alert("Click to view this QuickSight shared view", baseUrl);
```
------
#### [ With the contentOptions SDK ]
將 `viewId` 傳遞至 `contentOptions`，以開啟具有指定 `viewId` 的檢視。
```
const contentOptions = {
toolbarOptions: {
...
},
viewId: sharedViewId,
};
const embeddedDashboard = await embeddingContext.embedDashboard(
{container: containerRef.current},
contentOptions
);
```
------
#### [ With the InitialPath property ]
```
const shareView = async() => {
const returnValue = await consoleFrame.createSharedView();
const {dashboardId, sharedViewId} = returnValue.message;
const newEmbedUrl = await generateNewEmbedUrl(`/dashboards/${dashboardId}/views/${sharedViewId}`);
setShareUrl(newEmbedUrl);
};
const generateNewEmbedUrl = async (initialPath) => {
const generateUrlPayload = {
experienceConfiguration: {
QuickSightConsole: {
InitialPath: initialPath,
FeatureConfigurations: {
"SharedView": {
"Enabled": true
},
},
},
}
const result: GenerateEmbedUrlResult = await generateEmbedUrlForRegisteredUser(generateUrlPayload);
return result.url;
};
```
------
# 使用一鍵式內嵌程式碼內嵌 Amazon Quick Sight 視覺效果和儀表板
您可以使用內嵌程式碼將視覺效果或儀表板嵌入應用程式中。當您共用儀表板或從 Amazon Quick Sight 中的**內嵌視覺**效果選單取得此程式碼。
您可以在已註冊使用者的內部應用程式中嵌入視覺效果或儀表板。或者，您可以在 Amazon Quick Sight 主控台中開啟公開共用。這樣做可讓網際網路上的任何人存取內嵌在公用應用程式、Wiki 或入口網站中的共用視覺效果或儀表板。
接下來，您可以找到有關如何使用一鍵式視覺效果或儀表板內嵌程式碼嵌入視覺效果和儀表板的說明。
**Topics**
+ [使用一鍵式內嵌程式碼為已註冊使用者內嵌 Amazon Quick Sight 視覺效果和儀表板](embedded-analytics-1-click.md)
+ [使用一鍵式內嵌程式碼為匿名使用者內嵌 Amazon Quick Sight 視覺效果和儀表板](embedded-analytics-1-click-public.md)
# 使用一鍵式內嵌程式碼為已註冊使用者內嵌 Amazon Quick Sight 視覺效果和儀表板
| |
| --- |
| 適用於：企業版 |
您可以在內部應用程式中為 Amazon Quick Sight 帳戶的註冊使用者嵌入視覺效果或儀表板。您可以使用共用儀表板或從 Amazon Quick Sight 中的**內嵌視覺效果**選單取得的內嵌程式碼來執行此操作。您不需要執行 Amazon Quick Sight 內嵌 API 即可產生內嵌程式碼。您可以從 Amazon Quick Sight 複製內嵌程式碼，並將其貼到內部應用程式的 HTML 程式碼中。
當使用者和群組 （或 Amazon Quick Sight 帳戶上的所有使用者） 可以存取您要內嵌的儀表板，或擁有您要內嵌存取內部應用程式的視覺效果時，系統會提示他們使用其登入資料登入 Amazon Quick Sight 帳戶。通過身分驗證後，他們可以存取其內部頁面上的視覺效果或儀表板。如果您已啟用單一登入，則不會提示使用者再次登入。
接下來，您可以找到有關如何使用視覺效果或儀表板內嵌程式碼為已註冊使用者嵌入視覺效果或儀表板的描述。
## 開始之前
開始之前，請確認以下事項：
+ 您的網際網路瀏覽器設定包含以下項之一，以允許快顯窗口和 iframe 之間的通訊：
+ 對於 Mozilla 廣播頻道 API 的原生支援。如需詳細資訊，請參閱 Mozilla 文件中的[廣播頻道 API](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API)。
+ IndexedDB 支援。
+ LocalStorage 支援。
+ 您的網際網路瀏覽器的「阻止所有 cookie」設定已關閉。
## 步驟 1：授予對儀表板的存取權
若要讓使用者存取內嵌式儀表板，請向他們授予檢視內嵌式儀表板的存取權。您可以授予個別使用者和群組存取儀表板的權限，或授予帳戶中的每個人存取權。視覺效果許可是在儀表板層級決定的。若要授予內嵌視覺效果的存取權，請授予視覺效果所屬儀表板的存取權。如需詳細資訊，請參閱[授予儀表板的存取權](share-a-dashboard.md)。
## 步驟 2：將要嵌入視覺效果或儀表板的域放在允許清單中
若要在內部應用程式中嵌入視覺效果和儀表板，請確保在 Amazon Quick Sight 帳戶中允許列出您內嵌的網域。如需詳細資訊，請參閱[將靜態域新增至允許清單](manage-domains.md#embedding-static)。
## 步驟 3：取得內嵌程式
使用下列步驟來取得視覺效果或儀表板內嵌程式碼。
**若要取得儀表板內嵌程式碼**
1. 在 Amazon Quick Sight 中開啟發佈的儀表板，然後選擇右上角的**共用**。然後選擇**共用儀表板**。
1. 在開啟的**共用儀表板**頁面中，選擇左上角的**複製內嵌程式碼**。
內嵌程式碼已複製到剪貼簿，類似以下項目。此範例中`quicksightdomain`的 是您用來存取 Amazon Quick Sight 帳戶的 URL。
```
```
**若要取得視覺效果內嵌程式碼**
1. 在 Amazon Quick Sight 中開啟已發佈的儀表板，然後選擇您要嵌入的視覺效果。然後開啟視覺效果右上角的視覺效果選單，選擇**內嵌視覺效果**。
1. 在開啟的**內嵌視覺效果**窗格中，選擇**複製程式碼**。
內嵌程式碼已複製到剪貼簿，類似以下項目。此範例中`quicksightdomain`的 是您用來存取 Amazon Quick Sight 帳戶的 URL。
```
```
## 步驟 4：將程式碼粘貼到內部應用程序的 HTML 頁面
使用下列程序將內嵌程式碼貼到內部應用程式的 HTML 頁面
**若要將程式碼粘貼到內部應用程序的 HTML 頁面**
+ 開啟您要嵌入儀表板的任何頁面的 HTML 程式碼，然後將內嵌程式碼貼入其中。
下列範例展示了內嵌式儀表板的可能情況。此範例中`quicksightdomain`的 是您用來存取 Amazon Quick Sight 帳戶的 URL。
```
Example.com - Employee Portal
Current shipment stats
```
下列範例展示了內嵌式視覺效果的可能情況。此範例中`quicksightdomain`的 是您用來存取 Amazon Quick Sight 帳戶的 URL。
```
Example.com - Employee Portal
Current shipment stats
```
例如，假設您想要在 Google Sites 內部網頁中嵌入視覺效果或儀表板。您可以在 Google Sites 上開啟網頁，然後將內嵌程式碼貼到內嵌小工具中。
如果您想要在內部 Microsoft SharePoint 網站中內嵌您的視覺效果或儀表板，您可以建立新頁面，然後將內嵌程式碼貼到內嵌網頁部分中。
# 使用一鍵式內嵌程式碼為匿名使用者內嵌 Amazon Quick Sight 視覺效果和儀表板
| |
| --- |
| 適用於：企業版 |
您可以使用在 Amazon Quick Sight 中共用視覺效果或儀表板時取得的內嵌程式碼，在公有網站中內嵌視覺效果或儀表板。您也可以使用 Amazon Quick Sight 主控台開啟公開共用，並自動將共用視覺效果或儀表板的存取權授予網際網路上的任何人。
接下來，您可以了解如何為視覺或儀表板開啟公開共用，以及如何嵌入視覺或儀表板讓任何人在網際網路上查看。在這兩種情況下，您都可以使用一鍵式內嵌程式碼來執行此操作。
## 開始之前
開始之前，請確認以下事項：
+ 您的網際網路瀏覽器設定包含下列其中一項，以允許快顯視窗與共用使用的 iframe 之間進行通訊：
+ 對於 Mozilla 廣播頻道 API 的原生支援。如需詳細資訊，請參閱 Mozilla 文件中的[廣播頻道 API](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API)。
+ IndexedDB 支援。
+ LocalStorage 支援。
+ 您的網際網路瀏覽器的「阻止所有 cookie」設定已關閉。
## 步驟 1：開啟儀表板的公用存取權
若要讓網際網路上的任何人存取您的內嵌視覺效果或儀表板，請先開啟儀表板的公開存取權。視覺效果許可是在儀表板層級決定的。若要授予內嵌視覺效果的存取權，請授予視覺效果所屬儀表板的存取權。如需詳細資訊，請參閱[授予網際網路上任何人存取 Amazon Quick Sight 儀表板的權限](share-a-dashboard-grant-access-anyone.md)。
## 步驟 2：將要嵌入視覺效果或儀表板的域放在允許清單中
若要在公有應用程式、Wiki 或入口網站中嵌入視覺效果和儀表板，請確定您內嵌它的網域位於 Amazon Quick Sight 帳戶的允許清單中。
## 步驟 3：取得內嵌程式
使用下列步驟來取得視覺效果或儀表板內嵌程式碼。
**若要取得儀表板內嵌程式碼**
1. 在 Amazon Quick Sight 中開啟已發佈的儀表板，然後選擇右上角的**共用**。然後選擇**共用儀表板**。
1. 在開啟的**共用儀表板**頁面中，選擇左上角的**複製內嵌程式碼**。
內嵌程式碼已複製到剪貼簿，類似以下項目。此範例中`quicksightdomain`的 是您用來存取 Amazon Quick Sight 帳戶的 URL。
```
```
**若要取得視覺效果內嵌程式碼**
1. 在 Amazon Quick Sight 中開啟發佈的儀表板，然後選擇您要嵌入的視覺效果。然後開啟視覺效果右上角的視覺效果選單，選擇**內嵌視覺效果**。
1. 在開啟的**內嵌視覺效果**窗格中，選擇**複製程式碼**。
內嵌程式碼已複製到剪貼簿，類似以下項目。此範例中`quicksightdomain`的 是您用來存取 Amazon Quick Sight 帳戶的 URL。
```
```
## 步驟 4：將內嵌程式碼貼到 HTML 頁面、Wiki 頁面或入口網站
使用下列程序將內嵌程式碼貼到 HTML 頁面、Wiki 頁面或入口網站。
**若要貼上內嵌程式碼**
+ 開啟您要嵌入視覺效果或儀表板的位置的 HTML 程式碼，然後將內嵌程式碼貼入其中。
下列範例展示了內嵌式儀表板的可能情況。此範例中`quicksightdomain`的 是您用來存取 Amazon Quick Sight 帳戶的 URL。
```
Example.com - Employee Portal
Current shipment stats
```
下列範例展示了內嵌式視覺效果的可能情況。此範例中`quicksightdomain`的 是您用來存取 Amazon Quick Sight 帳戶的 URL。
```
Example.com - Employee Portal
Current shipment stats
```
如果您的公開應用程式是建立在 Google Sites 上的，請在 Google Sites 上開啟網頁，然後使用內嵌小工具貼上內嵌程式碼。
當您嵌入 Google 網站時，請確定 Amazon Quick Sight 中的下列網域位於您的允許清單中：
+ `https://googleusercontent.com` (開啟子網域)
+ `https://www.gstatic.com`
+ `https://sites.google.com`
在您的應用程式中內嵌視覺或儀表板之後，任何可以存取您應用程式的使用者皆可存取內嵌的視覺效果或儀表板。若要更新與公眾共用的儀表板，請參閱 [更新公開共用的儀表板](share-a-dashboard-grant-access-anyone-update.md)。若要關閉公開共用，請參閱 [關閉公開共用設定](share-a-dashboard-grant-access-anyone-no-share.md)。
當您關閉公開共用時，網際網路上的任何人都無法存取您內嵌在公用應用程式中或透過連結共用的儀表板。下次任何人嘗試從網際網路查看此類儀表板時，他們都會收到一條訊息，指出他們沒有查看儀表板的存取權。
# 使用 Amazon Quick Sight APIs 內嵌
| |
| --- |
| 適用於：企業版 |
| |
| --- |
| 目標對象：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 儀表板
使用下列主題來了解如何使用 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 儀表板
**重要**
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：設定許可
在以下章節中，您可以了解如何為後端應用程式或 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
在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌的儀表板 URL。如果您打算內嵌 IAM 或 Amazon Quick Sight 身分類型的儀表板，請與使用者共用儀表板。
當使用者存取您的應用程式時，該應用程式代表使用者擔任 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.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 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
```
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
```
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
以下範例顯示的 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
以下範例顯示的 .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
若要擔任角色，請選擇下列其中一個 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
在下一節中，您可以了解如何使用 [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
```
Dashboard Embedding Example
```
### SDK 1.0
```
Basic Embed
```
若要讓此範例運作，請務必使用 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 儀表板
**重要**
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：設定許可
| |
| --- |
| 適用於：企業版本 |
| |
| --- |
| 目標對象：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
| |
| --- |
| 適用於：企業版本 |
| |
| --- |
| 目標對象：Amazon Quick 開發人員 |
在下一章節，您可以了解如何在您的應用程式伺服器上代表匿名訪客進行身分驗證，以及取得可內嵌的儀表板 URL。
當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，它會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。
下列範例會代表使用者執行 IAM 身分驗證。它傳遞識別符當作唯一的角色工作階段 ID。此代碼在您的應用程式伺服器上運行。
### Java
```
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 authorizedResourceArns, // DASHBOARD ARN LIST TO EMBED
final List allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
final List 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
```
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
```
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
以下範例顯示的 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
以下範例顯示的 .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
若要擔任角色，請選擇下列其中一個 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
| |
| --- |
| 適用於：企業版 |
| |
| --- |
| 目標對象：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
```
Dashboard Embedding Example
```
### SDK 1.0
```
Basic Embed
```
若要讓此範例運作，請務必使用 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
```
# 在嵌入式儀表板中啟用執行摘要
| |
| --- |
| 適用於：企業版本 |
| |
| --- |
| 目標對象：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 視覺效果
您可以使用 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 視覺效果
| |
| --- |
| 適用於：企業版 |
| |
| --- |
| 目標對象：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：設定許可
在以下章節中，您可以了解如何為後端應用程式或 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
在下一節中，您可以了解如何驗證 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
```
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 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
```
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
```
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
以下範例顯示的 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
以下範例顯示的 .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
若要擔任角色，請選擇下列其中一個 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
在下一節中，您可以了解如何使用 [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
```
Visual Embedding Example
```
### SDK 1.0
```
Visual Embedding Example
```
若要讓此範例運作，請務必使用 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 視覺效果
| |
| --- |
| 適用於：企業版本 |
| |
| --- |
| 目標對象：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：設定許可
| |
| --- |
| 適用於：企業版本 |
| |
| --- |
| 目標對象：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
| |
| --- |
| 適用於：企業版本 |
| |
| --- |
| 目標對象：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.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 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 allowedDomains, // Runtime allowed domains for embedding
final List 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
```
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
```
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
以下範例顯示的 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
以下範例顯示的 .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
若要擔任角色，請選擇下列其中一個 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
| |
| --- |
| 適用於：企業版 |
| |
| --- |
| 目標對象：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
```
Visual Embedding Example
```
### SDK 1.0
```
Visual Embedding Example
```
若要讓此範例運作，請務必使用 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 主控台的完整功能
**重要**
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：設定許可
在以下章節中，您可以了解如何為後端應用程式或 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
在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌主控台工作階段的 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.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 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
```
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
```
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
以下範例顯示的 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
以下範例顯示的 .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
若要擔任角色，請選擇下列其中一個 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
在下一節中，您可以了解如何使用 [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
```
Console Embedding Example
```
### SDK 1.0
```
QuickSight Console Embedding
```
若要讓此範例運作，請務必使用 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 功能
| |
| --- |
| 適用於：企業版 |
| |
| --- |
| 目標對象：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
| |
| --- |
| 目標對象：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 生成式問答體驗
在下列各節中，您可以找到有關如何為 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：設定許可
在以下章節中，您可以了解如何為後端應用程式或 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
在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌的 Q 主題 URL。如果您打算嵌入 IAM 或 Amazon Quick Sight 身分類型的生成式問答體驗，請與使用者共用 Q 主題。
當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，應用程式會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。
執行所述的步驟可確保 Q 主題的每個檢視器都是在 Amazon Quick Sight 中唯一佈建。它還會強制執行個別使用者設定，例如資料列層級的安全性和參數的動態預設值。標籤型資料列層級安全性可用於 Q 列的匿名使用者嵌入。
下列範例會代表使用者執行 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.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 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
**注意**
無法直接從瀏覽器呼叫嵌入式 URL 產生 API。請改為參閱 Node.JS 範例。
#### Python3
```
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
以下範例顯示的 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
以下範例顯示的 .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
若要擔任角色，請選擇下列其中一個 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
在下一章節，您可以了解如何在網站或應用程式頁面中嵌入生成式問答功能 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
```
Generative Q&A Embedding Example
```
若要讓此範例運作，請務必使用 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
```
### 選用的嵌入生成式問答功能功能
下列選用功能可在使用嵌入式 SDK 的嵌入生成式問答功能中使用。
#### 調用生成式問答搜尋列動作
+ 設定問題：此功能會將問題傳送至生成式問答功能，並立即查詢問題。
```
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 體驗
| |
| --- |
| 目標對象：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：設定許可
在以下章節中，您可以了解如何為後端應用程式或 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
在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌的 Q 主題 URL。
當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，應用程式會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。
#### Java
```
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 authorizedResourceArns, // Q TOPIC ARN LIST TO EMBED
final List allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
final List 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
**注意**
無法直接從瀏覽器呼叫嵌入式 URL 產生 API。請改為參閱 Node.JS 範例。
#### Python3
```
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
以下範例顯示的 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
以下範例顯示的 .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
若要擔任角色，請選擇下列其中一個 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
在下一章節，您可以了解如何在網站或應用程式頁面中嵌入生成式問答功能 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
```
Generative Q&A Embedding Example
```
若要讓此範例運作，請務必使用 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
```
### 選用的嵌入生成式問答功能功能
下列選用功能可在使用嵌入式 SDK 的嵌入生成式問答功能中使用。
#### 調用生成式問答搜尋列動作
+ 設定問題：此功能會將問題傳送至生成式問答功能，並立即查詢問題。
```
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 搜尋列 （傳統）
| |
| --- |
| 目標對象：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 搜尋列
| |
| --- |
| 適用於：企業版本 |
| |
| --- |
| 目標對象：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：設定許可
**注意**
內嵌的 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
**注意**
內嵌的 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
```
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 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
```
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
```
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
以下範例顯示的 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
以下範例顯示的 .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
若要擔任角色，請選擇下列其中一個 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
**注意**
內嵌的 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
```
Q Search Bar Embedding Example
```
### SDK 1.0
```
QuickSight Q Search Bar Embedding
```
若要讓此範例運作，請務必使用 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 搜尋列內嵌功能
**注意**
內嵌的 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 搜尋列動作
下列選項僅支援 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 搜尋列
| |
| --- |
| 目標對象：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：設定許可
**注意**
內嵌的 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
**注意**
內嵌的 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
```
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 authorizedResourceArns, // Q SEARCHBAR TOPIC ARN LIST TO EMBED
final List allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
final List 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
```
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
```
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
以下範例顯示的 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
以下範例顯示的 .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
若要擔任角色，請選擇下列其中一個 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
**注意**
內嵌的 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
```
Q Search Bar Embedding Example
```
### SDK 1.0
```
QuickSight Q Search Bar Embedding
```
若要讓此範例運作，請務必使用 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 搜尋列內嵌功能
**注意**
內嵌的 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 搜尋列動作
下列選項僅支援 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 操作內嵌分析
| |
| --- |
| 適用於：企業版 |
| |
| --- |
| 目標對象：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) 為所有人內嵌儀表板
**重要**
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：設定許可
**重要**
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
**重要**
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
**重要**
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。此代碼駐留在您的應用程式伺服器上。
```
Basic Embed
```
若要讓此範例運作，請務必使用 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) 為已註冊使用者內嵌儀表板
**重要**
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：設定許可
**重要**
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
**重要**
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
**重要**
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。此代碼在您的應用程式伺服器上生成。
```
Basic Embed
```
若要讓此範例運作，請務必使用 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)
**重要**
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：設定許可
**重要**
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
**重要**
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
**重要**
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。此代碼在您的應用程式伺服器上生成。
```
Basic Embed
```
若要讓此範例運作，請務必使用 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
```