SDK для встраивания Amazon Quicksight
1.0.0
Благодарим вас за использование Amazon QuickSight JavaScript SDK. Вы можете использовать этот SDK для встраивания Amazon QuickSight в свой HTML.
Для получения дополнительной информации и изучения того, как использовать QuickSight Embedding, посетите веб-сайт портала разработчиков QuickSight.
Amazon QuickSight предлагает четыре различных способа внедрения с возможностью изоляции пользователей с помощью пространств имен и настраиваемых разрешений пользовательского интерфейса.
Вариант 1. Используйте Amazon QuickSight Embedding SDK в браузере:
...
< script src =" https://unpkg.com/[email protected]/dist/quicksight-embedding-js-sdk.min.js " > script >
< script type =" text/javascript " >
const onLoad = async ( ) => {
const embeddingContext = await QuickSightEmbedding . createEmbeddingContext ( ) ;
//...
} ;
script >
...
< body onload =" onLoad() " >
...Вариант 2. Установите Amazon QuickSight Embedding SDK в NodeJs:
npm install amazon-quicksight-embedding-sdk а затем используйте его в своем коде, используя синтаксис require
const QuickSightEmbedding = require ( "amazon-quicksight-embedding-sdk" ) ;
const embeddingContext = await QuickSightEmbedding . createEmbeddingContext ( ) ; или, используя именованный синтаксис import :
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext = await createEmbeddingContext ( ) ; или, используя синтаксис import с подстановочными знаками:
import * as QuickSightEmbedding from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext = await QuickSightEmbedding . createEmbeddingContext ( ) ; Используйте метод createEmbeddingContext для создания контекста внедрения. Он возвращает обещание типа EmbeddingContext .
export type CreateEmbeddingContext = ( frameOptions ?: EmbeddingContextFrameOptions ) => Promise < EmbeddingContext >
export type EventListener = (
event : EmbeddingEvents ,
metadata ?: ExperienceFrameMetadata
) => void ;
export type EmbeddingContextFrameOptions = {
onChange ?: EventListener ;
} ;
export type IEmbeddingContext = {
embedDashboard : ( frameOptions : FrameOptions , contentOptions ?: DashboardContentOptions ) => Promise < DashboardExperience > ;
embedVisual : ( frameOptions : FrameOptions , contentOptions ?: VisualContentOptions ) => Promise < VisualExperience > ;
embedConsole : ( frameOptions : FrameOptions , contentOptions ?: ConsoleContentOptions ) => Promise < ConsoleExperience > ;
embedQSearchBar : ( frameOptions : FrameOptions , contentOptions ?: QSearchContentOptions ) => Promise < QSearchExperience > ;
embedGenerativeQnA : ( frameOptions : FrameOptions , contentOptions ?: GenerativeQnAContentOptions ) => Promise < GenerativeQnAContentOptions > ;
} ; Вы можете создать контекст внедрения, вызвав метод createEmbeddingContext без каких-либо аргументов.
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext : EmbeddingContext = await createEmbeddingContext ( ) ; или вы можете передать аргумент объекта с помощью свойства onChange
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext : EmbeddingContext = await createEmbeddingContext ( {
onChange : ( changeEvent ) => {
console . log ( 'Context received a change' , changeEvent ) ;
} ,
} ) ; Контекст внедрения создает дополнительный iframe с нулевым пикселем и добавляет его в элемент body на странице, чтобы централизовать связь между SDK и внедренным содержимым QuickSight.
Экземпляр EmbeddingContext предоставляет 4 метода взаимодействия.
Эти методы принимают 2 параметра:
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext = await createEmbeddingContext ( ) ;
const {
embedDashboard ,
embedVisual ,
embedConsole ,
embedQSearchBar ,
} = embeddingContext ;
const frameOptions = {
//...
} ;
const contentOptions = {
//...
} ;
// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard ( frameOptions , contentOptions ) ;
// Embedding a visual experience
const embeddedVisualExperience = await embedVisual ( frameOptions , contentOptions ) ;
// Embedding a console experience
const embeddedConsoleExperience = await embedConsole ( frameOptions , contentOptions ) ;
// Embedding a Q search bar experience
const embeddedQSearchExperience = await embedQSearchBar ( frameOptions , contentOptions ) ;frameOptions для всех вариантов внедрения Это URL-адрес для встраивания, созданный с помощью операций API QuickSight для встраивания.
Следуйте инструкциям по внедрению с помощью API QuickSight в Руководстве пользователя Amazon QuickSight, чтобы создать URL-адрес.
Для каждого опыта вам необходимо убедиться, что пользователям предоставлены необходимые разрешения для просмотра встроенного интерфейса.
Это родительский элемент HTMLElement, в который мы собираемся встроить QuickSight.
Это может быть HTMLElement:
container: document . getElementById ( "experience-container" )Или это может быть строка селектора запроса:
container: "#experience-container" Вы можете установить width iframe, в котором хранится встроенный интерфейс QuickSight. Вы можете установить для него фиксированное значение:
width: "1000px"Или относительное значение:
width: "60%" Чтобы сделать встроенный интерфейс QuickSight отзывчивым, не устанавливайте его (оставьте значения по умолчанию: 100% ). Затем вы можете сделать контейнер HTMLElement реагирующим на изменение размера экрана.
Вы можете установить height iframe, в котором хранится встроенный интерфейс QuickSight. Вы можете установить для него фиксированное значение:
height: "700px"Или относительное значение:
height: "80%" Чтобы сделать встроенный интерфейс QuickSight отзывчивым, не устанавливайте его (оставьте значения по умолчанию: 100% ). Затем вы можете сделать контейнер HTMLElement реагирующим на изменение размера экрана.
Вы можете настроить стиль iframe, в котором хранится встроенный интерфейс, одним из следующих способов:
.quicksight-embedding-iframe {
margin: 5px;
}
className : .your-own-class {
margin: 5px;
}
const option = { className : "your-own-class" }Мы переопределили границу и отступы iframe на 0 пикселей, поскольку установка границы и отступов в iframe может вызвать непредвиденные проблемы. Если вам необходимо установить границу и отступы во встроенном сеансе QuickSight, установите их в контейнере div, содержащем iframe.
Он отображает простой счетчик во встроенном контейнере взаимодействия во время загрузки содержимого встроенного iframe.
Этот обратный вызов вызывается при изменении статуса кода SDK.
export type EventListener = (event: EmbeddingEvents, metadata?: ExperienceFrameMetadata) => void;
export interface ChangeEvent {
eventName: EventName,
eventLevel: ChangeEventLevel,
message?: EventMessageValue,
data?: EventData
}
export type ExperienceFrameMetadata = {
frame: EmbeddingIFrameElement | null;
};
Поддерживаемые eventLevel :
ERROR
INFO
WARN
ErrorChangeEventName s
NO_FRAME_OPTIONS = 'NO_FRAME_OPTIONS',
INVALID_FRAME_OPTIONS = 'INVALID_FRAME_OPTIONS',
FRAME_NOT_CREATED: invoked when the creation of the iframe element failed
NO_BODY: invoked when there is no `body` element in the hosting html
NO_CONTAINER: invoked when the experience container is not found
INVALID_CONTAINER: invoked when the container provided is not a valid DOM node
NO_URL: invoked when no url is provided in the frameOptions
INVALID_URL: invoked when the url provided is not a valid url for the experience
NO_FRAME_OPTIONS: invoked when frameOptions property is not populated,
INVALID_FRAME_OPTIONS: invoked when the frameOptions value is not object type,
InfoChangeEventName s
FRAME_STARTED: invoked just before the iframe is created
FRAME_MOUNTED: invoked after the iframe is appended into the experience container
FRAME_LOADED: invoked after iframe element emited the `load` event
FRAME_REMOVED: invoked after iframe element is removed from the DOM
WarnChangeEventName s
UNRECOGNIZED_CONTENT_OPTIONS: invoked when the content options for the experience contain unrecognized properties
UNRECOGNIZED_FRAME_OPTIONS: invoked when the frame options for the experience contain unrecognized properties
UNRECOGNIZED_EVENT_TARGET: invoked when a message with unrecognized event target is received
const frameOptions = {
//...
onChange : ( changeEvent : EmbeddingEvents , metadata : ExperienceFrameMetadata ) => {
if ( changeEvent . eventLevel === ' ERROR ' ) {
console . log ( `Do something when embedding experience failed with " ${ changeEvent . eventName } "` ) ;
return ;
}
switch ( changeEvent . eventName ) {
case 'FRAME_MOUNTED' : {
console . log ( "Do something when the experience frame is mounted." ) ;
break ;
}
case 'FRAME_LOADED' : {
console . log ( "Do something when the experience frame is loaded." ) ;
break ;
}
case 'FRAME_REMOVED' : {
console . log ( "Do something when the experience frame is removed." ) ;
break ;
}
//...
}
} ,
} ;contentOptions для всех вариантов внедрения Вы можете установить локаль для встроенного сеанса QuickSight:
const option = { locale : "en-US" } ; Доступные параметры локали:
en-US (English),
da-DK (Dansk)
de-DE (Deutsch),
ja-JP (日本語),
es-ES (Español),
fr-FR (Français),
it-IT (Italiano),
nl-NL (Nederlands),
nb-NO (Norsk),
pt-BR (Português),
fi-FI (Suomi),
sv-SE (Svenska),
ja-JP (日本語),
ko-KR (한국어),
zh-CN (中文 (简体)),
zh-TW (中文 (繁體))
Более обновленный список локалей можно найти по адресу https://docs.aws.amazon.com/quicksight/latest/user/choosing-a-language-in-quicksight.html. Любое неподдерживаемое значение локали будет возвращено к использованию en-US .
Вы можете добавить обратный вызов onMessage в contentOptions всех возможностей внедрения.
export type EventListener = ( event : EmbeddingEvents , metadata ?: ExperienceFrameMetadata ) => void ;
export interface SimpleMessageEvent {
eventName : EventName ;
message ?: EventMessageValue ;
data ?: EventData ;
eventTarget ?: InternalExperiences ;
}
export type ExperienceFrameMetadata = {
frame : EmbeddingIFrameElement | null ;
} ; См. документацию по конкретному опыту ниже, чтобы узнать о поддерживаемых eventName для каждого типа опыта.
const contentOptions = {
//...
onMessage : async ( messageEvent : EmbeddingEvents , metadata ?: ExperienceFrameMetadata ) => {
switch ( messageEvent . eventName ) {
case 'CONTENT_LOADED' : {
console . log ( "Do something when the embedded experience is fully loaded." ) ;
break ;
}
case 'ERROR_OCCURRED' : {
console . log ( "Do something when the embedded experience fails loading." ) ;
break ;
}
//...
}
}
} ; Dashboard Embedding обеспечивает интерактивный интерфейс только для чтения. Уровень интерактивности задается при публикации панели мониторинга.
Дополнительную информацию см. в разделе «Работа со встроенной аналитикой» Руководства пользователя Amazon QuickSight.
Используйте метод embedDashboard , чтобы встроить панель мониторинга QuickSight. Он возвращает обещание типа DashboardExperience .
export class DashboardExperience extends BaseExperience < DashboardContentOptions , InternalDashboardExperience , IDashboardExperience , TransformedDashboardContentOptions , DashboardExperienceFrame > {
initiatePrint : ( ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
undo : ( ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
redo : ( ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
toggleBookmarksPane : ( ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
getParameters : ( ) => Promise < Parameter [ ] > ;
getSheets : ( ) => Promise < Sheet [ ] > ;
getVisualActions : ( sheetId : string , visualId : string ) => Promise < VisualAction [ ] > ;
addVisualActions : ( sheetId : string , visualId : string , actions : VisualAction [ ] ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
setVisualActions : ( sheetId : string , visualId : string , actions : VisualAction [ ] ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
getFilterGroupsForSheet : ( sheetId : string ) => Promise < FilterGroup [ ] > ;
getFilterGroupsForVisual : ( sheetId : string , visualId : string ) => Promise < FilterGroup [ ] > ;
addFilterGroups : ( filterGroups : FilterGroup [ ] ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
updateFilterGroups : ( filterGroups : FilterGroup [ ] ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
removeFilterGroups : ( filterGroupsOrIds : FilterGroup [ ] | string [ ] ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
setTheme : ( themeArn : string ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
setThemeOverride : ( themeOverride : ThemeConfiguration ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
createSharedView : ( ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
getSelectedSheetId : ( ) => Promise < string > ;
setSelectedSheetId : ( sheetId : string ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
navigateToDashboard : ( dashboardId : string , navigateToDashboardOptions ?: NavigateToDashboardOptions ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
removeVisualActions : ( sheetId : string , visualId : string , actions : VisualAction [ ] ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
getSheetVisuals : ( sheetId : string ) => Promise < Visual [ ] > ;
setParameters : ( parameters : Parameter [ ] ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
reset : ( ) => Promise < SuccessResponseMessage | ErrorResponseMessage > ;
send : < EventMessageValue extends EventMessageValues > ( messageEvent : EmbeddingMessageEvent < MessageEventName > ) => Promise < ResponseMessage < EventMessageValue > > ;
}