Amazon Q Embedding Developer Business intelligence service Giya sa Gumagamit

QuickSight session embedding framework setup gamit ang AWS account
- Workshop alang niini: https://learnquicksight.workshop.aws/en/session-embedding.html
- Siguroha nga tugutan ang listahan sa imong domain sa Manage QuickSight page

Pagdeterminar (mga) Hilisgutan nga Ipasundayag

Ang QuickSight Q nga pag-embed nagsuporta sa duha ka lainlaing mga kaso sa paggamit bahin sa mga hilisgutan. Ang una mao ang kung ang usa ka hilisgutan kinahanglan nga itakda, ug kana nga hilisgutan ra ang mahimo nga pangutana batok sa pinaagi sa search bar. Ang ikaduha mao ang standard nga kasinatian sulod sa QuickSight nga aplikasyon, diin ang usa ka user adunay listahan sa mga topiko ug makagamit ug dropdown sa search bar aron mapili ang topiko nga gusto nilang ipangutana. Sa dili pa magpadayon, siguroha nga nahibal-an nimo kung ang imong kaso sa paggamit nanginahanglan usa ka hilisgutan, o usa ka lista sa mga hilisgutan sa na-embed nga kasinatian.

Pagtugot sa Domain

Sumala sa QuickSight embedding nga mga giya, imong mamatikdan nga kinahanglan nimo nga i-allowlist ang domain sa imong aplikasyon sa `Manage QuickSight' nga panid. Kasagaran, kini ra ang kinahanglan nimong buhaton, apan sa kaso sa Q kinahanglan usab namon nga idugang ang domain sa QuickSight sa lista nga gitugotan. Morag katingad-an kini, apan tungod kay sa ilawom sa hood ang Q naggamit usab usa ka iframe, kinahanglan namon, labing menos sa karon, nga itugot ang `parehas' nga domain. Ang QuickSight nga domain nga kinahanglan nimong itugot nga listahan nagdepende sa rehiyon nga imong gigamit. Kay example, pag-embed gamit ang `us-east-1′ nga rehiyon, among URL ang allowlist mao ang:

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

Ang URL mahimong pareho alang sa ubang mga rehiyon, nga ang tagsa-tagsa nga rehiyonal nga bahin (us-east-1) nausab.

Paghimo sa bag-ong sesyon URL

Una ang bahin sa embedding framework nga nagmugna sa sesyon URL pinaagi sa getSessionEmbedURL Ang API kinahanglan nga usbon gamay. Ang QuickSight Q session embedding gisuportahan sa lahi nga `entry point' kay sa standard console embedded nga kasinatian. Ang dokumentasyon alang niini nga API mahimong makita dinhi. Kinahanglang usbon ang entry-point parameter para niining tawag sa API – ang bag-ong entry point nagdepende sa (mga) topiko sa paggamit sa kaso. Alang sa usa ka kaso nga hilisgutan:

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

Aron ipakita ang tanang mga topiko sa tigpili, atong wagtangon ang topicId:

entry-point = /q/search

Kini kinahanglan nga makamugna sa usa ka higayon nga gipamatud-an URL nga maghatag usa ka panid nga adunay QuickSight Q search bar.

Gamit ang JS SDK aron I-embed

Uban sa URL, magamit namo ang gihatag nga QuickSight Embedding Javascript SDK aron i-embed ang Q search bar sa aplikasyon. Una, siguroha nga ikaw adunay usa ka kopya sa SDK gikan sa QuickSight team - timan-i tungod kay kini usa ka preview feature ug wala pa ipagawas, ang SDK mahimong lahi nga bersyon kay sa magamit sa publiko SDK sa github. Gusto namong gamiton ang pamaagi sa EmbedSession gikan sa SDK uban sa namugna nga sesyon URL. Ang may kalabutan nga mga kapilian alang sa embedSession function mao ang (makita usab sa mga type.js sa 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

Ang duha ka gikinahanglan nga mga argumento dinhi mao url ug sudlanan. Atong gamiton ang URL namugna gikan sa getSessionEmbedURL API nga tawag, ug alang sa sudlanan kini nagdepende sa imong aplikasyon. Gusto nimo labing menos usa ka yano isip `sudlanan' alang sa gisukip nga iframe; hatagi kini nga sudlanan og id ug ipasa ang id sa mga argumento sa SDK. Ang default nga sesyon nga nag-embed sa mga callback, errorCallback ug loadCallback buhaton sumala sa gisugyot sa ngalan - kung ikaw
nanginahanglan ug kostumbre nga pamatasan kung ang naka-embed nga panid nag-load, o nakasugat og sayup, ipiho kana nga lohika sa kini nga mga callback. Kung gigamit ang Q embedded mode sa SDK, ang iframe mahimong usa ka pirmi nga gitas-on (ang gitas-on sa search bar mismo) ug 100% ang gilapdon sa sulud sa ginikanan nga HTML. Kini nagpasabot nga ang search bar mahimong sama ka lapad sa sudlanan; gusto nimong sigurohon nga ang search bar adunay labing menos 600px nga gilapdon (kon gihubad gikan sa view-kalapad/porsiyentotage o direkta nga gi-assign). Alang sa pag-istilo sa iframe, ang parameter sa className mahimong mapili usab.

