Amazon Quicksight การฝัง SDK
1.0.0
ขอขอบคุณที่ใช้ Amazon QuickSight JavaScript SDK คุณสามารถใช้ SDK นี้เพื่อฝัง Amazon QuickSight ใน HTML ของคุณได้
สำหรับข้อมูลเพิ่มเติมและเรียนรู้วิธีใช้ QuickSight Embedding โปรดไปที่เว็บไซต์ QuickSight Developer Portal
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: ติดตั้ง 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 ฝังที่คุณสร้างขึ้นโดยใช้การดำเนินการ QuickSight API สำหรับการฝัง
ปฏิบัติตามการฝังด้วย QuickSight API ในคู่มือผู้ใช้ 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 ให้เป็น 0px เนื่องจากการตั้งค่าเส้นขอบและช่องว่างภายใน 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 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
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 > > ;
}