Амазон Q Embedding Developer Служба за деловна интелигенција

Содржини скриј
1 Предуслови
2 Одредување тема(и) за прикажување
3 Дозволување на список на домен
4 Генерирање на новата сесија URL
5 Користење на JS SDK за вградување
6 QuickSight Q Промени за вградување
7 Опции за стилизирање QuickSight Q
8 Exampлес
9 Тематска компонента
10 Решавање проблеми
11 Дневник за промена на ревизија на SDK
12 Документи / ресурси
12.1 Референци
13 Поврзани мислења

Предуслови

  • AWS сметка со овозможен QuickSight Q
  • Најмалку една тема поставена со QuickSight Q (и ID на тема на таа тема)
  • Поставување рамка за вградување на сесија QuickSight со сметката AWS

Одредување тема(и) за прикажување

Вградувањето QuickSight Q поддржува два различни случаи на употреба во врска со теми. Првиот е кога треба да се одреди една тема и само таа тема може да се бара преку лентата за пребарување. Вториот е стандардното искуство во апликацијата QuickSight, каде што корисникот има список на теми и може да користи паѓачко мени во лентата за пребарување за да ја избере темата против која би сакал да побара. Пред да продолжите, проверете дали знаете дали вашиот случај на употреба бара една тема или листа на теми во вграденото искуство.

Дозволување на список на домен

