Amazon Q Embedding Developer viðskiptagreindarþjónusta
Forkröfur
- AWS reikningur með QuickSight Q virkt
- Að minnsta kosti eitt efni sett upp með QuickSight Q (og efnisauðkenni þess efnis)
- QuickSight fundur innfelldur rammauppsetning með AWS reikningi
- Vinnustofa fyrir þetta: https://learnquicksight.workshop.aws/en/session-embedding.html
- Vertu viss um að leyfa skrá lénið þitt á síðunni Stjórna QuickSight
Ákvörðun efnis til að sýna
QuickSight Q innfelling styður tvö mismunandi notkunartilvik varðandi efni. Það fyrsta er þegar tilgreina á eitt efni og aðeins er hægt að spyrjast fyrir um það efni í gegnum leitarstikuna. Annað er staðlað reynsla innan QuickSight forritsins, þar sem notandi hefur lista yfir efni og getur notað fellivalmynd á leitarstikunni til að velja efni sem þeir vilja spyrjast fyrir um. Áður en þú heldur áfram skaltu ganga úr skugga um að þú vitir hvort notkunartilvikið þitt krefst eins efnis eða lista yfir efni í innbyggðu upplifuninni.
Leyfir lén
Samkvæmt QuickSight innfellingarleiðbeiningunum muntu taka eftir því að þú þarft að leyfa lista yfir lén forritsins þíns á síðunni `Stjórna QuickSight'. Venjulega er þetta allt sem þú þarft að gera, en þegar um Q er að ræða þurfum við líka að bæta QuickSight léninu við leyfislistann. Þetta virðist skrítið, en þar sem Q notar líka iframe undir hettunni, þurfum við, að minnsta kosti í bili, að leyfa lista yfir „sama“ lénið. QuickSight lénið sem þú þarft á leyfislista er háð svæðinu sem þú notar. Til dæmisample, embed in með því að nota `us-east-1′ svæðinu, okkar URL á leyfislista væri:
https://us-east-1.quicksight.aws.amazon.com
The URL væri það sama fyrir önnur svæði, með viðkomandi svæðishluta (us-east-1) breytt.
Að búa til nýja lotuna URL
Fyrst sá hluti innfellingarrammans sem býr til lotuna URL í gegnum getSessionEmbedURL API þarf að breyta örlítið. QuickSight Q lotuinnfelling er studd á öðrum „inngangsstað“ en hefðbundin innbyggð upplifun á vélinni. Skjöl fyrir þetta API geta verið finna hér. Aðgangspunktsfæribreytunni fyrir þetta API símtal þarf að breyta - nýi inngangspunkturinn er háður notkunartilvikum efnis. Fyrir einstætt mál:
entry-point = /q/search/<topicId>
Til að sýna öll efni í veljarann sleppum við topicId:
entry-point = /q/search
Þetta ætti að búa til einu sinni sannvottaða URL sem mun birta síðu með aðeins QuickSight Q leitarstikunni.
Að nota JS SDK til að fella inn
Með URL, við getum notað QuickSight Embedding Javascript SDK til að fella Q leitarstikuna inn í forritið. Fyrst skaltu ganga úr skugga um að þú hafir a afrit af SDK frá QuickSight teyminu - athugið þar sem þetta er forview lögun og er ekki gefin út ennþá, SDK verður önnur útgáfa en sú sem er aðgengileg almenningi SDK á github. Við viljum nota EmbedSession aðferðina frá SDK með myndaðri lotunni URL. Viðeigandi valkostir fyrir embedSession aðgerðina eru (einnig að finna í types.js í 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
Tvö nauðsynleg rök hér eru url og ílát. Við munum nota URL búið til úr getSessionEmbedURL API kalla, og fyrir gáminn er þetta háð forritinu þínu. Þú vilt að minnsta kosti einfalt sem 'ílát' fyrir innbyggða iframe; gefðu þessum íláti auðkenni og sendu inn auðkennið í SDK rökunum. Sjálfgefin lota sem fellir inn svarhringingar, errorCallback og loadCallback gera eins og nafnið gæti gefið til kynna - ef þú
þarf sérsniðna hegðun þegar innbyggða síðan hleðst, eða lendir í villu, tilgreindu þá rökfræði í þessum svarhringingum. Þegar Q embed in mode er notað með SDK, mun iframe vera föst hæð (hæð leitarstikunnar sjálfrar) og 100% breidd móður HTML gámsins. Þetta þýðir að leitarstikan verður aðeins eins breiður og ílátið; þú þarft að ganga úr skugga um að leitarstikan hafi að minnsta kosti 600px breidd (hvort sem hún er þýdd frá view-breidd/prósentatage eða beint úthlutað). Til að stilla iframe er einnig hægt að tilgreina className færibreytuna.
MIKILVÆGT:
Lykilorð hér er að ganga úr skugga um að eða hluti sem þú ert að senda þar sem html-ílátið í gámum hefur stíl sem er `position: absolute'. Þetta er það sem gerir leitarstikunni kleift að stækka sem yfirlag í stað þess að færa innihald appsins niður.
QuickSight Q Innfellingarbreytingar
Það eru nokkur lykilmunur á innfellingu lotu/mælaborðs og innfellingu á Q leitarstiku (þótt Q-innfelling nýtir einfaldlega lotuinnfelling). Með mælaborði og innfellingu setu er ramminn almennt í einni stærð, án þess að breyta stærð miðað við stærð mælaborðs eða greiningarblaðs. Með Q, upphaflega er innfelldi ramminn á síðunni þinni tiltölulega lítill (við viljum aðeins að raunverulegur leitarstikan birtist). Þegar leitarstikan er notuð þarf þessi rammi að stækka (til að sýna fleiri fellilista eins og sjónræna niðurstöðu, tillögur osfrv.). Til að stækka þennan ramma án þess að breyta innihaldi forritsins þíns, settum við það bara sem yfirlag yfir núverandi síðu, svipað og hvernig leitarstikan virkar í QuickSight forritinu í dag - sjá skjámyndir hér að neðan.
Með smá um hvernig Q innfelling virkar í huga skulum við skoða QuickSight Q sérstakar SDK færibreytur. Í fyrsta lagi þurfum við isQEmbedded til að vera stillt sem satt. maxHeightForQ er valfrjáls rök sem tilgreinir þann stærsta sem Q ramminn getur verið á síðunni þinni; eins og áður hefur komið fram, þurfum við iframe og ílát hans til að stækka yfir innihald síðunnar. Við getum notað maxHeightForQ rökin til að tryggja að ramminn/gámurinn breyti ekki stærð fram yfir hámarkshæð síðunnar þinnar og veldur því að flett birtist eða önnur óæskileg hegðun. Ef það er ekki stillt mun Q ramminn breyta stærð í 100vh.
Síðustu tvær Q-sértæku færibreyturnar eru afturköllun sem eiga sér stað þegar innbyggði ramminn breytir stærð. Sjálfgefin hegðun er að búa til bakgrunnsþátt og nota þetta til að gefa dekkri bakgrunnsútlit sem við sjáum á ofangreindum skjámyndum frá QuickSight forritinu. Þetta er „út af kassanum“ virkni sem við viljum bjóða upp á til að gera innfellingu Q eins auðvelt og mögulegt er – hins vegar vitum við að þetta mun ekki virka fyrir öll forrit sem Q þarf að fella inn í. Ef þú þarft að hnekkja þessari hegðun, skrifaðu einfaldlega rökfræðina í onQBarOpenCallback og onQBarCloseCallback. Þetta kemur í veg fyrir að sjálfgefna bakgrunnurinn birtist líka.
QuickSight Q stílvalkostir
Það eru nokkrir stíl-/snyrtivöruvalkostir sem við getum notað til að sérsníða útlit Q leitarstikunnar.
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
Ef þú vilt slökkva á "Q" tákninu (vinstra megin á leitarstikunni, notaðu qBarIconDisabled færibreytuna. Á sama hátt, til að slökkva á efnisheitinu, ef þú ert aðeins að sýna eintölu efni í innbyggðri stillingu, notaðu qBarTopicNameDisabled breytu. Athugaðu að þessar snyrtivörusérstillingar eru aðeins tiltækar fyrir málið þegar þú ert að fella inn eitt efni.
Ef þú vilt gera þema innbyggðu Q stikunnar til að útlitið sé í samræmi við forritið þitt, geturðu gert það með því að búa til nýtt þema í QuickSight og senda þemaId til SDK (td.ample fyrir neðan).
Examples
Eftirfarandi frvamples mun gera ráð fyrir að það sé gámur til staðar í DOM með auðkenninu `q-bar-container'.
Innfelling með sjálfgefna bakgrunnshegðun (með q/leitarslóð)
Gerum ráð fyrir að gámurinn sé með 75px spássíu, þannig að við gerum grein fyrir því með því að nota maxHeightForQ færibreytuna, þannig að iframe stækkar ekki stærra en síðan leyfir, skapar skrunstiku eða aðra óæskilega hegðun.
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);
}
Innfelling með óvirka bakgrunnshegðun (með q/leitarslóð)
Fyrir þetta frvampVið gerum ráð fyrir að ílátið sé efst á síðunni þannig að það geti stækkað í 100% án vandræða; við munum ekki þurfa maxHeightForQ. Við munum nota onQBarOpenCallback og onQBarCloseCallback sem no-op aðgerðir til að koma í veg fyrir að sjálfgefna bakgrunnurinn birtist.
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);
}
Innfelling með sérsniðinni bakgrunnshegðun (með q/leitarslóð)
Við munum aftur gera ráð fyrir að gámurinn sé efst á síðunni þannig að hann geti stækkað í 100% án vandræða; við munum ekki þurfa maxHeightForQ. Við munum nota onQBarOpenCallback og onQBarCloseCallback sem svarhringingar sem vinna með einhvern annan bakgrunnsþátt (customBackdropComponent) í forritinu okkar sem við viljum nota í stað sjálfgefna. Athugaðu að bakhringingar þínar gætu verið flóknari, þetta tdample er bara til einföldunar.
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);
}
Innfelling með sjálfgefna bakgrunnshegðun (með q/search/topicId slóð)
Við gerum aftur ráð fyrir að gámurinn hafi 75px spássíu, svo við gerum grein fyrir því með því að nota maxHeightForQ færibreytuna, þannig að iframe stækkar ekki stærra en síðan leyfir, skapar skrunstiku eða aðra óæskilega hegðun. Þar sem við erum að nota innbyggðu leitarstikuna með einu efni, getum við notað sérstillingarnar qBarIconDisabled og qBarTopicNameDisabled. Þetta frvample mun gefa okkur leitarstiku án tákns eða nafns efnis, stillt á að vera tilbúið til að spyrjast fyrir um hvaða topicId sem er sent inn.
function embedQSession(embedUrl) {
var containerDiv = document.getElementById(„q-bar-ílát“);
containerDiv.innerHTML = “”;
var params = {
url: fella innUrl,
gámur: gámurDiv,
isQEmbedded: satt,
maxHeightForQ: „calc(100vh – 75px)",
qBarIconDisabled: ósatt,
qBarTopicNameDisabled: false,
};
QuickSightEmbedding.embedSession(params);
}
Innfelling með þemaauðkenni
Búðu til nýtt þema í QuickSight ef þú ert ekki með það. Opnaðu greiningu eða búðu til nýja. Veldu þemu til vinstri.
Og veldu síðan eitt af byrjunarþemunum sem þú kýst og smelltu síðan á „Vista sem“. Ef þú ert þegar með þema geturðu sleppt skrefinu til að búa til þema.
Það mun fara með þig á þema ritstjórasíðuna, gefa henni nafn, stilla litinn eins og þú vilt og vista hann efst til hægri.
Nú þegar þú ert með þema þarftu að finna auðkenni þess þema og senda það til SDK. Veldu „Breyta“ á þemanu sem þú bjóst til.
Það mun aftur fara með þig á þema ritstjórasíðuna, en að þessu sinni muntu finna þemaauðkenni þar í url bar. Í þessu tilviki er „d39c0065bf69-4b3d-927b-9dd3a241f094“ auðkenni þema sem ég bjó til.
Að lokum sendir þú þemaauðkennið sem færibreytu til SDK, þá færðu þema Q bar í appinu þínu.
function embedQSession(embedUrl) {
var containerDiv = document.getElementById(„q-bar-ílát“);
containerDiv.innerHTML = “”;
var params = {
url: fella innUrl,
gámur: gámurDiv,
isQEmbedded: satt,
maxHeightForQ: "calc(100vh – 75px)“,
qBarIconDisabled: ósatt,
qBarTopicNameDisabled: false,
þemakenni: “d39c0065-bf69-4b3d-927b-9dd3a241f094”
};
QuickSightEmbedding.embedSession(params);
}
Þemahæfur hluti
Við viljum sýna þér hvaða íhlutir í Q bar geta verið þema, og við munum taka QuickSight Midnight þema sem fyrrverandiample (þú getur fundið það í byrjendaþemum)
Úrræðaleit
'Neitaði að ramma *.quicksight.aws.amazon.com vegna þess að forfaðir brýtur..' Villa
Þessi villa stafar af því að ekki er hægt að skrá lénið þitt á stjórnunarsíðu QuickSight í QuickSight forritinu. Vertu viss um að leyfa skrá bæði svæðisbundna QuickSight lénið (fyrir us-east-1, þetta er https://us-east-1.quicksight.aws.amazon.com , tdample), sem og lén forritsins þíns.
Get ekki séð leitarstikuna eftir að innfelling hefur tekist
Ef þú getur búið til og fengið aðgang að og fellt inn tengil (án heimilda eða aðrar augljósar villur), en færð "autt" skjá án leitarstiku sem birtist, þá eru nokkur atriði sem þarf að athuga. Eitt er að það verður að vera að minnsta kosti einu efni sem deilt er með notandanum sem þú ert að fella inn með. Í öðru lagi þarftu að ganga úr skugga um að það sé að minnsta kosti eitt efni sem er búið til með góðum árangri og í „vel heppnuðu“ ástandi eftir upphaflega byggingu. Auðveld leið til að prófa þetta er að nota bara efnið í Q í QuickSight forritinu; ef það virkar eðlilega er gott að nota það í embed in ham.
Önnur ástæða fyrir því að leitarstikan birtist ekki er sú að ílátið sem innfellda iframe er í gefur kannski ekki næga breidd. Eins og kallað er fram í skjölunum, þá þarftu að ganga úr skugga um að leitarstikan sé gefin að minnsta kosti 600px breidd til að hún virki eðlilega.
Leitarstika stækkar en færir efni niður
Leitarstikan með SDK var hönnuð til að stækka yfir allt viðbótarefni á síðunni. Ef þetta er ekki raunin skaltu ganga úr skugga um að leitarstikan sé ílát er stíll með `position: absolute', sem gerir það kleift að færa innihald síðunnar ekki niður. Til dæmisample:
<div id="q-search-container" style="position: absolute; width: 100%"></div>
Breytingaskrá SDK endurskoðunar
- V1(5/15/21): Upphafleg sérsniðin „Q-ready“ SDK
- V1.1 (5/25/21)
- Breyttu iframe hæð til að vera fast við hæð leitarstikunnar sjálfrar, notandi getur ekki tilgreint í Q ham
- Stilltu iframe breidd á 100% af yfirgeymi fyrir Q ham. Athugaðu að breidd leitarstikunnar getur samt verið takmörkuð af stærð móðurílátsins.
- V1.1 (5/25/21)
Skjöl / auðlindir
 |
Amazon Q Embedding Developer viðskiptagreindarþjónusta [pdfNotendahandbók Q Embedding Developer viðskiptagreindarþjónusta, Developer viðskiptagreindarþjónusta, njósnaþjónusta |
