Amazon Q Embedding Developer Služba Business Intelligence
Předpoklady
- Účet AWS s povolenou funkcí QuickSight Q
- Alespoň jedno téma nastavené pomocí QuickSight Q (a ID tématu daného tématu)
- Nastavení rámce pro vkládání relace QuickSight s účtem AWS
- Workshop k tomu: https://learnquicksight.workshop.aws/en/session-embedding.html
- Nezapomeňte povolit uvedení vaší domény na stránce Spravovat QuickSight
Určení témat k zobrazení
Vkládání QuickSight Q podporuje dva různé případy použití týkající se témat. První je, když má být specifikováno jedno téma a pouze na toto téma lze dotazovat pomocí vyhledávacího pole. Druhým je standardní prostředí v rámci aplikace QuickSight, kde má uživatel k dispozici seznam témat a pomocí rozevíracího seznamu ve vyhledávací liště si může vybrat téma, na které by se chtěl dotazovat. Než budete pokračovat, ujistěte se, že víte, zda váš případ použití vyžaduje jedno téma nebo seznam témat ve vloženém prostředí.
Seznam povolených domén
Podle příruček pro vkládání QuickSight si všimnete, že musíte na stránce „Manage QuickSight“ uvést doménu vaší aplikace na seznam povolených. Normálně je to vše, co musíte udělat, ale v případě Q budeme také muset přidat doménu QuickSight do seznamu povolených. Zdá se to divné, ale protože pod kapotou Q také používá iframe, potřebujeme, alespoň prozatím, uvést na seznam povolených „stejnou“ doménu. Doména QuickSight, kterou potřebujete na seznam povolených, závisí na oblasti, kterou používáte. Napřample, vkládání pomocí oblasti `us-východ-1', naše URL seznam povolených by byl:
https://us-east-1.quicksight.aws.amazon.com
The URL by bylo stejné pro ostatní regiony se změnou příslušné regionální části (us-východ-1).
Generování nové relace URL
Nejprve část rámce pro vkládání, která generuje relaci URL prostřednictvím getSessionEmbedURL API je potřeba mírně upravit. Vkládání relace QuickSight Q je podporováno v jiném „vstupním bodě“ než standardní vestavěná konzola. Dokumentace pro toto API může být najdete zde. Parametr vstupního bodu pro toto volání API bude nutné změnit – nový vstupní bod závisí na případu použití témat. Pro případ jednoho tématu:
entry-point = /q/search/<topicId>
Chcete-li zobrazit všechna témata ve selektoru, vynecháme topicId:
entry-point = /q/search
To by mělo vygenerovat jednorázové ověření URL která vykreslí stránku pouze pomocí vyhledávacího pole QuickSight Q.
Použití JS SDK k vložení
s URL, můžeme použít poskytnutou sadu QuickSight Embedding Javascript SDK k vložení vyhledávacího panelu Q do aplikace. Nejprve se ujistěte, že máte a kopii sady SDK z týmu QuickSight – všimněte si, že se jedná o preview a ještě nebyla vydána, bude SDK jiná verze, než je veřejně dostupná SDK na githubu. S vygenerovanou relací budeme chtít použít metodu EmbedSession ze sady SDK URL. Relevantní možnosti pro funkci embedSession jsou (také se nacházejí v types.js v sadě 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
Zde jsou dva požadované argumenty url a kontejner. Použijeme URL generované z getSessionEmbedURL Volání API a pro kontejner to závisí na vaší aplikaci. Budete chtít alespoň jednoduchý jako 'kontejner' pro vložený prvek iframe; zadejte tomuto kontejneru id a předejte id v argumentech SDK. Výchozí zpětná volání vkládání relace, errorCallback a loadCallback dělají, jak by název mohl napovídat – pokud
potřebujete vlastní chování, když se vložená stránka načte nebo dojde k chybě, zadejte tuto logiku v těchto zpětných voláních. Při použití vloženého režimu Q se sadou SDK bude mít prvek iframe pevnou výšku (výška samotného vyhledávacího panelu) a 100% šířku nadřazeného kontejneru HTML. To znamená, že vyhledávací panel bude široký pouze jako kontejner; budete se chtít ujistit, že vyhledávací pole má šířku alespoň 600 pixelů (ať už je přeloženo z view-šířka/procenttage nebo přímo přidělené). Pro stylování prvku iframe lze volitelně zadat také parametr className.
DŮLEŽITÉ:
Klíčovým požadavkem je zajistit, aby nebo komponenta, kterou předáváte jako prvek html kontejneru, má styl `position: absolute'. To umožňuje, aby se vyhledávací panel rozbalil jako překryvná vrstva, místo aby se obsah vaší aplikace posouval dolů.
Změny vkládání QuickSight Q
Existuje několik klíčových rozdílů mezi vkládáním relace/dashboardu a vkládáním vyhledávacího panelu Q (ačkoli v současné době vkládání Q jednoduše využívá vkládání relace). S řídicím panelem a vkládáním relace má rám obecně jednu velikost, s výjimkou některých změn velikosti na základě velikosti řídicího panelu nebo listu analýzy. S Q je zpočátku vložený rámec na vaší stránce relativně malý (chceme, aby se zobrazoval pouze skutečný vyhledávací panel). Když se používá vyhledávací panel, musí se tento rám rozbalit (aby se zobrazily další rozevírací prvky, jako je vizuální výsledek, návrhy atd.). Abychom tento rámec rozšířili bez posunutí obsahu vaší aplikace, nastavili jsme jej pouze jako překryvnou vrstvu přes stávající stránku, podobně jako dnes funguje vyhledávací lišta v aplikaci QuickSight – viz snímky obrazovky níže.
S ohledem na to, jak funguje vkládání Q, se podívejme na specifické parametry SDK QuickSight Q. Nejprve potřebujeme, aby byl parametr isQEmbedded nastaven jako true. maxHeightForQ je volitelný argument, který určuje největší, jaký může být Q rámec na vaší stránce; jak již bylo zmíněno dříve, budeme potřebovat prvek iframe a jeho kontejner, aby se rozšířily přes obsah stránky. Argument maxHeightForQ můžeme použít k zajištění toho, aby se velikost rámce/kontejneru nezměnila za maximální výšku vaší stránky a nezpůsobila posouvání nebo jiné nežádoucí chování. Pokud není nastaveno, velikost snímku Q se změní na 100vh.
Poslední dva parametry specifické pro Q jsou zpětná volání, ke kterým dochází při změně velikosti vloženého rámce. Výchozí chování je vytvořit prvek pozadí a použít jej k vytvoření tmavšího vzhledu pozadí, který vidíme na výše uvedených snímcích obrazovky z aplikace QuickSight. Toto je funkce „z krabice“, kterou chceme poskytnout, aby bylo vkládání Q co nejsnazší – víme však, že to nebude fungovat pro každou aplikaci, do které je třeba zabudovat Q. Pokud potřebujete přepsat toto chování, jednoduše zapište logiku do onQBarOpenCallback a onQBarCloseCallback. Tím zabráníte zobrazení výchozího pozadí.
Možnosti stylu QuickSight Q
Existuje několik stylingových/kosmetických možností, které můžeme použít k přizpůsobení vzhledu vyhledávací lišty 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
Pokud byste chtěli deaktivovat ikonu `Q' (na levé straně vyhledávacího panelu použijte parametr qBarIconDisabled. Podobně, chcete-li deaktivovat název tématu, pokud zobrazujete pouze singulární téma ve vloženém režimu, použijte qBarTopicNameDisabled Všimněte si, že tyto kosmetické úpravy jsou dostupné pouze pro případ, kdy vkládáte jedno téma.
Pokud chcete motiv vloženého Q pruhu vytvořit tak, aby byl vzhled konzistentní s vaší aplikací, můžete tak učinit vytvořením nového motivu v QuickSight a předáním themeId SDK (např.ample níže).
Examples
Následující examples bude předpokládat, že v DOM je přítomen kontejner s id `q-bar-container'.
Vkládání s výchozím chováním kulisy (s q/vyhledávací cestou)
Předpokládejme, že kontejner má horní okraj 75 pixelů, takže to zohledníme pomocí parametru maxHeightForQ, aby se iframe nerozšiřoval na větší velikost, než umožňuje stránka, a nevytváří posuvník nebo jiné nežádoucí chování.
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);
}
Vkládání s vypnutým chováním pozadí (s q/vyhledávací cestou)
Pro tento example budeme předpokládat, že kontejner je v horní části stránky, takže se může bez problémů roztáhnout na 100 %; nebudeme potřebovat maxHeightForQ. Abychom zabránili zobrazení výchozího pozadí, použijeme onQBarOpenCallback a onQBarCloseCallback jako neoperativní funkce.
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);
}
Vkládání s vlastním chováním pozadí (s q/vyhledávací cestou)
Znovu budeme předpokládat, že kontejner je v horní části stránky, takže se může bez problémů rozbalit na 100 %; nebudeme potřebovat maxHeightForQ. Použijeme onQBarOpenCallback a onQBarCloseCallback jako zpětná volání, která manipulují s nějakou jinou komponentou pozadí (customBackdropComponent) v naší aplikaci, kterou bychom chtěli použít místo výchozí. Všimněte si, že vaše zpětná volání na pozadí mohou být složitější, napřample je jen pro jednoduchost.
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);
}
Vkládání s výchozím chováním kulisy (s cestou q/search/topicId)
Znovu budeme předpokládat, že kontejner má horní okraj 75 pixelů, takže to zohledníme pomocí parametru maxHeightForQ, aby se iframe nerozšířil na větší velikost, než umožňuje stránka, a nevytvářel tak posuvník nebo jiné nežádoucí chování. Vzhledem k tomu, že používáme vestavěný vyhledávací panel s jedním tématem, můžeme použít přizpůsobení qBarIconDisabled a qBarTopicNameDisabled. Tento example nám poskytne vyhledávací pole bez ikony nebo názvu tématu, které je nastaveno tak, aby bylo připraveno dotazovat se na jakékoli téma, které je předáno.
funkce embedQSession(embedUrl) {
var containerDiv = document.getElementById("q-bar-container");
containerDiv.innerHTML = "";
var params = {
url: vložitUrl,
kontejner: containerDiv,
isQEmbedded: true,
maxHeightForQ: “calc(100vh – 75px)“,
qBarIconDisabled: false,
qBarTopicNameDisabled: false,
};
QuickSightEmbedding.embedSession(params);
}
Vložení s ID tématu
Vytvořte si nový motiv v QuickSight, pokud žádný nemáte. Otevřete analýzu nebo vytvořte novou. Vlevo vyberte Motivy.
A poté vyberte jedno ze startovacích motivů, které preferujete, a klikněte na „Uložit jako“. Pokud již téma máte, můžete krok vytvoření motivu přeskočit.
Dostanete se na stránku editoru motivu, pojmenujte ji, upravte barvu, jak chcete, a poté ji uložte vpravo nahoře.
Nyní, když máte motiv, musíte najít id tohoto motivu a předat jej SDK. Vyberte „Upravit“ na motivu, který jste vytvořili.
Znovu vás přenese na stránku editoru motivu, ale tentokrát tam najdete id motivu url bar. V tomto případě je „d39c0065bf69-4b3d-927b-9dd3a241f094“ id motivu, který jsem vytvořil.
Nakonec předáte id motivu jako parametr do SDK, poté ve své aplikaci získáte tematický Q bar.
funkce embedQSession(embedUrl) {
var containerDiv = document.getElementById("q-bar-container");
containerDiv.innerHTML = "";
var params = {
url: vložitUrl,
kontejner: containerDiv,
isQEmbedded: true,
maxHeightForQ: "calc(100vh – 75px)“,
qBarIconDisabled: false,
qBarTopicNameDisabled: false,
themeId: “d39c0065-bf69-4b3d-927b-9dd3a241f094”
};
QuickSightEmbedding.embedSession(params);
}
Tématická komponenta
Chceme vám ukázat, které komponenty uvnitř Q baru lze motivovat, a jako příklad použijeme téma QuickSight Midnightample (najdete jej v úvodních tématech)
Odstraňování problémů
'Odmítl zarámovat *.quicksight.aws.amazon.com protože předek porušuje..“ Chyba
Tato chyba je způsobena tím, že není povoleno uvedení vaší domény na stránce správy QuickSight v aplikaci QuickSight. Nezapomeňte povolit seznam obou regionálních domén QuickSight (pro us-východ-1, to je https://us-east-1.quicksight.aws.amazon.com , napřample), stejně jako doménu vaší aplikace.
Po úspěšném vložení nevidím vyhledávací lištu
Pokud jste schopni úspěšně vygenerovat a získat přístup a vložit odkaz (bez oprávnění nebo jiných zjevných chyb), ale zobrazí se vám „prázdná“ obrazovka bez vyhledávacího pole, je třeba zkontrolovat několik věcí. Jedním z nich je, že musí existovat alespoň jedno téma sdílené s uživatelem, se kterým vkládáte. Za druhé, budete se chtít ujistit, že existuje alespoň jedno téma, které bylo úspěšně vytvořeno a v „úspěšném“ stavu po prvním vytvoření. Snadný způsob, jak to otestovat, je jednoduše použít téma v Q v aplikaci QuickSight; pokud to funguje normálně, je dobré používat v embedded režimu.
Dalším důvodem, proč se vyhledávací panel nemusí zobrazovat, je to, že kontejner, ve kterém je vložený prvek iframe, nemusí poskytovat dostatečnou šířku. Jak je uvedeno v dokumentaci, budete se chtít ujistit, že vyhledávací lišta má šířku alespoň 600 pixelů, aby fungovala normálně.
Panel vyhledávání se rozšíří, ale posune obsah dolů
Vyhledávací panel se sadou SDK byl navržen tak, aby se rozšiřoval přes jakýkoli další obsah na stránce. Pokud tomu tak není, zkontrolujte prosím kontejner vyhledávací lišty je stylizována s 'position: absolute', což mu umožní neposouvat obsah stránky dolů. Napřampten:
<div id="q-search-container" style="position: absolute; width: 100%"></div>
Protokol změn revize SDK
- V1(5/15/21): Počáteční vlastní sada SDK připravená pro Q
- V1.1 (5)
- Změňte výšku prvku iframe tak, aby byla pevně nastavena na výšku samotného vyhledávacího panelu, uživatel nemůže zadat v režimu Q
- Nastavte šířku prvku iframe na 100 % nadřazeného kontejneru pro režim Q. Všimněte si, že šířka vyhledávacího pole může být stále omezena velikostí nadřazeného kontejneru.
- V1.1 (5)
Dokumenty / zdroje
 |
Amazon Q Embedding Developer Služba Business Intelligence [pdfUživatelská příručka Q Embedding Developer Business intelligence service, Developer Business Intelligence service, zpravodajská služba |
