Amazon Q 嵌入開發人員商業智能服務用戶指南

QuickSight Q 嵌入支援有關主題的兩種不同用例。第一種情況是要指定單一主題，並且只能透過搜尋欄查詢該主題。第二個是 QuickSight 應用程式中的標準體驗，使用者有一個主題列表，可以使用搜尋欄中的下拉列表來選擇他們想要查詢的主題。在繼續之前，請確保您知道您的用例是否需要嵌入式體驗中的一個主題或一系列主題。

將網域列入白名單

根據 QuickSight 嵌入指南，您會注意到需要在「管理 QuickSight」頁面中將應用程式的網域列入白名單。通常，這就是您需要做的全部事情，但對於 Q，我們還需要將 QuickSight 網域新增至白名單。這看起來很奇怪，但由於 Q 在幕後也使用 iframe，所以我們至少現在需要將「相同」網域列入白名單。您需要列入白名單的 QuickSight 網域取決於您所使用的區域。對於前ample，使用“us-east-1”區域嵌入，我們的 URL 列入白名單將是：

https://us-east-1.quicksight.aws.amazon.com

這 URL 其他區域也一樣，只是相應的區域部分 (us-east-1) 發生了變化。

產生新會話 URL

首先是產生會話的嵌入框架部分 URL 透過 getSessionEmbedURL API需要稍微修改一下。 QuickSight Q 會話嵌入在與標準控制台嵌入體驗不同的「入口點」上受到支援。該 API 的文檔可以是找到這裡。此 API 呼叫的入口點參數需要更改 - 新入口點取決於主題用例。對於單一主題的情況：

entry-point = /q/search/<topicId>

要在選擇器中顯示所有主題，我們將省略 topicId：

entry-point = /q/search

這應該會產生一次性經過身份驗證的 URL 這將呈現一個僅包含 QuickSight Q 搜尋欄的頁面。

使用JS SDK嵌入

隨著 URL，我們可以使用提供的 QuickSight Embedding Javascript SDK 將 Q 搜尋欄嵌入到應用程式中。首先，確保您有一個 SDK 的副本來自 QuickSight 團隊 - 請注意，因為這是預先發布的view 功能尚未發布，SDK 將與公開可用的版本不同 github上的SDK。我們希望將 SDK 中的 EmbedSession 方法與產生的會話一起使用 URL。 embedSession 函數的相關選項為（也可在 SDK 中的 types.js 中找到）：

url: url of the session or dashboard to embed container: parent html element or query selector string errorCallback: callback when error occurs loadCallback: callback when visualization data load complete className: optional className to be given to iframe element isQEmbedded: embeddable object is Q search bar flag maxHeightForQ: height for Q to resize to when it expands onQBarOpenCallback: optional callback for Q search bar open onQBarCloseCallback: optional callback for Q search bar close

這裡的兩個必要參數是 url 和容器。我們將使用 URL 從 getSessionEmbed 生成URL API 調用，對於容器而言，這取決於您的應用程式。你至少需要一個簡單的作為嵌入式 iframe 的「容器」；給這個容器一個 id 並在 SDK 參數中傳入該 id。預設會話嵌入回呼、errorCallback 和 loadCallback 的作用正如其名稱所暗示的那樣 – 如果您
當嵌入頁面載入或遇到錯誤時需要自訂行為，請在這些回呼中指定該邏輯。當 SDK 使用 Q 嵌入模式時，iframe 將具有固定高度（搜尋列本身的高度）和父 HTML 容器的 100% 寬度。這意味著搜尋欄將僅與容器一樣寬；你需要確保搜尋欄的寬度至少為 600px（無論是從 view-寬度/百分比tage 或直接指定）。為了設定 iframe 的樣式，也可以選擇指定 className 參數。

重要的：
這裡的一個關鍵標註是確保或作為容器 html 元素傳遞的元件具有“position:absolute”樣式。這使得搜尋欄能夠作為覆蓋層展開，而不是向下移動應用程式的內容。

QuickSight Q 嵌入更改

會話/儀表板嵌入和 Q 搜尋列嵌入之間存在一些關鍵區別（儘管目前 Q 嵌入僅使用會話嵌入）。對於儀表板和會話嵌入，框架通常是單一尺寸，除非根據儀表板或分析表的尺寸進行一些調整。使用 Q，最初頁面上的嵌入框架相對較小（我們只希望顯示實際的搜尋欄）。使用搜尋列時，該框架需要展開（以顯示其他下拉元素，例如視覺結果、建議等）。為了在不改變應用程式內容的情況下擴展此框架，我們只需將其設定為現有頁面上的覆蓋層，類似於當今 QuickSight 應用程式中搜尋列的功能 - 請參閱下面的螢幕截圖。

