Signed Embedの設定方法

外部サービスにNotebookをシームレスに統合します。

設定方法

統合の準備

• API KeyとSecretの準備

  • "Workspace settings"を開き、"API Keys"メニューをクリックします。

  • "New API Key"ボタンをクリックして新しいAPI Keyを作成します。

  • API KeyとAPI Secret（後でAPIコールに使用します）をメモしておきます。

• Notebookを開く

  • 共有したいNotebookを開きます。

  • ヘッダーの"Share"ボタンをクリックし、"Integration"を選択します。

• ページの選択

  • 公開したいページを選択します。

• 公開

  • "Publish"ボタンをクリックします。

• 統合設定の構成

  • "Permitted API Keys"セクションで使用するAPI Keyを追加します。

  • APIを通じてパラメータ値を上書きしたい場合は、Externalized Paramsセクションで設定します。

サーバーからトークンを発行する

• トークンを発行するには以下のAPIを使用します

  • APIを呼び出すために必要な引数は"Setup guide"タブで確認できます。

  • API Secretが外部に漏れないようにするため、サーバーサイドでAPIコールを実行してください。

  • ユーザーセッションごとにトークンを発行し、再利用しないでください（1時間後に期限切れになります）。

post

本文

api_keystring · 最小: 24 · 最大: 24必須

API Key. Can be issued from 'Workspace settings > API Keys'

Example: 6729a28bc7100424ad4e2e5d

api_secretstring · 最小: 32 · 最大: 32必須

API Secret. Generated when issuing 'API Key'

Example: c711defdff5f4e3e8e53d4f408579b9a

integration_idstring · 最小: 24 · 最大: 24必須

Integration ID. Can be obtained from the signed embed settings

Example: 671ef14b0d08cf6c657df7da

page_idstring · 最小: 24 · 最大: 24必須

Page ID to be displayed in the notebook. Can be obtained from the signed embed settings

Example: 671ecbbf2990c63fea3b3a26

token_user_idstring · 最小: 1必須

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.

paramsobject[]必須

Externalized parameter values. Can be configured in the signed embed settings

expires_ininteger · 最小: 1 · 最大: 86400オプション

Token expiration time in seconds. Default is 3600 seconds (1 hour)

Example: 3600

cache_max_ageinteger · 最大: 86400オプション

Cache max age in seconds. Default is 86400 (24 hours)

Example: 86400

レスポンス

application/json

objectオプション

application/json

application/json

post

HTTPcURLJavaScriptPython

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の埋め込み

Integration URLを使用してHTMLをサービスに埋め込みます。 トークンと一緒に表示オプションを設定できます。詳細については"Setup guide"を確認してください。

[推奨] パターン1. postMessageを介したトークンの受け渡し

1. Integration URLをsrc属性としたiframe要素を作成します

2. postMessageを介してiframeから{type: "READY_FOR_TOKEN"}メッセージを待ちます

3. 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';
const token = '{{ TOKEN_HERE }}';  // 発行されたトークンをここに
const displayOptions = {
  "theme": "LIGHT",
  "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パラメータを介したトークンの受け渡し

1. Integration URLにクエリパラメータとしてトークンを追加します（?token=xxx）

2. オプションでdisplayOptionsをクエリパラメータとして追加します （値はencodeURIComponent(JSON.stringify(displayOptions))である必要があります）

3. 修正されたURLをsrc属性としたiframe要素を作成します

// サンプル

<iframe
  src="https://app.codatum.com/protected/workspace/xxx/notebook/xxx?token={{ TOKEN_HERE }}&displayOptions={{ ENCODED_DISPLAY_OPTIONS_HERE }}"
  allow="fullscreen; clipboard-write" 
/>

付録：メッセージ一覧

iframeのpostMessage機能を使用してメッセージを交換できます。

• メッセージはconsole.debug()にも出力されるため、実際のメッセージ内容をそこで確認できます。

• 例えば、この機能は以下のような用途に使用できます：

  • ユーザーによって変更されたパラメータ情報を永続化する。

  • 異なる統合やページ間でパラメータを共有する。

送受信できるメッセージの一覧は以下の通りです。

iframeへのメッセージ

type	description
SET_TOKEN	認証トークンを設定し、Notebookのレンダリングを開始します。このメッセージはREADY_FOR_TOKENメッセージを受信した後に送信する必要があります。 {type: "SET_TOKEN", token: "..."}

iframeからのメッセージ

type	description
READY_FOR_TOKEN	Notebookがトークンを受信する準備ができたことを通知します。 {type: "READY_FOR_TOKEN"}
PARAM_CHANGED	ユーザーがNotebook内のパラメータを変更するたびに送信されます。 { type: "PARAM_CHANGED", params: [ { param_id: "662a5e9fce6482ca0231f06f", param_value: "\"Hello codatum\"" }, ] }
EXECUTE_SQLS_TRIGGERED	Notebook内で「すべて実行」が実行されたときに送信されます。 { type: "EXECUTE_SQLS_TRIGGERED", params: [ { param_id: "662a5e9fce6482ca0231f0aa", param_value: "123" } ] }