Amazon QuickSight Embedding SDK
1.0.0
Vielen Dank, dass Sie das Amazon QuickSight JavaScript SDK verwenden. Mit diesem SDK können Sie Amazon QuickSight in Ihren HTML-Code einbetten.
Weitere Informationen und Informationen zur Verwendung von QuickSight Embedding finden Sie auf der Website des QuickSight Developer Portal
Amazon QuickSight bietet vier verschiedene Einbettungserlebnisse mit Optionen zur Benutzerisolation mit Namespaces und benutzerdefinierten UI-Berechtigungen.
Option 1: Verwenden Sie das Amazon QuickSight Embedding SDK im Browser:
...
< 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() " >
...Option 2: Installieren Sie das Amazon QuickSight Embedding SDK in NodeJs:
npm install amazon-quicksight-embedding-sdk und verwenden Sie es dann in Ihrem Code mithilfe require -Syntax
const QuickSightEmbedding = require ( "amazon-quicksight-embedding-sdk" ) ;
const embeddingContext = await QuickSightEmbedding . createEmbeddingContext ( ) ; oder mit benannter import :
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext = await createEmbeddingContext ( ) ; oder mit Wildcard- import :
import * as QuickSightEmbedding from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext = await QuickSightEmbedding . createEmbeddingContext ( ) ; Verwenden Sie die Methode createEmbeddingContext , um einen Einbettungskontext zu erstellen. Es gibt ein Versprechen vom Typ EmbeddingContext zurück.
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 > ;
} ; Sie können den Einbettungskontext erstellen, indem Sie die Methode createEmbeddingContext ohne Argumente aufrufen
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext : EmbeddingContext = await createEmbeddingContext ( ) ; Oder Sie können ein Objektargument mit der Eigenschaft onChange übergeben
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext : EmbeddingContext = await createEmbeddingContext ( {
onChange : ( changeEvent ) => {
console . log ( 'Context received a change' , changeEvent ) ;
} ,
} ) ; Der Einbettungskontext erstellt einen zusätzlichen Null-Pixel-Iframe und hängt ihn an das body -Element auf der Seite an, um die Kommunikation zwischen dem SDK und dem eingebetteten QuickSight-Inhalt zu zentralisieren.
Eine EmbeddingContext -Instanz stellt vier Erfahrungsmethoden bereit
Diese Methoden benötigen zwei Parameter:
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 für alle Einbettungserlebnisse Dies ist die Einbettungs-URL, die Sie mithilfe der QuickSight-API-Operationen zum Einbetten generiert haben.
Befolgen Sie die Anweisungen zum Einbetten mit der QuickSight-API im Amazon QuickSight-Benutzerhandbuch, um die URL zu generieren.
Für jedes Erlebnis müssen Sie sicherstellen, dass den Benutzern die erforderlichen Berechtigungen zum Anzeigen des eingebetteten Erlebnisses erteilt werden.
Dies ist das übergeordnete HTMLElement, in das wir QuickSight einbetten werden.
Es kann ein HTMLElement sein:
container: document . getElementById ( "experience-container" )Oder es kann eine Abfrageselektorzeichenfolge sein:
container: "#experience-container" Sie können width für den Iframe festlegen, der Ihr eingebettetes QuickSight-Erlebnis enthält. Sie können einen festen Wert festlegen:
width: "1000px"Oder ein relativer Wert:
width: "60%" Um Ihr eingebettetes QuickSight-Erlebnis reaktionsfähig zu machen, legen Sie es nicht fest (belassen Sie die Standardeinstellung: 100% ). Anschließend können Sie dafür sorgen, dass der HTMLElement-Container auf Änderungen der Bildschirmgröße reagiert.
Sie können height für den Iframe festlegen, der Ihr eingebettetes QuickSight-Erlebnis enthält. Sie können einen festen Wert festlegen:
height: "700px"Oder ein relativer Wert:
height: "80%" Um Ihr eingebettetes QuickSight-Erlebnis reaktionsfähig zu machen, legen Sie es nicht fest (belassen Sie die Standardeinstellung: 100% ). Anschließend können Sie dafür sorgen, dass der HTMLElement-Container auf Änderungen der Bildschirmgröße reagiert.
Sie können den Stil des Iframes, der Ihr eingebettetes Erlebnis enthält, auf eine der folgenden Weisen anpassen:
.quicksight-embedding-iframe {
margin: 5px;
}
className : .your-own-class {
margin: 5px;
}
const option = { className : "your-own-class" }Wir haben den Rahmen und den Abstand des Iframes auf 0 Pixel überschrieben, da das Festlegen des Rahmens und des Abstands des Iframes zu unerwarteten Problemen führen kann. Wenn Sie Rahmen und Abstand für die eingebettete QuickSight-Sitzung festlegen müssen, legen Sie diese für das Container-Div fest, das den Iframe enthält.
Es rendert einen einfachen Spinner im eingebetteten Erlebniscontainer, während der Inhalt des eingebetteten Erlebnis-Iframes geladen wird.
Dieser Rückruf wird aufgerufen, wenn sich der SDK-Codestatus ändert.
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;
};
Unterstützte eventLevel s:
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 für alle Einbettungserlebnisse Sie können das Gebietsschema für die eingebettete QuickSight-Sitzung festlegen:
const option = { locale : "en-US" } ; Verfügbare Gebietsschemaoptionen sind:
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 (中文 (繁體))
Eine aktuellere Liste der Gebietsschemas finden Sie unter https://docs.aws.amazon.com/quicksight/latest/user/choosing-a-lingual-in-quicksight.html. Für jeden nicht unterstützten Gebietsschemawert wird auf die Verwendung en-US zurückgegriffen.
Sie können onMessage Rückruf zu den contentOptions aller Einbettungserlebnisse hinzufügen.
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 ;
} ; In der erlebnisspezifischen Dokumentation unten finden Sie die unterstützten eventName s für jeden Erlebnistyp.
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 ;
}
//...
}
}
} ; Die Dashboard-Einbettung bietet ein interaktives, schreibgeschütztes Erlebnis. Der Grad der Interaktivität wird festgelegt, wenn das Dashboard veröffentlicht wird.
Weitere Informationen finden Sie unter Arbeiten mit eingebetteten Analysen im Amazon QuickSight-Benutzerhandbuch.
Verwenden Sie die Methode embedDashboard um ein QuickSight-Dashboard einzubetten. Es gibt ein Versprechen vom Typ DashboardExperience zurück.
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 > > ;
}