在了解了 Q 嵌入的工作原理後，讓我們來看看 QuickSight Q 特定的 SDK 參數。首先，我們需要將 isQEmbedded 設為 true。 maxHeightForQ 是一個可選參數，指定 Q 框架在頁面上可以存在的最大高度；如前所述，我們需要 iframe 及其容器來擴展頁面的內容。我們可以使用 maxHeightForQ 參數來確保框架/容器的大小調整不會超過頁面的最大高度並導致出現滾動或其他不必要的行為。如果未設置，Q 幀的大小將調整為 100vh。

最後兩個 Q 特定參數是嵌入框架調整大小時發生的回呼。預設行為是創建一個背景元素，並使用它來提供我們在上面的 QuickSight 應用程式螢幕截圖中看到的較暗的背景外觀。這是我們希望提供的「開箱即用」功能，以使嵌入 Q 盡可能簡單 - 然而，我們知道這並不適用於每個需要嵌入 Q 的應用程式。將邏輯寫入onQBarOpenCallback 和onQBarCloseCallback 即可。這也將阻止顯示預設背景。

QuickSight Q 樣式選項

我們可以使用一些樣式/裝飾選項來自訂 Q 搜尋欄的外觀。

qBarIconDisabled: option to hide the Q search bar qBarTopicNameDisabled: option to hide the Q search bar topic name themeId: option to apply Quicksight theme to Q search bar

如果您想要停用「Q」圖示（在搜尋列的左側，請使用 qBarIconDisabled 參數。類似地，若要停用主題名稱，如果您僅在嵌入模式下顯示單一主題，請使用 qBarTopicNameDisabled請注意，這些修飾自訂僅適用於嵌入單一主題的情況。
如果您想要對嵌入式 Q 欄進行主題化以使外觀與您的應用程式一致，您可以透過在 QuickSight 中建立新主題並將 themeId 傳遞給 SDK（例如amp下面）。

Examp萊斯

以下前amples 將假設 DOM 中存在一個 ID 為「q-bar-container」的容器。

使用預設背景行為嵌入（使用 q/搜尋路徑）

假設容器的頂部邊距為 75px，因此我們將使用 maxHeightForQ 參數來考慮這一點，以便 iframe 不會擴展得超過頁面允許的範圍，從而創建滾動條或其他不必要的行為。
function embedQSession(embedUrl) { var containerDiv = document.getElementById("q-bar-container"); containerDiv.innerHTML = ""; var params = { url: embedUrl, container: containerDiv, isQEmbedded: true, maxHeightForQ: "calc(100vh - 75px)", }; QuickSightEmbedding.embedSession(params);
}

禁用背景行為的嵌入（帶有 q/搜尋路徑）

對於這個前任amp我們假設容器位於頁面頂部，因此它可以毫無問題地擴展到 100%；我們不需要 maxHeightForQ。我們將使用 onQBarOpenCallback 和 onQBarCloseCallback 作為無操作函數來防止預設背景出現。

function embedQSession(embedUrl) { var containerDiv = document.getElementById("q-bar-container"); containerDiv.innerHTML = "";
var params = {
url: embedUrl, container: containerDiv,
isQEmbedded: true,
onQBarOpenCallback: () => {},
onQBarCloseCallback: () => {},
};
QuickSightEmbedding.embedSession(params);
}

嵌入自訂背景行為（帶有 q/搜尋路徑）

我們再次假設容器位於頁面頂部，因此它可以毫無問題地擴展到 100%；我們不需要 maxHeightForQ。我們將使用 onQBarOpenCallback 和 onQBarCloseCallback 作為回調，在我們的應用程式中操作一些其他背景元件（customBackdropComponent），我們希望使用它來取代預設元件。請注意，您的背景回呼可能更複雜，例如ample 只是為了簡單起見。

function onQBarOpen() {
customBackdropComponent.style.height = "100%";
}
function onQBarClose() {
customBackdropComponent.style.height = 0;
}
function embedQSession(embedUrl) {
var containerDiv = document.getElementById("q-bar-container");
containerDiv.innerHTML = "";
var params = {
url: embedUrl,
container: containerDiv,
isQEmbedded: true,
onQBarOpenCallback: () => {},
onQBarCloseCallback: () => {},
};
QuickSightEmbedding.embedSession(params);
}

使用預設背景行為嵌入（使用 q/search/topicId 路徑）

