Amazon Q Embedding Developer Serviziu di Business Intelligence

Cuntenuti ammuccià
1 Prerequisites
2 Determinazione di u tema (s) per vede
3 Dominiu di Allowlisting
4 Generazione di a nova sessione URL
5 Utilizà u JS SDK per Incrustà
6 QuickSight Q Incrustazione Cambiamenti
7 Opzioni di stile QuickSight Q
8 Examples
9 Componente tematicu
10 Risoluzione di prublemi
11 SDK Revision Change Log
12 Documenti / Risorse
12.1 Referenze
13 Posti cunnessi

Prerequisites

  • Contu AWS cù QuickSight Q attivatu
  • Almenu un Tema cunfiguratu cù QuickSight Q (è l'ID di u tema di quellu tema)
  • Configurazione di framework di incrustazione di sessione QuickSight cù un contu AWS

Determinazione di u tema (s) per vede

L'incrustazione di QuickSight Q supporta dui casi d'usu diffirenti in quantu à i temi. U primu hè quandu un unicu tema deve esse specificatu, è solu quellu tema pò esse interrugatu cù a barra di ricerca. U sicondu hè l'esperienza standard in l'applicazione QuickSight, induve un utilizatore hà una lista di temi è ponu utilizà un menu dropdown in a barra di ricerca per selezziunà u tema chì vulia dumandà. Prima di prucede, assicuratevi di sapè s'ellu u vostru casu d'usu richiede un tema, o una lista di temi in l'esperienza integrata.

Dominiu di Allowlisting

Sicondu i guide d'incrustazione di QuickSight, noterete chì avete bisognu di elencu u duminiu di a vostra applicazione in a pagina "Gestisce QuickSight". Normalmente, questu hè tuttu ciò chì deve fà, ma in u casu di Q, avemu bisognu di aghjunghje u duminiu QuickSight à a lista di permessi. Questu pare stranu, ma postu chì sottu u cappucciu Q hè ancu utilizendu un iframe, avemu bisognu, almenu per ora, di permette a lista di u "stessu" duminiu. U duminiu QuickSight chì avete bisognu di permette a lista dipende da a regione chì site aduprate. Per example, embedding usendu a regione `us-east-1′, u nostru URL to allowlist seria:

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

U URL seria u listessu per l'altri rigioni, cù a parte regiunale rispettiva (us-east-1) cambiata.

Generazione di a nova sessione URL

Prima a parte di u quadru di incrustazione chì genera a sessione URL via u getSessionEmbedURL L'API deve esse ligeramente mudificate. L'incrustazione di sessione QuickSight Q hè supportata in un "puntu di entrata" sfarente da l'esperienza integrata di cunsola standard. A documentazione per questa API pò esse trovu quì. U paràmetru di u puntu di ingressu per questa chjama API duverà esse cambiatu - u novu puntu di ingressu dipende da u casu d'usu di u tema. Per u casu unicu tematicu:

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

Per vede tutti i temi in u selettore, omettemu u topicId:

entry-point = /q/search

Questu deve generà l'autentificazione una volta URL chì rende una pagina cù solu a barra di ricerca QuickSight Q.

Utilizà u JS SDK per Incrustà

Cù u URL, Pudemu aduprà u QuickSight Embedding Javascript SDK furnitu per incrustà a barra di ricerca Q in l'applicazione. Prima, assicuratevi di avè un copia di u SDK da a squadra QuickSight - nota postu chì questu hè un preview funzione è ùn hè micca liberatu ancu, u SDK serà una versione sfarente di quella dispunibule publicamente SDK nantu à github. Vulemu aduprà u metudu EmbedSession da u SDK cù a sessione generata URL. L'opzioni pertinenti per a funzione embedSession sò (trovate ancu in types.js in u SDK):

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

I dui argumenti necessarii sò quì url è cuntainer. Avemu aduprà u URL generatu da u getSessionEmbedURL Chjama API, è per u containeru questu dipende da a vostra applicazione. Vulete almenu un simplice cum'è u "container" per l'iframe integratu; dà stu containeru un id è trasmette l'id in l'argumenti SDK. A sessione predeterminata chì incorpora callbacks, errorCallback è loadCallback facenu cum'è u nome puderia suggerisce - se
bisognu di cumpurtamentu persunalizatu quandu a pagina incrustata carica, o scontra un errore, specificate quella logica in questi callbacks. Quandu si usa u modu Q incrustatu cù u SDK, l'iframe serà una altezza fissa (l'altezza di a barra di ricerca stessu) è 100% larghezza di u cuntinuu HTML parent. Questu significa chì a barra di ricerca serà solu larga quant'è u cuntinuu; vi vulete assicurà chì a barra di ricerca hà almenu 600px di larghezza (sia traduttu da view-larghezza / per centutage o direttamente attribuiti). Per u stilu di l'iframe, u paràmetru className pò esse specificatu ancu.

