署名付き埋め込みの設定方法
外部サービスにノートブックをシームレスに統合します。
設定方法
統合の準備
APIキーとAPIシークレットの準備
ワークスペース設定
を開き、APIキー
メニューをクリックします。APIキーを追加
ボタンをクリックして新しいAPIキーを作成します。APIキーとAPIシークレット(後でAPIコールに使用します)をメモしておきます。
ノートブックを開く
共有したいノートブックを開きます。
ヘッダーの
共有
ボタンをクリックし、署名付き埋め込み
タブを選択します。
ページの選択
公開したいページを選択します。
公開
公開
ボタンをクリックします。
統合設定の構成
権限を付与するAPIキー
セクションで使用するAPIキーを追加します。APIを通じてパラメータ値を上書きしたい場合は、
外部化パラメータ
セクションで設定します。
サーバーからトークンを発行する
トークンを発行するには以下のAPIを使用します
APIを呼び出すために必要な引数は
セットアップガイド
タブで確認できます。APIシークレットが外部に漏れないようにするため、サーバーサイドでAPIコールを実行してください。
ユーザーセッションごとにトークンを発行し、再利用しないでください(1時間後に期限切れになります)。
API Key. Can be issued from 'Workspace settings > API Keys'
6729a28bc7100424ad4e2e5d
API Secret. Generated when issuing 'API Key'
c711defdff5f4e3e8e53d4f408579b9a
Integration ID. Can be obtained from the signed embed settings
671ef14b0d08cf6c657df7da
Page ID to be displayed in the notebook. Can be obtained from the signed embed settings
671ecbbf2990c63fea3b3a26
Specify the user ID within the application where the notebook is embedded. Ensure that the token can uniquely identify the token user for security reason.
Token expiration time in seconds. Default is 3600 seconds (1 hour)
3600
Cache max age in seconds. Default is 86400 (24 hours)
86400
POST /api/notebook/issueToken HTTP/1.1
Host: api.codatum.com
Content-Type: application/json
Accept: */*
Content-Length: 313
{
"api_key": "6729a28bc7100424ad4e2e5d",
"api_secret": "c711defdff5f4e3e8e53d4f408579b9a",
"integration_id": "671ef14b0d08cf6c657df7da",
"page_id": "671ecbbf2990c63fea3b3a26",
"token_user_id": "text",
"params": [
{
"param_id": "6722c7061b02448a4056d84d",
"param_value": "\"Hello world\""
}
],
"expires_in": 3600,
"cache_max_age": 86400
}
{
"token": "(Generated-token)"
}
iframeの埋め込み
署名付き埋め込みURL
を使用してHTMLをサービスに埋め込みます。
トークンと一緒に表示オプションを設定できます。詳細については セットアップガイド
を確認してください。
[推奨] パターン1. トークンを postMessage で渡す
署名付き埋め込みURL
をsrc属性としたiframe要素を作成しますpostMessageを介してiframeから
{type: "READY_FOR_TOKEN"}
メッセージを待ちますpostMessageを介して
{type: "SET_TOKEN", token: "{{ TOKEN_HERE }}"}
メッセージをiframeに送り返します (オプションでdisplayOptions
も送信できます)
// サンプル
const NOTEBOOK_ORIGIN = 'https://app.codatum.com';
const ingegrationUrl = 'https://app.codatum.com/protected/workspace/xxx/notebook/xxx?theme=LIGHT&locale=ja';
const token = '{{ TOKEN_HERE }}'; // 発行されたトークンをここに
const displayOptions = {
"sqlDisplay": "SHOW",
"expandParamsFormByDefault": false
};
// iframeウィンドウの参照を保存
let notebookWindow: Window | null = null;
// iframeの作成と挿入
function createDashboard(containerId: string) {
const container = document.getElementById(containerId);
if (!container) return;
const iframe = document.createElement('iframe');
iframe.src = ingegrationUrl;
iframe.allow = 'fullscreen;clipboard-write';
container.appendChild(iframe);
notebookWindow = iframe.contentWindow;
}
// iframeからのメッセージを処理
function handleMessage(event: MessageEvent<{type: 'READY_FOR_TOKEN'}>): void {
// オリジンとソースを検証
if (event.origin !== NOTEBOOK_ORIGIN || event.source !== notebookWindow) {
return;
}
// iframeの準備ができたらトークンを送信
if (event.data.type === 'READY_FOR_TOKEN') {
const message = {
type: 'SET_TOKEN',
token: token,
displayOptions: displayOptions
};
notebookWindow?.postMessage(message, NOTEBOOK_ORIGIN);
}
}
function cleanup() {
window.removeEventListener('message', handleMessage);
notebookWindow = null;
}
export function createEmbeddedNotebook(containerId: string) {
window.addEventListener('message', handleMessage);
createDashboard(containerId);
return cleanup;
}
パターン2. トークンをURLパラメータで渡す
署名付き埋め込みURL
にクエリパラメータとしてトークンを追加します(?token=xxx
)オプションで
displayOptions
をクエリパラメータとして追加します (値はencodeURIComponent(JSON.stringify(displayOptions))
で生成)URLをsrc属性とするiframe要素を作成します
// サンプル
<iframe
src="https://app.codatum.com/protected/workspace/xxx/notebook/xxx?theme=LIGHT&token={{ TOKEN_HERE }}&displayOptions={{ ENCODED_DISPLAY_OPTIONS_HERE }}"
allow="fullscreen; clipboard-write"
/>
付録:メッセージ一覧
iframeのpostMessage機能を使用してメッセージを交換できます。
メッセージは
console.debug()
にも出力されるため、実際のメッセージ内容をそこで確認できます。例えば、この機能は以下のような用途に使用できます:
ユーザーによって変更されたパラメータ情報を永続化する。
異なる統合やページ間でパラメータを共有する。
送受信できるメッセージの一覧は以下の通りです。
iframeへのメッセージ
SET_TOKEN
認証トークンを設定し、ノートブックのレンダリングを開始します。このメッセージはREADY_FOR_TOKEN
メッセージを受信した後に送信する必要があります。
このメッセージは同じiframeに複数回送信することができ、その場合iframeは新しいトークンとパラメータで内部的にリロードされます。
parameters
フィールドを使用すると、サーバーサイドで固定化やデフォルト設定されていないパラメータの初期値を設定できます。これは、アプリケーション側でパラメータ入力欄を提供したい場合に便利です。
{
type: "SET_TOKEN",
token: "...",
displayOptions: {
"sqlDisplay": "SHOW",
"expandParamsFormByDefault": false
},
parameters: [
{
param_id: "662a5e9fce6482ca0231f06f",
param_value: "\"Hello codatum\""
}
]
}
iframeからのメッセージ
READY_FOR_TOKEN
ノートブックがトークンを受信する準備ができたことを通知します。
{type: "READY_FOR_TOKEN"}
PARAM_CHANGED
ユーザーがノートブック内のパラメータを変更するたびに送信されます。
{
type: "PARAM_CHANGED",
params: [
{
param_id: "662a5e9fce6482ca0231f06f",
param_value: "\"Hello codatum\""
},
]
}
EXECUTE_SQLS_TRIGGERED
ノートブック内で「すべて実行」が実行されたときに送信されます。
{
type: "EXECUTE_SQLS_TRIGGERED",
params: [
{
param_id: "662a5e9fce6482ca0231f0aa",
param_value: "123"
}
]
}
最終更新
役に立ちましたか?