署名付き埋め込みの設定方法

外部サービスにノートブックをシームレスに統合します。

設定方法

統合の準備

APIキーとAPIシークレットの準備
- 「ワークスペース設定」を開き、「APIキー」メニューをクリックします。
- 「新規APIキー」ボタンをクリックして新しいAPIキーを作成します。
- APIキーとAPIシークレット（後でAPIコールに使用します）をメモしておきます。
ノートブックを開く
- 共有したいノートブックを開きます。
- ヘッダーの「共有」ボタンをクリックし、「署名付き埋め込み」を選択します。
ページの選択
- 公開したいページを選択します。
公開
- 「公開」ボタンをクリックします。
統合設定の構成
- 「権限を付与するAPIキー」セクションで使用するAPIキーを追加します。
- APIを通じてパラメータ値を上書きしたい場合は、外部化パラメータセクションで設定します。

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

トークンを発行するには以下のAPIを使用します
- APIを呼び出すために必要な引数は"Setup guide"タブで確認できます。
- APIシークレットが外部に漏れないようにするため、サーバーサイドでAPIコールを実行してください。
- ユーザーセッションごとにトークンを発行し、再利用しないでください（1時間後に期限切れになります）。

iframeの埋め込み

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

[推奨] パターン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';
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へのメッセージ

type

description

SET_TOKEN

認証トークンを設定し、ノートブックのレンダリングを開始します。このメッセージはREADY_FOR_TOKENメッセージを受信した後に送信する必要があります。

このメッセージは同じiframeに複数回送信することができ、その場合iframeは新しいトークンとパラメータで内部的にリロードされます。

parametersフィールドを使用すると、サーバーサイドで固定化やデフォルト設定されていないパラメータの初期値を設定できます。これは、アプリケーション側でパラメータ入力欄を提供したい場合に便利です。

iframeからのメッセージ

type

description

READY_FOR_TOKEN

ノートブックがトークンを受信する準備ができたことを通知します。

PARAM_CHANGED

ユーザーがノートブック内のパラメータを変更するたびに送信されます。

EXECUTE_SQLS_TRIGGERED

ノートブック内で「すべて実行」が実行されたときに送信されます。

前へ署名付き埋め込み次へアカウント

最終更新 13 時間前

役に立ちましたか？

署名付き埋め込みの設定方法

外部サービスにノートブックをシームレスに統合します。

設定方法

統合の準備

APIキーとAPIシークレットの準備
- 「ワークスペース設定」を開き、「APIキー」メニューをクリックします。
- 「新規APIキー」ボタンをクリックして新しいAPIキーを作成します。
- APIキーとAPIシークレット（後でAPIコールに使用します）をメモしておきます。
ノートブックを開く
- 共有したいノートブックを開きます。
- ヘッダーの「共有」ボタンをクリックし、「署名付き埋め込み」を選択します。
ページの選択
- 公開したいページを選択します。
公開
- 「公開」ボタンをクリックします。
統合設定の構成
- 「権限を付与するAPIキー」セクションで使用するAPIキーを追加します。
- APIを通じてパラメータ値を上書きしたい場合は、外部化パラメータセクションで設定します。

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

トークンを発行するには以下のAPIを使用します
- APIを呼び出すために必要な引数は"Setup guide"タブで確認できます。
- APIシークレットが外部に漏れないようにするため、サーバーサイドでAPIコールを実行してください。
- ユーザーセッションごとにトークンを発行し、再利用しないでください（1時間後に期限切れになります）。

iframeの埋め込み

[推奨] パターン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';
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へのメッセージ

type

description

SET_TOKEN

このメッセージは同じiframeに複数回送信することができ、その場合iframeは新しいトークンとパラメータで内部的にリロードされます。

{
  type: "SET_TOKEN",
  token: "...",
  displayOptions: {
    "sqlDisplay": "SHOW",
    "expandParamsFormByDefault": false
  },
  parameters: [
    {
      param_id: "662a5e9fce6482ca0231f06f",
      param_value: "\"Hello codatum\""
    }
  ]
}

iframeからのメッセージ

type

description

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"
        }
    ]
}

前へ署名付き埋め込み次へアカウント

最終更新 13 時間前

役に立ちましたか？