IMPORTANTE:
Usa ka mahinungdanong callout dinhi mao ang pagsiguro nga ang o component nga imong gipasa ingon nga sudlanan html elemento adunay usa ka estilo sa `posisyon: hingpit'. Mao kini ang nagtugot sa search bar nga molapad isip usa ka overlay imbes nga ibalhin ang mga sulod sa imong app ngadto sa ubos.

Mga Kausaban sa Pag-embed sa QuickSight Q

Adunay pipila ka mahinungdanong kalainan tali sa session/dashboard embedding ug Q search bar embedding (bisan tuod sa pagkakaron ang Q embedding naggamit lang sa session embedding). Uban sa dashboard ug session nga pag-embed, ang frame kasagaran usa ka gidak-on, nga nagdili sa pipila nga pag-resize base sa gidak-on sa usa ka dashboard o analysis sheet. Uban sa Q, sa sinugdan gamay ra ang gi-embed nga frame sa imong panid (gusto lang namo nga makita ang aktwal nga search bar). Kung gigamit ang search bar, kini nga frame kinahanglan nga molapad (aron ipakita ang dugang nga mga elemento sa dropdown sama sa biswal nga resulta, mga sugyot, ug uban pa). Aron mapalapad kini nga frame nga dili ibalhin ang mga sulud sa imong aplikasyon, gipahimutang namon kini ingon usa ka overlay sa naglungtad nga panid, parehas sa kung giunsa ang paggana sa search bar sa aplikasyon sa QuickSight karon - tan-awa ang mga screenshot sa ubos.

Uban sa gamay kung giunsa ang pag-embed sa Q sa hunahuna, atong tan-awon ang QuickSight Q nga piho nga mga parameter sa SDK. Una, kinahanglan nato ang isQEmbedded aron mabutang nga tinuod. Ang maxHeightForQ usa ka opsyonal nga argumento nga nagtino sa kinadak-an nga ang Q frame mahimong anaa sa imong panid; sama sa nahisgotan na, kinahanglan namo ang iframe ug kini sudlanan aron mapalapad ang mga sulod sa panid. Mahimo namong gamiton ang argumento sa maxHeightForQ aron maseguro nga ang frame/container dili mausab ang gidak-on lapas sa max nga gitas-on sa imong panid ug mopatunghag scroll o uban pang dili gusto nga kinaiya. Kung dili itakda, ang Q frame magbag-o sa 100vh.

Ang katapusan nga duha ka piho nga mga parameter sa Q mao ang mga callback nga mahitabo kung ang gi-embed nga frame nagbag-o. Ang default nga pamatasan mao ang paghimo usa ka elemento sa backdrop, ug gamita kini aron mahatagan ang labi ka itom nga hitsura sa background nga makita namon sa mga screenshot sa taas gikan sa aplikasyon sa QuickSight. Kini ang `out of the box' functionality nga gusto namong ihatag aron ang pag-embed sa Q ingon kadali kutob sa mahimo – bisan pa, nahibal-an namon nga dili kini magamit sa matag aplikasyon nga kinahanglan i-embed ang Q. Kung kinahanglan nimo i-override kini nga kinaiya, isulat lang ang logic sa onQBarOpenCallback ug onQBarCloseCallback. Kini magpugong sa default nga backdrop gikan sa pagpakita usab.

Mga Opsyon sa Pag-istilo sa QuickSight Q

Adunay pipila ka mga kapilian sa pag-istilo/kosmetiko nga magamit namo aron ipasibo ang dagway sa Q search bar.

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