IMPORTANTE:
Una chjave chjave quì hè di assicurà chì u o cumpunente chì passate cum'è l'elementu html di u containeru hà un stilu di "posizione: assolutu". Questu hè ciò chì permette a barra di ricerca per espansione cum'è una superposizione invece di trasfurmà u cuntenutu di a vostra app.

QuickSight Q Incrustazione Cambiamenti

Ci hè uni pochi di differenze chjave trà l'incrustazione di sessione / dashboard è l'incrustazione di a barra di ricerca Q (ancu se l'incrustazione Q attualmente utilizza solu l'incrustazione di sessione). Cù l'incrustazione di u dashboard è di a sessione, u quadru hè in generale di una sola dimensione, salvu qualchì ridimensionamentu basatu annantu à a dimensione di un dashboard o foglia di analisi. Cù Q, inizialmente u quadru incrustatu nantu à a vostra pagina hè relativamente chjuca (vulemu solu a barra di ricerca attuale per vede). Quandu a barra di ricerca hè aduprata, stu quadru deve esse espansione (per mustrà elementi dropdown supplementari cum'è u risultatu visuale, suggerimenti, etc.). Per espansione stu quadru senza trasfurmà u cuntenutu di a vostra applicazione, l'avemu ghjustu cum'è una superposizione nantu à a pagina esistente, simile à cumu funziona a barra di ricerca in l'applicazione QuickSight oghje - vede screenshots sottu.

Cù un pocu nantu à u funziunamentu di l'incrustazione di Q in mente, fighjemu i paràmetri specifici di QuickSight Q SDK. Prima, avemu bisognu di isQEmbedded per esse stabilitu cum'è veru. maxHeightForQ hè un argumentu opcional chì specifica u più grande chì u quadru Q pò esse in a vostra pagina; cum'è menzionatu prima, avemu bisognu di l'iframe è u so containeru per espansione nantu à u cuntenutu di a pagina. Pudemu aduprà l'argumentu maxHeightForQ per assicurà chì u quadru / cuntainer ùn si ridimensiona più di l'altezza massima di a vostra pagina è pruvucarà un scroll à apparizione o un altru cumpurtamentu indesideratu. Se ùn hè micca stabilitu, u quadru Q ridimensionarà à 100vh.

L'ultimi dui parametri specifichi di Q sò callbacks chì succedenu quandu u quadru incrustatu resizes. U cumpurtamentu predeterminatu hè di creà un elementu di sfondate, è aduprà questu per dà l'aspettu più scuru di u fondu chì vedemu in i screenshots sopra da l'applicazione QuickSight. Questa hè a funziunalità "fora di a scatula" chì vulemu furnisce per fà l'incrustazione di Q u più faciule pussibule - in ogni modu, sapemu chì questu ùn funziona micca per ogni applicazione chì Q deve esse incrustata. annullà stu cumpurtamentu, simpricimenti scrivite a logica in onQBarOpenCallback è onQBarCloseCallback. Questu impediscerà chì u sfondate predeterminatu si prisenta ancu.

Opzioni di stile QuickSight Q

Ci hè uni pochi d'opzioni di stile / cusmetichi chì pudemu usà per persunalizà l'apparenza di a barra di ricerca 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

