亚马逊 Quicksight 嵌入 sdk
1.0.0
感谢您使用 Amazon QuickSight JavaScript SDK。您可以使用此开发工具包将 Amazon QuickSight 嵌入到您的 HTML 中。
如需了解更多信息以及如何使用 QuickSight 嵌入，请访问 QuickSight 开发者门户网站
Amazon QuickSight 提供四种不同的嵌入体验，以及使用命名空间和自定义 UI 权限进行用户隔离的选项。
选项 1：在浏览器中使用 Amazon QuickSight 嵌入 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：在 NodeJ 中安装 Amazon QuickSight 嵌入 SDK：
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的通用属性这是您使用 QuickSight API 嵌入操作生成的嵌入 URL。
按照 Amazon QuickSight 用户指南中的使用 QuickSight API 嵌入来生成 URL。
对于每种体验，您需要确保向用户授予查看嵌入式体验所需的权限。
这是我们将在其中嵌入 QuickSight 的父 HTMLElement。
它可以是一个 HTMLElement：
container: document . getElementById ( "experience-container" )或者，它可以是查询选择器字符串：
container: "#experience-container" 您可以设置保存嵌入式 QuickSight 体验的 iframe 的width 。您可以将其设置为固定值：
width: "1000px"或者，相对值：
width: "60%"要使嵌入式 QuickSight 体验具有响应能力，请不要设置它（将其保留为默认值： 100% ）。然后您可以使容器 HTMLElement 响应屏幕尺寸的变化。
您可以设置容纳嵌入式 QuickSight 体验的 iframe 的height 。您可以将其设置为固定值：
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 的边框和内边距覆盖为 0px，因为在 iframe 上设置边框和内边距可能会导致意外问题。如果您必须在嵌入式 QuickSight 会话上设置边框和内边距，请在包含 iframe 的容器 div 上进行设置。
当加载嵌入体验 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 ;
}
//...
}
}
} ; 仪表板嵌入提供了交互式只读体验。交互级别在发布仪表板时设置。
有关更多信息，请参阅 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 > > ;
}