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

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

設定方法

署名付き埋め込みの準備

APIキーとAPIシークレットの準備
- ワークスペース設定を開き、APIキーメニューをクリックします。
- APIキーを追加ボタンをクリックして新しいAPIキーを作成します。
- APIキーとAPIシークレット（後でAPIコールに使用します）をメモしておきます。
ノートブックを開く
- 共有したいノートブックを開きます。
- ヘッダーの共有ボタンをクリックし、署名付き埋め込みタブを選択します。
署名付き埋め込みの公開
- 公開対象のページの選択や、公開時のオプションを設定します。
- 公開ボタンをクリックします。
署名付き埋め込みの設定
- 権限を付与するAPIキーセクションで使用するAPIキーを追加します。
- サーバーサイドでのトークン発行時に値を指定するパラメータを、サーバーサイドパラメータセクションで設定します。

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

トークンを発行するには以下のAPIを使用します
- APIを呼び出すために必要な引数は セットアップガイドタブで確認できます。
- APIシークレットが外部に漏れないようにするため、サーバーサイドで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.

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

レスポンス

200

Generated token

application/json

400

Bad request

application/json

401

Unauthorized

application/json

post

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 }}", ...clientSideOptions}メッセージをiframeに送り返します
- clientSideOptions には、パラメータの初期値等の設定を指定できます。詳細については付録を参照してください。

// サンプル

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 clientSideOptions = {
  displayOptions: {
    sqlDisplay: "SHOW" | "RESULT_ONLY" | "HIDE",  // 
    expandParamsFormByDefault: false
  },
  params: [
    {
      param_id: "686d820209183cfa1045cb81",
      param_value: "\"Hello codatum\""  // JSON.stringify("Hello codatum")
    },
  ]
};

// 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,
      ...clientSideOptions,
    };    
    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）
clientSideOptionsをクエリパラメータとして追加（オプション）（各キーに対して値を encodeURIComponent(JSON.stringify(value)) で生成して付与）
URLをsrc属性とするiframe要素を作成します

// URL生成のサンプルコード
const signedEmbedUrl = 'https://app.cdm.test/protected/workspace/6653ebab5a1acaa5bd5422a5/notebook/686d823e586c271be1472207?theme=LIGHT&locale=ja';
const token = '{{ TOKEN_HERE }}';
const clientSideOptions = {
  displayOptions: {
    sqlDisplay: "RESULT_ONLY",
    expandParamsFormByDefault: false
  },
  params: [
    {
      param_id: "686d820209183cfa1045cb81",
      param_value: "\"Hello codatum\""  // JSON.stringify("Hello codatum")
    },
  ]
};

const url = new URL(signedEmbedUrl);
url.searchParams.append('token', token);
for (const [key, value] of Object.entries(clientSideOptions)) {
  const encodedValue = encodeURIComponent(JSON.stringify(value));
  url.searchParams.append(key, encodedValue);
}

const generatedUrl = url.toString();

<!-- サンプルHTML -->
<iframe src="{{ GENERATED_URL_HERE }}" allow="fullscreen; clipboard-write" />

付録

クライアントサイドオプション

「iframeの埋め込み」の際に渡すことができる、クライアントサイドオプション(clientSideOptions)には以下のような項目があります。

key

description

displayOptions.sqlDisplay

SQL表示オプションを指定します。

"SHOW": SQLブロックとビルド済SQLを表示します "RESULT_ONLY": SQLブロック内のSQL部分とビルド済SQLを非表示にします "HIDE": SQLブロックとビルド済SQLを非表示にします

displayOptions.hideParamsForm

パラメータフォームを非表示にする場合にtrueを指定します。

displayOptions.expandParamsFormByDefault

デフォルトでパラメータフォームを開く場合にtrueを指定します。hideParamsFormがtrueの場合は無視されます。

params[]

クライアントサイドパラメータの初期値を指定します。ここで初期値の指定されなかったクライアントサイドパラメータは、署名付き埋め込みの公開時に設定されていたパラメータの値が初期値として使用されます。

params[].param_id

パラメータのIDを指定します。

params[].param_value

パラメータの値を指定します。パラメータの値は、JSON.stringify()で文字列に変換して指定してください。

パラメータの値に、"_RESET_TO_DEFAULT_"を指定することで、署名付き埋め込みの公開時にパラメータに設定されていたデフォルト値を初期値として使用できます。\ 相対日付によるデフォルト値の解決も行われます。

params[].is_hidden

パラメータの入力フォームを非表示にする場合にtrueを指定します。hideParamsFormがtrueの場合は無視されます。

クライアントサイドオプションの設定例を以下に示します。

const clientSideOptions = {
  displayOptions: {
    sqlDisplay: "RESULT_ONLY",
    hideParamsForm: true
  },
  params: [
    {
      param_id: "686d820209183cfa1045cb81",
      param_value: "\"Hello codatum\""  // JSON.stringify("Hello codatum")
    },
    {
      param_id: "686d820209183cfa1045cb82",
      param_value: "_RESET_TO_DEFAULT_"  // 署名付き埋め込みの公開時に設定されていたデフォルト値を使用
    },
    {
      param_id: "686d820209183cfa1045cb83",
      param_value: "\"2025-01-01\""  // JSON.stringify("2025-01-01")
    },
    {
      param_id: "686d820209183cfa1045cb84",
      param_value: "[\"2025-01-01\", \"2025-01-02\"]"  // JSON.stringify(["2025-01-01", "2025-01-02"])
    },
    {
      param_id: "686d820209183cfa1045cb85",
      param_value: "123"  // JSON.stringify(123)
    }
  ]
};

メッセージ一覧

「iframeの埋め込み」でパターン1による実装を行った場合、iframeのpostMessage機能を使用してメッセージを交換できます。以下に、送受信できるメッセージの一覧を示します。

iframeへのメッセージ

type

description

SET_TOKEN

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

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

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

{
  type: "SET_TOKEN",
  token: "...",
  displayOptions: {
    "sqlDisplay": "SHOW",
    "expandParamsFormByDefault": false
  },
  params: [
    {
      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"
        }
    ]
}

よくある質問

トークン発行時に "Missing param: xxx" エラーが出る場合

トークン発行時には、全てのサーバーサイドパラメータをリクエスト内に含める必要があります
"xxx" というパラメータIDのパラメータがリクエスト内に含まれていない場合、このエラーが発生します

SET_TOKENメッセージの送信時に "The following parameters must be set by the server" エラーが出る

SET_TOKENの際にサーバーサイドパラメータを変更しようとしています
サーバーサイドパラメータを変更するためには、新しいトークン発行が必要です

SET_TOKENメッセージを送信してもパラメータが変更されない場合

送信したパラメータがサーバーサイドパラメータとして指定されていないか確認
param_valueが正しいJSON文字列形式か確認
param_idが実在するパラメータIDと一致しているか確認

前へ署名付き埋め込み次へユースケース

最終更新 1 か月前

役に立ちましたか？