Se vulete disattivà l'icona "Q" (in u latu di a manca di a barra di ricerca, utilizate u paràmetru qBarIconDisabled. In listessu modu, per disattivà u nome di u tema, sè vo site solu un tema singulari in modu incrustatu, utilizate u qBarTopicNameDisabled. Nota chì queste persunalizazione cusmetichi sò dispunibuli solu per u casu quandu site incrustendu un solu tema.
Se vulete tematizà a barra Q incrustata per fà l'apparenza coherente cù a vostra applicazione, pudete fà cusì creendu un novu tema in QuickSight è passà u tema ID à SDK (es.ample sottu).

Examples

I seguenti exampLes assumera qu'il y ait un récipient présent dans DOM avec l'id `q-bar-container'.

Incrustazione cù u cumportamentu di u fondu predeterminatu (cù q / percorsu di ricerca)

Assumimu chì u cuntinuu hà un margine superiore di 75px, cusì cuntaremu per questu utilizendu u paràmetru maxHeightForQ, perchè l'iframe ùn si espansione più grande di a pagina permette, creendu una barra di scorrimentu o un altru cumpurtamentu indesevule.
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);
}

Incrustazione cù u cumpurtamentu di u fondu disattivatu (cù q / percorsu di ricerca)

Per questu example assumeremu chì u cuntinuu hè in cima di a pagina per pudè espansione à 100% senza prublema; ùn avemu micca bisognu di u maxHeightForQ. Useremu l'onQBarOpenCallback è l'onQBarCloseCallback cum'è funzioni no-op per impediscenu l'apparizione di u fondu predeterminatu.

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

Incrustazione cù u cumportamentu di u fondu persunalizatu (cù q / percorsu di ricerca)

Assumiremu dinò chì u cuntinuu hè in cima di a pagina per pudè espansione à 100% senza prublema; ùn avemu micca bisognu di u maxHeightForQ. Useremu l'onQBarOpenCallback è l'onQBarCloseCallback cum'è callbacks chì manipulanu qualchì altru cumpunente di sfondate (customBackdropComponent) in a nostra applicazione chì vulemu aduprà in u locu di u predeterminatu. Nota chì i vostri callbacks di sfondate puderanu esse più cumplessi, questu example hè solu per simplicità.

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

Incrustazione cù u cumportamentu di u fondu predeterminatu (cù u percorsu q/search/topicId)

Assumiremu di novu chì u cuntinuu hà un margine superiore di 75px, cusì cuntaremu per quessa utilizendu u paràmetru maxHeightForQ, in modu chì l'iframe ùn si espansione più grande chì a pagina permette, creendu una barra di scorrimentu o un altru cumpurtamentu indesevule. Siccomu usemu a barra di ricerca incrustata cù un solu tema, pudemu usà e customizazioni qBarIconDisabled è qBarTopicNameDisabled. Questu example ci darà una barra di ricerca senza icona o nome di u tema, stabilitu per esse prontu à interrogà nantu à qualunque topicId hè passatu.

funzione embedQSession (incrustàUrl) {
var containerDiv = document.getElementById("q-bar-container");
containerDiv.innerHTML = "";
var params = {
url: incrustàUrl,
container: containerDiv,
isQEmbedded: veru,
maxHeightForQ: "calc (100vh - 75px)",
qBarIconDisabled: false,
qBarTopicNameDisabled: false,
};
QuickSightEmbedding.embedSession (params);
}

Incrustà cù l'ID di u tema

Crea un novu tema in QuickSight se ùn ne avete micca. Aprite una analisi, o creanu una nova. Sceglite Temi à manca.
E poi sceglite unu di i temi di partenza chì preferite dopu cliccate "Salvà cum'è". Sè avete digià un tema, pudete saltà u passu di creazione di u tema.

Vi purterà à a pagina di l'editore di u tema, dà un nome, aghjustate u culore cum'è ti piace, dopu salvallu in cima à diritta.

Avà chì avete un tema, avete bisognu di truvà l'id di quellu tema è passà à SDK. Sceglite "Edit" nantu à u tema chì avete creatu.

Vi purterà di novu à a pagina di l'editore di tema, ma sta volta, truverete l'id di u tema in u url bar. In questu casu "d39c0065bf69-4b3d-927b-9dd3a241f094" hè l'id di un tema chì aghju creatu.

Infine, passate l'ID di u tema cum'è un paràmetru à u SDK, allora uttene una barra Q tematica in a vostra app.

funzione embedQSession (incrustàUrl) {
var containerDiv = document.getElementById("q-bar-container");
containerDiv.innerHTML = "";
var params = {
url: incrustàUrl,
container: containerDiv,
isQEmbedded: veru,
maxHeightForQ: "calc(100vh - 75px)",
qBarIconDisabled: false,
qBarTopicNameDisabled: false,
themeId: “d39c0065-bf69-4b3d-927b-9dd3a241f094”
};
QuickSightEmbedding.embedSession (params);
}

Componente tematicu

Vulemu dimustrà quali cumpunenti in Q bar ponu esse tematichi, è pigliaremu u tema QuickSight Midnight cum'è ex.ample (pudete truvà in i temi di partenza)

Risoluzione di prublemi

'Rifiutatu di quadru *.quicksight.aws.amazon.com perchè un antenatu viola..' Errore

Stu errore hè causatu da ùn permette micca di listinu u vostru duminiu in a pagina di gestione QuickSight admin in l'applicazione QuickSight. Assicuratevi di permette a lista di u duminiu QuickSight regiunale (per us-east-1, questu hè https://us-east-1.quicksight.aws.amazon.com , per esample), è ancu u duminiu di a vostra applicazione.

Ùn pò micca vede a barra di ricerca dopu l'incrustazione successu

Se pudete generà bè è accede è incrustà u ligame (senza permessi o altri errori evidenti), ma uttene una schermu "biancu" senza alcuna barra di ricerca chì appare, ci sò parechje cose da verificà. Unu hè chì ci deve esse almenu un tema spartutu cù l'utilizatore chì site incrustendu. Siconda, vi vulete assicurà chì ci hè almenu un tema chì hè creatu bè è in un statu "successu" dopu à custruì inizialmente. Un modu faciule per pruvà questu hè solu aduprà u tema in Q in l'applicazione QuickSight; s'ellu funziona nurmalmente, hè bonu per aduprà in modu incrustatu.

Un altru mutivu chì a barra di ricerca ùn pò micca esse cumparisce hè chì u cuntinuu in cui si trova l'iframe d'incrustazione ùn pò micca dà abbastanza larghezza. Cum'è chjamatu in a documentazione, vi vulete assicurà chì a barra di ricerca hè datu almenu 600px di larghezza per u funziunamentu nurmale.

A barra di ricerca si espande ma sposta u cuntenutu

A barra di ricerca cù u SDK hè stata pensata per espansione sopra à qualsiasi cuntenutu supplementu in a pagina. Se questu ùn hè micca u casu, assicuratevi chì u cuntinuu di a barra di ricerca hè stilatu cù una "posizione: assoluta", chì permetterà micca di trasfurmà u cuntenutu di a pagina. Per exampLe:

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

SDK Revision Change Log

  • V1 (5/15/21): SDK persunalizatu iniziale "Q-ready".
    • V1.1 (5/25/21)
      • Cambia l'altezza di iframe per esse fissata à l'altezza di a barra di ricerca stessu, l'utilizatore ùn pò micca specificà in modu Q
      • Definite a larghezza di iframe à 100% di u containeru parent per u modu Q. Innota chì a larghezza di a barra di ricerca pò ancu esse limitata da a dimensione di u cuntinuu parent.

Documenti / Risorse

Amazon Q Embedding Developer Serviziu di Business Intelligence [pdfGuida di l'utente
Q Embedding Developer Business intelligence service, Developer Business intelligence service, service intelligence

Referenze

Posti cunnessi

Lascia un cumentu

U vostru indirizzu email ùn serà micca publicatu. I campi obbligatori sò marcati *