أمازون Quicksight تضمين SDK
1.0.0
نشكرك على استخدام Amazon QuickSight JavaScript SDK. يمكنك استخدام SDK هذا لتضمين Amazon QuickSight في HTML الخاص بك.
لمزيد من المعلومات ومعرفة كيفية استخدام QuickSight Embedding، يرجى زيارة موقع بوابة مطور QuickSight
يقدم Amazon QuickSight أربع تجارب تضمين مختلفة مع خيارات لعزل المستخدم بمساحات الأسماء وأذونات واجهة المستخدم المخصصة.
الخيار 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 طرق للتجربة
تأخذ هذه الطرق معلمتين:
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 في دليل مستخدم 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 لتصبح 0 بكسل، نظرًا لأن تعيين الحدود والمساحة في إطار 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 المدعوم:
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 لجميع تجارب التضمين يمكنك ضبط الإعدادات المحلية لجلسة 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 > > ;
}