Според упатствата за вградување на QuickSight, ќе забележите дека треба да го наведете доменот на вашата апликација за дозволи во страницата „Управување со QuickSight“. Вообичаено, ова е сè што треба да направите, но во случајот со Q, ќе треба да го додадеме и доменот QuickSight во списокот со дозволи. Ова изгледа чудно, но бидејќи под капакот Q користи и iframe, треба, барем засега, да го ставиме списокот на „истиот“ домен. Доменот QuickSight што треба да го поставите зависи од регионот што го користите. За прample, вградување со користење на регионот `us-east-1, наш URL до списокот на дозволи ќе биде:

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

На URL истото би било и за другите региони, со промена на соодветниот регионален дел (нас-исток-1).

Генерирање на новата сесија URL

Прво делот од рамката за вградување што ја генерира сесијата URL преку getSessionEmbedURL API треба малку да се измени. Вградувањето на QuickSight Q сесијата е поддржано на различна „влезна точка“ од стандардното искуство со вградено конзола. Документацијата за ова API може да биде најде овде. Параметарот за влезна точка за овој повик API ќе треба да се смени - новата влезна точка зависи од употребата на тема(и). За случајот со една тема:

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

За да ги прикажеме сите теми во избирачот, ќе ја испуштиме темата ID:

entry-point = /q/search

Ова треба да генерира еднократно автентицирано URL што ќе прикаже страница само со лентата за пребарување QuickSight Q.

Користење на JS SDK за вградување

Со URL, можеме да ја користиме обезбедената QuickSight Embedding Javascript SDK за да ја вградиме лентата за пребарување Q во апликацијата. Прво, проверете дали имате а копија од SDK од тимот на QuickSight – имајте предвид бидејќи ова е предview функција и сè уште не е објавена, SDK ќе биде различна верзија од јавно достапната SDK на github. Ќе сакаме да го користиме методот EmbedSession од SDK со генерираната сесија URL. Релевантните опции за функцијата embedSession се (исто така пронајдени во type.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

Двата потребни аргументи овде се url и контејнер. Ќе го користиме URL генерирана од getSessionEmbedURL Повик за API, а за контејнерот тоа зависи од вашата апликација. Ќе сакате барем едноставно како „контејнер“ за вградениот iframe; дајте му на овој контејнер ид и внесете го идентификацијата во аргументите на SDK. Стандардната сесија за вградување повратни повици, errorCallback и loadCallback прават како што сугерира името - ако
треба приспособено однесување кога вградената страница се вчитува или наидува на грешка, наведете ја таа логика во овие повратни повици. Кога користите Q вграден режим со SDK, iframe ќе биде фиксна висина (висина на самата лента за пребарување) и 100% ширина на матичниот HTML контејнер. Ова значи дека лентата за пребарување ќе биде широка само како контејнерот; ќе сакате да бидете сигурни дека лентата за пребарување има ширина од најмалку 600 пиксели (без разлика дали е преведена од view-ширина/процентtagд или директно доделени). За стилизирање на iframe, параметарот className може опционално да се специфицира и.

ВАЖНО:
Клучен повик овде е да се осигураме дека или компонента што ја пренесувате како контејнер html елемент има стил на „позиција: апсолутна“. Ова е она што овозможува лентата за пребарување да се прошири како преклоп наместо да ја преместува содржината на вашата апликација надолу.

QuickSight Q Промени за вградување

Има неколку клучни разлики помеѓу вградувањето на сесија/табла и вградувањето на лентата за пребарување Q (иако моментално Q вградувањето едноставно користи вградување сесија). Со вградување на контролната табла и сесии, рамката е генерално со една големина, забранува одредена промена на големината врз основа на големината на контролната табла или листот за анализа. Со Q, првично вградената рамка на вашата страница е релативно мала (сакаме да се прикаже само вистинската лента за пребарување). Кога се користи лентата за пребарување, оваа рамка треба да се прошири (за да се прикажат дополнителни паѓачки елементи како визуелен резултат, предлози итн.). За да ја прошириме оваа рамка без да ја смениме содржината на вашата апликација, само ја поставивме како преклопување на постоечката страница, слично на тоа како функционира лентата за пребарување во апликацијата QuickSight денес - видете ги сликите од екранот подолу.

Имајќи на ум малку за тоа како функционира Q вградувањето, ајде да ги погледнеме специфичните параметри на QuickSight Q SDK. Прво, ќе ни треба isQEmbedded за да биде поставено како точно. maxHeightForQ е опционален аргумент кој го одредува најголемиот што може да биде рамката Q на вашата страница; како што беше споменато претходно, ќе ни треба iframe и контејнер за проширување на содржината на страницата. Можеме да го користиме аргументот maxHeightForQ за да се осигураме дека рамката/контејнерот нема да ја промени големината над максималната висина на вашата страница и да предизвика појава на лизгање или друго несакано однесување. Ако не е поставена, Q рамката ќе ја промени големината на 100vh.

Последните два Q специфични параметри се повратни повици што се случуваат кога се менува големината на вградената рамка. Стандардното однесување е да се создаде елемент за заднина и да се користи ова за да се даде изглед на потемната позадина што ја гледаме на горните слики од екранот од апликацијата QuickSight. Ова е функционалноста „out of the box“ што сакаме да ја обезбедиме за да го направиме вградувањето 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 со идентификација „q-bar-container“.

Вградување со стандардно однесување на заднината (со q/пат за пребарување)

Да претпоставиме дека контејнерот има врв на маргина од 75 пиксели, така што ќе го земеме предвид со помош на параметарот 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) во нашата апликација која би сакале да ја користиме наместо стандардната. Имајте предвид дека вашите повратни повици во заднина може да бидат посложени, на прampе само за едноставност.

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)

Повторно ќе претпоставиме дека контејнерот има врвна маргина од 75 пиксели, така што ќе го земеме предвид тоа користејќи го параметарот maxHeightForQ, така што iframe-от не се прошири поголемо отколку што дозволува страницата, создавајќи лента за лизгање или друго несакано однесување. Бидејќи ја користиме вградената лента за пребарување со една тема, можеме да ги користиме прилагодувањата qBarIconDisabled и qBarTopicNameDisabled. Овој ексampќе ни даде лента за пребарување без икона или име на тема, поставена да биде подготвена за барање во која и да е ID на тема.

функцијата embedQSession (вградиUrl) {
var containerDiv = document.getElementById(„Q-бар-контејнер“);
containerDiv.innerHTML = „“;
var парами = {
url: вградувањеUrl,
контејнер: containerDiv,
isQEmbedded: точно,
maxHeightForQ: „калк(100vh – 75px)“,
qBarIconDisabled: неточно,
qBarTopicNameDisabled: неточно,
};
QuickSightEmbedding.embedSession(params);
}

Вградување со ИД на тема

Создадете нова тема во QuickSight ако ја немате. Отворете анализа или креирајте нова. Изберете Теми лево.
И потоа изберете една од почетните теми што ја претпочитате, а потоа кликнете „Зачувај како“. Ако веќе имате тема, можете да го прескокнете чекорот за создавање тема.

Ќе ве однесе до страницата за уредувач на теми, ќе и дадете име, ќе ја прилагодите бојата како што сакате, а потоа ќе ја зачувате на горниот десен агол.

Сега кога имате тема, треба да го пронајдете ID на таа тема и да го предадете на SDK. Изберете „Уреди“ на темата што сте ја создале.

Повторно ќе ве однесе до страницата за уредувач на теми, но овој пат ќе го најдете ID на темата таму во url бар. Во овој случај „d39c0065bf69-4b3d-927b-9dd3a241f094“ е ид на темата што ја создадов.

И на крај, го пренесувате ID-то на темата како параметар на SDK, а потоа ќе добиете тематска Q лента во вашата апликација.

функцијата embedQSession (вградиUrl) {
var containerDiv = document.getElementById(„Q-бар-контејнер“);
containerDiv.innerHTML = „“;
var парами = {
url: вградувањеUrl,
контејнер: containerDiv,
isQEmbedded: точно,
maxHeightForQ: „calc(100vh – 75px)“,
qBarIconDisabled: неточно,
qBarTopicNameDisabled: неточно,
ИД на тема: “d39c0065-bf69-4b3d-927b-9dd3a241f094”
};
QuickSightEmbedding.embedSession(params);
}

Тематска компонента

Сакаме да ви покажеме кои компоненти во Q лентата можат да бидат тематски и ќе ја земеме темата QuickSight Midnight како ексample (може да го најдете во почетните теми)

Решавање проблеми

„Одби да врами *.quicksight.aws.amazon.com бидејќи предок прекршува..“ Грешка

Оваа грешка е предизвикана од тоа што не дозволува наведување на вашиот домен во административната страница за управување со QuickSight во апликацијата QuickSight. Погрижете се да дозволите список и на регионалниот домен QuickSight (за нас-east-1, ова е https://us-east-1.quicksight.aws.amazon.com , на прample), како и доменот на вашата апликација.

Не можам да ја видам лентата за пребарување по успешно вградување

Ако сте во можност успешно да генерирате и пристапувате и вградувате врска (без дозволи или други очигледни грешки), но добиете „празен“ екран без да се појавува лента за пребарување, има неколку работи што треба да ги проверите. Една од нив е дека мора да има барем една тема споделена со корисникот со кој го вградувате. Второ, ќе сакате да бидете сигурни дека има барем една тема што е успешно креирана и во „успешна“ состојба по првичното градење. Лесен начин да се тестира ова е само да се користи темата во Q во апликацијата QuickSight; ако работи нормално, добро е да се користи во вграден режим.

Друга причина зошто лентата за пребарување можеби не се појавува е тоа што контејнерот во кој се наоѓа iframe за вградување можеби не дава доволно ширина. Како што е наведено во документацијата, ќе сакате да бидете сигурни дека лентата за пребарување има ширина од најмалку 600 пиксели за таа да функционира нормално.

Лентата за пребарување се проширува, но ја префрла содржината надолу

Лентата за пребарување со SDK беше дизајнирана да се прошири над секоја дополнителна содржина на страницата. Ако ова не е случај, ве молиме проверете го контејнерот на лентата за пребарување е стилизиран со „позиција: апсолутна“, што ќе му овозможи да не ја поместува содржината на страницата надолу. За пр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)
      • Променете ја висината на рамката за да се фиксира на висината на самата лента за пребарување, корисникот не може да ја одреди во режимот Q
      • Поставете ја ширината на iframe на 100% од матичниот контејнер за режимот Q. Имајте предвид дека ширината на лентата за пребарување сè уште може да се ограничи со големината на матичниот контејнер.

Документи / ресурси

Амазон Q Embedding Developer Служба за деловна интелигенција [pdf] Упатство за корисникот
Q Embedding Developer Бизнис разузнавачка служба, Developer Business Intelligence Service, разузнавачка служба

Референци

Поврзани мислења

Оставете коментар

Вашата адреса за е-пошта нема да биде објавена. Задолжителните полиња се означени *