Amazon Quicksight 내장 SDK
1.0.0
Amazon QuickSight JavaScript SDK를 사용해 주셔서 감사합니다. 이 SDK를 사용하여 HTML에 Amazon QuickSight를 포함할 수 있습니다.
자세한 내용과 QuickSight Embedding 사용 방법을 알아보려면 QuickSight 개발자 포털 웹사이트를 방문하세요.
Amazon QuickSight는 네임스페이스를 통한 사용자 격리 옵션과 사용자 지정 UI 권한을 갖춘 네 가지 내장 환경을 제공합니다.
옵션 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: NodeJs에 Amazon QuickSight Embedding 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 ) ;
} ,
} ) ; 포함 컨텍스트는 추가 0픽셀 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입니다.
URL을 생성하려면 Amazon QuickSight 사용 설명서의 QuickSight API를 사용한 임베딩을 따르세요.
각 경험에 대해 사용자에게 내장된 경험을 보는 데 필요한 권한이 부여되었는지 확인해야 합니다.
이는 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에 테두리와 패딩을 설정하면 예상치 못한 문제가 발생할 수 있으므로 iframe의 테두리와 패딩을 0px로 재정의했습니다. 포함된 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 s:
ERROR
INFO
WARN
ErrorChangeEventName
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
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-언어-in-quicksight.html을 참조하십시오. 지원되지 않는 로케일 값은 en-US 사용으로 대체됩니다.
모든 임베딩 경험의 contentOptions 에 onMessage 콜백을 추가할 수 있습니다.
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 사용 설명서의 내장된 분석 작업을 참조하십시오.
QuickSight 대시보드를 삽입하려면 embedDashboard 메서드를 사용하세요. 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 > > ;
}