Kung gusto nimong i-disable ang icon nga `Q' (sa wala nga bahin sa search bar, gamita ang qBarIconDisabled parameter. Sa susama, aron ma-disable ang ngalan sa topiko, kung nagpakita ka lang ug usa ka hilisgutan sa naka-embed nga mode, gamita ang qBarTopicNameDisabled Parametro. Timan-i nga kini nga mga kosmetiko nga pagpahiangay magamit ra alang sa kaso kung nag-embed ka usa ka hilisgutan.
Kung gusto nimo nga tema ang naka-embed nga Q bar aron mahimo ang hitsura nga nahiuyon sa imong aplikasyon, mahimo nimo kini pinaagi sa paghimo og bag-ong tema sa QuickSight ug ipasa ang themeId sa SDK (exampsa ubos).

Examples

Ang mosunod nga examples maghunahuna nga adunay sudlanan nga naa sa DOM nga adunay id nga `q-bar-container'.

Pag-embed sa Default nga Backdrop Behavior (uban ang q/search path)

Ibutang nato nga ang sudlanan adunay margin top nga 75px, mao nga atong tagdon kana gamit ang maxHeightForQ parameter, aron ang iframe dili molapad nga mas dako kay sa gitugot sa panid, paghimo og scroll bar o uban pang dili gusto nga kinaiya.
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);
}

Pag-embed Uban sa Disabled Backdrop Behavior (uban ang q/search path)

Para ani nga exampatong isipon nga ang sudlanan anaa sa ibabaw sa panid aron kini molapad ngadto sa 100% nga walay isyu; dili namo kinahanglan ang maxHeightForQ. Gamiton namo ang onQBarOpenCallback ug ang onQBarCloseCallback isip no-op functions aron mapugngan ang default backdrop gikan sa pagpakita.

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

Pag-embed sa Custom nga Backdrop Behavior (uban ang q/search path)

Atong isipon pag-usab nga ang sudlanan anaa sa ibabaw sa panid aron kini molapad ngadto sa 100% nga walay isyu; dili namo kinahanglan ang maxHeightForQ. Gamiton namo ang onQBarOpenCallback ug ang onQBarCloseCallback isip mga callback nga nagmaniobra sa ubang bahin sa backdrop (customBackdropComponent) sa among aplikasyon nga gusto namong gamiton puli sa default. Timan-i nga ang imong backdrop callback mahimong mas komplikado, kini nga example kay para lang kay simple.

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

Pag-embed sa Default nga Backdrop Behavior (uban ang q/search/topicId path)

Atong hunahunaon pag-usab nga ang sudlanan adunay margin ibabaw nga 75px, mao nga atong tagdon kana gamit ang maxHeightForQ parameter, aron ang iframe dili molapad nga mas dako kay sa gitugot sa panid, paghimo og scroll bar o uban pang dili gusto nga kinaiya. Tungod kay gigamit namo ang gi-embed nga search bar nga adunay usa ka hilisgutan, mahimo namong gamiton ang qBarIconDisabled ug qBarTopicNameDisabled customizations. Kini nga exampHatagan mi kami ug search bar nga walay icon o ngalan sa topiko, andam nga mangutana kung asa nga topicId ang gipasa.

function embedQSession(embedUrl) {
var containerDiv = document.getElementById(“q-bar-container”);
containerDiv.innerHTML = “”;
var params = {
url: apilUrl,
sudlanan: containerDiv,
isQEmbedded: tinuod,
maxHeightForQ: “calc(100vh – 75px)",
qBarIconDisabled: bakak,
qBarTopicNameDisabled: bakak,
};
QuickSightEmbedding.embedSession(params);
}

Pag-embed sa Theme Id

Paghimo usa ka bag-ong tema sa sulod sa QuickSight kung wala ka. Ablihi ang usa ka pagtuki, o paghimo og bag-o. Pilia ang Mga Tema sa wala.
Ug unya pilia ang usa sa tema sa pagsugod nga gusto nimo unya i-klik ang "Save as". Kung aduna ka'y tema, mahimo nimong laktawan ang lakang sa paghimo sa tema.

Dad-on ka sa panid sa editor sa tema, hatagan kini usa ka ngalan, i-adjust ang kolor kung gusto nimo dayon i-save kini sa taas nga tuo.

Karon nga ikaw adunay usa ka tema, kinahanglan nimo pangitaon ang id sa kana nga tema ug ipasa kini sa SDK. Pilia ang "Edit" sa tema nga imong gibuhat.