我們再次假設容器的頂部邊距為 75px，因此我們將使用 maxHeightForQ 參數來考慮這一點，以便 iframe 不會擴展得超過頁面允許的範圍，從而創建滾動條或其他不必要的行為。由於我們使用單一主題的嵌入式搜尋欄，因此我們可以使用 qBarIconDisabled 和 qBarTopicNameDisabled 自訂。這個前任ample 將為我們提供一個沒有圖示或主題名稱的搜尋欄，設定為隨時可以查詢傳入的 topicId。

函數 embedQSession(嵌入Url）{
var containerDiv = document.getElementById(“q-bar-容器”);
containerDiv.innerHTML = “”;
var 參數 = {
url：嵌入Url,
容器：containerDiv，
isQEmbedded：正確，
Q 的最大高度：「計算（100vh – 75px)”，
qBarIconDisabled：假，
qBarTopicNameDisabled：假，
};
QuickSightEmbedding.embedSession(params);
}

嵌入主題 ID

如果您沒有 QuickSight，請在 QuickSight 中建立一個新主題。開啟一項分析，或建立一個新分析。選擇左側的主題。
然後選擇您喜歡的起始主題之一，然後按一下「另存為」。如果您已有主題，則可以跳過主題建立步驟。

它將帶您進入主題編輯器頁面，為其命名，根據需要調整顏色，然後將其保存在右上角。

現在您已經有了一個主題，您需要找到該主題的 id 並將其傳遞給 SDK。在您建立的主題上選擇“編輯”。

它會再次帶你到主題編輯器頁面，但這一次，你會在 url 酒吧。在本例中，「d39c0065bf69-4b3d-927b-9dd3a241f094」是我創建的主題的 ID。

最後，將主題id作為參數傳遞給SDK，然後您將在應用程式中獲得主題Q欄。

函數 embedQSession(嵌入Url）{
var containerDiv = document.getElementById(“q-bar-容器”);
containerDiv.innerHTML = “”;
var 參數 = {
url：嵌入Url,
容器：containerDiv，
isQEmbedded：正確，
maxHeightForQ：「計算（100vh – 75 像素)「，
qBarIconDisabled：假，
qBarTopicNameDisabled：假，
主題ID： “d39c0065-bf69-4b3d-927b-9dd3a241f094”
};
QuickSightEmbedding.embedSession(params);
}

主題組件

我們想向您展示 Q bar 中的哪些元件可以進行主題化，我們將以 QuickSight Midnight 主題作為例子ample（您可以在入門主題中找到它）

故障排除

'拒絕陷害*。Quicksight.aws.amazon.com 因為祖先違反了..'錯誤

此錯誤是由於不允許在 QuickSight 應用程式的管理 QuickSight 管理頁面中列出您的網域而導致的。請務必允許列出區域 QuickSight 網域（對於 us-east-1，這是 https://us-east-1.quicksight.aws.amazon.com ，例如ample)，以及您的應用程式的網域。

成功嵌入後看不到搜尋欄

如果您能夠成功產生並存取和嵌入連結（沒有權限或其他明顯錯誤），但出現「空白」螢幕，沒有出現搜尋欄，則需要檢查一些事項。一是必須至少有一個主題與您要嵌入的使用者分享。其次，您需要確保至少有一個主題已成功創建，並且在最初建置後處於「成功」狀態。測試這一點的一個簡單方法是在 QuickSight 應用程式中使用 Q 中的主題；如果工作正常，那麼在嵌入模式下使用就好了。

搜尋欄可能不顯示的另一個原因是嵌入 iframe 所在的容器可能沒有提供足夠的寬度。如文件中所述，您需要確保搜尋欄的寬度至少為 600 像素，才能正常運作。

搜尋欄擴大但內容下移

帶有 SDK 的搜尋欄旨在擴展到頁面上任何其他內容之上。如果不是這種情況，請確保搜尋欄容器樣式為“position:absolute”，這將允許它不會向下移動頁面內容。對於前amp樂：

<div id="q-search-container" style="position: absolute; width: 100%"></div>

SDK 修訂變更日誌

V1(5/15/21)：初始自訂“Q-ready”SDK
- V1.1（5/25/21）
  - 更改 iframe 高度以固定為搜尋列本身的高度，使用者無法在 Q 模式下指定
  - 對於 Q 模式，將 iframe 寬度設定為父容器的 100%。請注意，搜尋列的寬度仍然會受到父容器大小的限制。

文件/資源

Amazon Q Embedding Developer 商業智慧服務 [pdf] 使用者指南
Q Embedding Developer 商業智慧服務、Developer 商業智慧服務、情報服務

參考

使用者手冊

先決條件

確定要顯示的主題