Amazon Quicksight intégration SDK
1.0.0
Merci d'utiliser le SDK JavaScript Amazon QuickSight. Vous pouvez utiliser ce SDK pour intégrer Amazon QuickSight dans votre code HTML.
Pour plus d'informations et pour apprendre à utiliser QuickSight Embedding, veuillez visiter le site Web du portail des développeurs QuickSight.
Amazon QuickSight propose quatre expériences d'intégration différentes avec des options d'isolation des utilisateurs avec des espaces de noms et des autorisations d'interface utilisateur personnalisées.
Option 1 : utilisez le SDK d'intégration Amazon QuickSight dans le navigateur :
...
< 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 : installez le SDK d'intégration Amazon QuickSight dans NodeJs :
npm install amazon-quicksight-embedding-sdk puis utilisez-le dans votre code en utilisant la syntaxe require
const QuickSightEmbedding = require ( "amazon-quicksight-embedding-sdk" ) ;
const embeddingContext = await QuickSightEmbedding . createEmbeddingContext ( ) ; ou, en utilisant la syntaxe import nommée :
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext = await createEmbeddingContext ( ) ; ou, en utilisant la syntaxe import générique :
import * as QuickSightEmbedding from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext = await QuickSightEmbedding . createEmbeddingContext ( ) ; Utilisez la méthode createEmbeddingContext pour créer un contexte d'intégration. Il renvoie une promesse de type 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 > ;
} ; Vous pouvez créer le contexte d'intégration en appelant la méthode createEmbeddingContext sans aucun argument.
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext : EmbeddingContext = await createEmbeddingContext ( ) ; ou, vous pouvez passer un argument d'objet avec la propriété onChange
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext : EmbeddingContext = await createEmbeddingContext ( {
onChange : ( changeEvent ) => {
console . log ( 'Context received a change' , changeEvent ) ;
} ,
} ) ; Le contexte d'intégration crée une iframe supplémentaire de zéro pixel et l'ajoute à l'élément body de la page pour centraliser la communication entre le SDK et le contenu QuickSight intégré.
Une instance EmbeddingContext expose 4 méthodes d'expérience
Ces méthodes prennent 2 paramètres :
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 pour toutes les expériences d'intégration Il s'agit de l'URL d'intégration que vous avez générée à l'aide des opérations de l'API QuickSight pour l'intégration.
Suivez Incorporation avec l'API QuickSight dans le Guide de l'utilisateur Amazon QuickSight pour générer l'URL.
Pour chaque expérience, vous devez vous assurer que les utilisateurs disposent des autorisations nécessaires pour afficher l'expérience intégrée.
Il s'agit du HTMLElement parent dans lequel nous allons intégrer QuickSight.
Il peut s'agir d'un HTMLElement :
container: document . getElementById ( "experience-container" )Ou bien, il peut s'agir d'une chaîne de sélecteur de requête :
container: "#experience-container" Vous pouvez définir width de l'iframe qui contient votre expérience QuickSight intégrée. Vous pouvez définir une valeur fixe :
width: "1000px"Ou une valeur relative :
width: "60%" Pour rendre votre expérience QuickSight intégrée réactive, ne la définissez pas (laissez-la par défaut : 100% ). Ensuite, vous pouvez rendre le conteneur HTMLElement réactif au changement de taille d'écran.
Vous pouvez définir height de l’iframe qui contient votre expérience QuickSight intégrée. Vous pouvez définir une valeur fixe :
height: "700px"Ou une valeur relative :
height: "80%" Pour rendre votre expérience QuickSight intégrée réactive, ne la définissez pas (laissez-la par défaut : 100% ). Ensuite, vous pouvez rendre le conteneur HTMLElement réactif au changement de taille d'écran.
Vous pouvez personnaliser le style de l'iframe qui contient votre expérience intégrée de l'une des manières suivantes :
.quicksight-embedding-iframe {
margin: 5px;
}
className : .your-own-class {
margin: 5px;
}
const option = { className : "your-own-class" }Nous avons remplacé la bordure et le remplissage de l'iframe par 0px, car la définition de la bordure et du remplissage sur l'iframe peut entraîner des problèmes inattendus. Si vous devez définir une bordure et un remplissage sur la session QuickSight intégrée, définissez-les sur le div du conteneur qui contient l'iframe.
Il affiche un simple spinner dans le conteneur d'expérience intégré pendant le chargement du contenu de l'iframe de l'expérience d'intégration.
Ce rappel est invoqué en cas de changement dans l'état du code 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 pris en charge :
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 pour toutes les expériences d'intégration Vous pouvez définir les paramètres régionaux pour la session QuickSight intégrée :
const option = { locale : "en-US" } ; Les options de paramètres régionaux disponibles sont :
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 (中文 (繁體))
Pour une liste plus à jour des paramètres régionaux, veuillez vous référer à https://docs.aws.amazon.com/quicksight/latest/user/choosing-a-lingual-in-quicksight.html. Toute valeur de paramètres régionaux non prise en charge reviendra à l'utilisation en-US .
Vous pouvez ajouter le rappel onMessage dans les contentOptions de toutes les expériences d'intégration.
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 ;
} ; Consultez la documentation spécifique à l’expérience ci-dessous pour connaître eventName pris en charge pour chaque type d’expérience.
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 ;
}
//...
}
}
} ; L'intégration du tableau de bord offre une expérience interactive en lecture seule. Le niveau d'interactivité est défini lors de la publication du tableau de bord.
Pour plus d'informations, consultez Utilisation des analyses intégrées dans le Guide de l'utilisateur Amazon QuickSight.
Utilisez la méthode embedDashboard pour intégrer un tableau de bord QuickSight. Il renvoie une promesse de type 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 > > ;
}