Dad-on ka na usab sa panid sa editor sa tema, apan niining higayona, makit-an nimo ang theme id didto sa url bar. Niini nga kaso ang "d39c0065bf69-4b3d-927b-9dd3a241f094" mao ang id sa usa ka tema nga akong gibuhat.

Katapusan, imong gipasa ang theme id isip parameter sa SDK, unya makakuha ka ug themed Q bar sa imong app.

function embedQSession(embedUrl) {
var containerDiv = document.getElementById(“q-bar-container”);
containerDiv.innerHTML = “”;
var params = {
url: apilUrl,
sudlanan: containerDiv,
isQEmbedded: tinuod,
maxHeightForQ: “calc(100vh – 75px)“,
qBarIconDisabled: bakak,
qBarTopicNameDisabled: bakak,
themeId: “d39c0065-bf69-4b3d-927b-9dd3a241f094”
};
QuickSightEmbedding.embedSession(params);
}

Magamit nga Component

Gusto namong ipakita kanimo kung unsang mga sangkap sa sulod sa Q bar ang mahimong tema, ug among kuhaon ang QuickSight Midnight nga tema isip example (makita nimo kini sa mga tema sa pagsugod)

Pag-troubleshoot

'Nagdumili sa pag-frame *.quicksight.aws.amazon.com tungod kay ang usa ka katigulangan naglapas..' Sayop

Kini nga sayup tungod sa dili pagtugot sa paglista sa imong domain sa pagdumala sa QuickSight admin nga panid sa QuickSight nga aplikasyon. Siguruha nga tugutan ang paglista sa parehas nga rehiyon sa QuickSight domain (alang sa us-east-1, kini https://us-east-1.quicksight.aws.amazon.com , alang sa example), ingon man ang domain sa imong aplikasyon.

Dili Makita ang Search Bar Human sa Malampuson nga Pag-embed

Kung malamposon nimo ang paghimo ug pag-access ug pag-embed sa link (nga wala’y pagtugot o uban pang klaro nga sayup), apan pagkuha usa ka `blangko' nga screen nga wala’y makita nga search bar, adunay pipila ka mga butang nga susihon. Ang usa mao nga kinahanglan adunay labing menos usa ka hilisgutan nga gipaambit sa user nga imong gi-embed. Ikaduha, gusto nimong masiguro nga adunay labing menos usa ka hilisgutan nga malampuson nga nahimo ug sa usa ka `malampuson' nga kahimtang pagkahuman sa una nga pagtukod. Usa ka sayon nga paagi sa pagsulay niini mao ang paggamit lang sa hilisgutan sa Q sa QuickSight aplikasyon; kung kini nagtrabaho sa normal, kini maayo nga gamiton sa embedded mode.

Ang laing rason nga ang search bar mahimong dili makita mao nga ang sudlanan nga gisudlan sa iframe mahimong dili makahatag og igo nga gilapdon. Ingon nga gitawag sa dokumentasyon, gusto nimong sigurohon nga ang search bar gihatagan labing menos 600px nga gilapdon aron kini molihok nga normal.

Ang Search Bar Naglapad Apan Gibalhin ang Content

Ang search bar nga adunay SDK gidesinyo sa pagpalapad sa ibabaw sa bisan unsang dugang nga sulod sa panid. Kung dili ingon niini ang kahimtang, palihug siguroha ang sulud sa search bar gi-istilo nga adunay `posisyon: absolute', nga magtugot niini nga dili ibalhin ang sulod sa panid paubos. Kay example:

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

SDK Revision Change Log

V1(5/15/21): Inisyal nga custom nga `Q-ready' SDK
- V1.1 (5/25/21)
  - Usba ang gitas-on sa iframe aron ma-fix sa gitas-on sa search bar mismo, dili matino sa user sa Q mode
  - Ibutang ang gilapdon sa iframe ngadto sa 100% sa sudlanan sa ginikanan para sa Q mode. Timan-i nga ang gilapdon sa search bar mahimo gihapon nga limitado sa gidak-on sa sudlanan sa ginikanan.

Mga Dokumento / Mga Kapanguhaan

Amazon Q Embedding Developer Business intelligence nga serbisyo [pdf] Giya sa Gumagamit
Q Embedding Developer Business intelligence service, Developer Business intelligence service, intelligence service

Mga pakisayran

Manwal sa Gumagamit

Mga kinahanglanon