アマゾンクイックサイト埋め込みSDK
1.0.0
Amazon QuickSight JavaScript SDK をご利用いただきありがとうございます。この SDK を使用して、Amazon QuickSight を HTML に埋め込むことができます。
QuickSight 埋め込みの詳細および使用方法については、QuickSight 開発者ポータル Web サイトをご覧ください。
Amazon QuickSight は、名前空間によるユーザー分離のオプションとカスタム UI 権限を備えた 4 つの異なる埋め込みエクスペリエンスを提供します。
オプション 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 埋め込み 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型の Promise を返します。
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の共通プロパティこれは、埋め込み用の QuickSight API オペレーションを使用して生成した埋め込み URL です。
『Amazon QuickSight ユーザーガイド』の「QuickSight API を使用した埋め込み」に従って URL を生成します。
エクスペリエンスごとに、埋め込まれたエクスペリエンスを表示するために必要な権限がユーザーに付与されていることを確認する必要があります。
これは、QuickSight を埋め込む親 HTMLElement です。
HTMLElement にすることもできます。
container: document . getElementById ( "experience-container" )または、クエリ セレクター文字列にすることもできます。
container: "#experience-container" 埋め込まれた QuickSight エクスペリエンスを保持する iframe のwidthを設定できます。固定値に設定できます。
width: "1000px"または、相対値:
width: "60%"埋め込まれた QuickSight エクスペリエンスの応答性を高めるには、設定しないでください (デフォルトの100%のままにしておきます)。次に、コンテナー HTMLElement を画面サイズの変更に応答できるようにすることができます。
埋め込まれた QuickSight エクスペリエンスを保持する iframe のheight設定できます。固定値に設定できます。
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 セッションにボーダーとパディングを設定する必要がある場合は、iframe を含むコンテナ div に設定します。
埋め込みエクスペリエンス 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
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 ユーザーガイド』の「埋め込み分析の使用」を参照してください。
QuickSight ダッシュボードを埋め込むには、 embedDashboardメソッドを使用します。 DashboardExperienceタイプの Promise を返します。
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 > > ;
}