> For the complete documentation index, see [llms.txt](https://docs.codatum.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codatum.jp/external-integrations/signed-embed-light.md).

# Signed Embed Light セットアップガイド

## 概要

**Signed Embed Light** を使用することで、Codatumで作成したダッシュボードやノートブックを、KARTEのDatahub上に「Codatum BI」として埋め込み活用することができます。埋め込まれたコンテンツはトークンベースで認証され、セキュアに表示されます。

Datahubの閲覧権限があるKARTEアカウントで、Codatumにアクセスせずともダッシュボードを閲覧できます。

## 設定方法

### Codatum側での準備

* APIキーとAPIシークレット、ワークスペースIDを取得する
  * `ワークスペース設定`を開きます（画面左下の歯車アイコンをクリック）
  * `APIキー`メニューをクリックします
  * `APIキーを追加`ボタンをクリックして新しいAPIキーを作成します
    * **APIキー**と**APIシークレット**が生成されます。両方の値を後ほど使用します
  * `基本設定`メニューでワークスペースIDを確認します（KARTE側で使用します）
* ノートブックを公開設定にする
  * 埋め込みたいノートブックを開きます
  * ヘッダーの`共有`ボタンをクリックし、`署名付き埋め込み`タブを選択します
  * `署名付き埋め込みを作成`をクリックします
  * `公開ページの選択`や`公開時のオプション`を設定します（どのページをKARTEに埋め込むかを指定します）
    * KARTEの管理画面上からデータソースをCSV形式で「ダウンロード」する機能の有効化
    * GUIで探索できる「エクスプローラ」機能の有効化
    * ※ パラメータなどの設定は不要です
  * `公開`ボタンをクリックします
  * 設定タブの`権限を付与するAPIキー`セクションで、先ほど作成したAPIキーを追加します
    * 埋め込み先でパラメータを活用する場合は、パラメータも追加します
* インテグレーションIDとページIDを確認する
  * 同じ画面の`セットアップガイド`タブをクリックします
  * **インテグレーションID**と**ページID**を確認・メモします（KARTE側で必要になります）

確認済み情報のメモ例:

```
ワークスペースID: codatum123456
インテグレーションID: 123456codatum
ページID: 123codatum456
APIキー: xxxxxxxxxxxxxxxx
APIシークレット: xxxxxxxxxxxxxxxxxxxxxxxx
```

### KARTE側での設定

* Codatum APIキーをKARTEに登録する（初回のみ）
  * KARTEの`Datahub`を開き、`Codatum BI`セクションに移動します
  * `APIキー`ボタン、続けて`作成`ボタンをクリックします
  * 以下を入力します
    * **名前**: 任意の名前（例：「プロダクション」「テスト環境」）
    * **APIキー**: Codatum側で取得したAPIキー
    * **APIシークレット**: Codatum側で取得したAPIシークレット
  * ダイアログを閉じます
* ノートブックをKARTEに追加する
  * `Codatumノートブックを追加`ボタンをクリックします
  * ダイアログに以下を入力します

    | 項目          | 説明                  | 入力例                        |
    | ----------- | ------------------- | -------------------------- |
    | ダッシュボード名    | KARTE内に表示される名前      | 「月間売上分析」                   |
    | 説明          | 簡単な説明（一覧に表示）        | 「売上推移とセグメント分析」             |
    | APIキー       | 登録したAPIキーをプルダウンから選択 | 「プロダクション」など                |
    | インテグレーションID | Codatum側で確認した値      | `6a0be605b82c28cfca0a3b87` |
    | ワークスペースID   | Codatum側で確認した値      | `68f6cf4aa62ec85afb3525bc` |
    | ページID       | Codatum側で確認した値      | `68f6cf4aa62ec85afb3525bc` |
  * `作成`ボタンをクリックすると、ダッシュボード一覧に追加されます
    * ダッシュボード名をクリックするとコンテンツが表示されます

## 開発者向け補足

### サーバーサイドでのトークン発行

フロントエンドで Codatum Embed SDK を使用する場合、以下の API エンドポイントからサーバーサイドでトークンを発行する必要があります。

**エンドポイント**

```
POST https://api.codatum.com/api/notebook/issueToken
```

**リクエスト例**

```json
{
  "api_key": "6729a28bc7100424ad4e2e5d",
  "api_secret": "c711defdff5f4e3e8e53d4f408579b9a",
  "integration_id": "671ef14b0d08cf6c657df7da",
  "page_id": "671ecbbf2990c63fea3b3a26",
  "token_user_id": "user123",
  "params": [
    {
      "param_id": "6722c7061b02448a4056d84d",
      "param_value": "\"Hello world\""
    }
  ],
  "expires_in": 3600,
  "cache_max_age": 86400
}
```

**レスポンス例**

```json
{
  "token": "(Generated-token)"
}
```

**パラメータ説明**

| パラメータ            | 説明                                |
| ---------------- | --------------------------------- |
| `api_key`        | Codatum APIキー                     |
| `api_secret`     | Codatum APIシークレット                 |
| `integration_id` | インテグレーションID（署名付き埋め込み設定で確認）        |
| `page_id`        | ページID（署名付き埋め込み設定で確認）              |
| `token_user_id`  | 埋め込み対象のユーザーID（KARTEのユーザーIDなど）     |
| `params`         | サーバーサイドで設定するパラメータ（オプション）          |
| `expires_in`     | トークン有効期限（秒）。デフォルト：3600秒（1時間）      |
| `cache_max_age`  | キャッシュ最大有効期間（秒）。デフォルト：86400秒（24時間） |

{% hint style="warning" %}
APIシークレットは外部に漏らさないよう、必ずサーバーサイドで実行してください。
{% endhint %}

### フロントエンドでの組み込み

[Codatum Embed SDK](https://github.com/codatum/codatum-embed-js) を使用してフロントエンドに組み込みます。詳細は[SDKのREADME](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme)を参照してください。

## 付録

### よくある質問

#### インテグレーションIDってなんですか？

Codatumで、このノートブックを外部に公開するための識別子です。署名付き埋め込み設定時に自動生成されます。

#### ワークスペースIDとページIDは同じですか？

異なります。

* **ワークスペースID**: あなたのCodatumワークスペース（組織）を識別するID
* **ページID**: 埋め込みたいノートブックの特定ページを識別するID

#### 複数のノートブックを埋め込めますか？

はい。「KARTE側での設定」の手順を繰り返すことで、複数のノートブックを埋め込めます。

#### APIシークレットを失くしてしまいました

新しいAPIキーを作成し直す必要があります。Codatumの`ワークスペース設定`＞`APIキー`から古いキーを削除し、新しいものを作成してください。

#### IDを間違えて入力してしまいました

KARTE側で該当ダッシュボードを削除して、新しく作成し直してください。正しいIDを確認してから再度設定します。

#### 「指定されたインテグレーション ID が見つかりません」エラーが出る場合

* Codatum側で該当ノートブックが公開状態になっているか確認してください
* `署名付き埋め込み`＞`セットアップガイド`でインテグレーションIDが正しく表示されているか確認してください
* KARTE側で入力したIDが正確か再度確認してください

#### ダッシュボードが表示されない場合

APIキーの認証に失敗している可能性があります。

* KARTE側のAPIキー設定で、APIキーとAPIシークレットが正確に入力されているか確認してください
* Codatum側でそのAPIキーが削除されていないか確認してください
* 必要に応じてAPIキーを作成し直してください


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.codatum.jp/external-integrations/signed-embed-light.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.