SDK de incorporación de Amazon Quicksight
1.0.0
Gracias por utilizar el SDK de JavaScript de Amazon QuickSight. Puede utilizar este SDK para insertar Amazon QuickSight en su HTML.
Para obtener más información y aprender a utilizar QuickSight Embedding, visite el sitio web del portal para desarrolladores de QuickSight.
Amazon QuickSight ofrece cuatro experiencias de integración diferentes con opciones para el aislamiento de usuarios con espacios de nombres y permisos de interfaz de usuario personalizados.
Opción 1: utilice el SDK de incorporación de Amazon QuickSight en el navegador:
...
< 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() " >
...Opción 2: Instale el SDK de incrustación de Amazon QuickSight en NodeJs:
npm install amazon-quicksight-embedding-sdk y luego úselo en su código usando la sintaxis require
const QuickSightEmbedding = require ( "amazon-quicksight-embedding-sdk" ) ;
const embeddingContext = await QuickSightEmbedding . createEmbeddingContext ( ) ; o, usando la sintaxis import con nombre:
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext = await createEmbeddingContext ( ) ; o, utilizando la sintaxis import con comodines:
import * as QuickSightEmbedding from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext = await QuickSightEmbedding . createEmbeddingContext ( ) ; Utilice el método createEmbeddingContext para crear un contexto de incrustación. Devuelve una promesa de tipo 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 > ;
} ; Puede crear el contexto de incrustación llamando al método createEmbeddingContext sin ningún argumento.
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext : EmbeddingContext = await createEmbeddingContext ( ) ; o puede pasar un argumento de objeto con la propiedad onChange
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk' ;
const embeddingContext : EmbeddingContext = await createEmbeddingContext ( {
onChange : ( changeEvent ) => {
console . log ( 'Context received a change' , changeEvent ) ;
} ,
} ) ; El contexto de incrustación crea un iframe adicional de cero píxeles y lo agrega al elemento body de la página para centralizar la comunicación entre el SDK y el contenido QuickSight incrustado.
Una instancia EmbeddingContext expone 4 métodos de experiencia
Estos métodos toman 2 parámetros:
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 para todas las experiencias de incrustación Esta es la URL para incrustar que generó mediante las operaciones de incrustación de QuickSight API.
Siga Incrustación con la API QuickSight en la Guía del usuario de Amazon QuickSight para generar la URL.
Para cada experiencia, debe asegurarse de que a los usuarios se les otorguen los permisos necesarios para ver la experiencia integrada.
Este es el HTMLElement principal donde vamos a incrustar QuickSight.
Puede ser un HTMLElement:
container: document . getElementById ( "experience-container" )O puede ser una cadena de selección de consultas:
container: "#experience-container" Puede establecer width del iframe que contiene su experiencia QuickSight integrada. Puede configurarlo para que sea un valor fijo:
width: "1000px"O un valor relativo:
width: "60%" Para que su experiencia QuickSight integrada responda, no la configure (déjela en el valor predeterminado: 100% ). Luego puede hacer que el contenedor HTMLElement responda al cambio de tamaño de la pantalla.
Puede establecer height del iframe que contiene su experiencia QuickSight integrada. Puede configurarlo para que sea un valor fijo:
height: "700px"O un valor relativo:
height: "80%" Para que su experiencia QuickSight integrada responda, no la configure (déjela en el valor predeterminado: 100% ). Luego puede hacer que el contenedor HTMLElement responda al cambio de tamaño de la pantalla.
Puede personalizar el estilo del iframe que contiene su experiencia integrada mediante una de las siguientes opciones:
.quicksight-embedding-iframe {
margin: 5px;
}
className : .your-own-class {
margin: 5px;
}
const option = { className : "your-own-class" }Hemos anulado el borde y el relleno del iframe para que sean 0px, porque establecer el borde y el relleno en el iframe puede causar problemas inesperados. Si tiene que configurar el borde y el relleno en la sesión QuickSight integrada, configúrelo en el div contenedor que contiene el iframe.
Representa un control giratorio simple en el contenedor de la experiencia integrada mientras se carga el contenido del iframe de la experiencia integrada.
Esta devolución de llamada se invoca cuando hay un cambio en el estado del código 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 admitidos:
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 para todas las experiencias de incrustación Puede configurar la configuración regional para la sesión QuickSight integrada:
const option = { locale : "en-US" } ; Las opciones locales disponibles son:
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 (中文 (繁體))
Para obtener una lista más actualizada de configuraciones regionales, consulte https://docs.aws.amazon.com/quicksight/latest/user/choosing-a-language-in-quicksight.html. Cualquier valor local no admitido recurrirá al uso en-US .
Puede agregar una devolución de llamada onMessage en las contentOptions de todas las experiencias de inserción.
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 ;
} ; Consulte la documentación específica de la experiencia a continuación para conocer los eventName admitidos para cada tipo de experiencia.
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 ;
}
//...
}
}
} ; Dashboard Embedding proporciona una experiencia interactiva de solo lectura. El nivel de interactividad se establece cuando se publica el panel.
Para obtener más información, consulte Trabajar con análisis integrados en la Guía del usuario de Amazon QuickSight.
Utilice el método embedDashboard para insertar un panel de QuickSight. Devuelve una promesa de tipo 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 > > ;
}