# Treasure Data CDP連携

Treasure AI Voiceは、組織の録音、文字起こし、AI生成の要約、デバイスインベントリを自社の[Treasure Data CDP](/ja/products/customer-data-platform)データベースに直接プッシュできます。データがCDPに取り込まれると、他の顧客データと結合してセグメントの作成やジャーニーの実行が可能になり、会議や通話で実際に話された内容を分析できます。

この連携は**プッシュ型かつオンデマンド**です。管理者がAI Voice Consoleからエクスポートを実行すると、Treasure AI Voiceが選択したデータのスナップショットを指定したテーブルにストリーミングします。管理すべき常設パイプラインはなく、データが中間の場所に保存されることもありません。APIキーはその1回の実行を認証するためだけに使用され、保存・永続化されることはありません。

利用できるユーザー
Treasure Data CDPエクスポートは**エンタープライズ管理者**のみが利用でき、表示される前に組織で有効化する必要があります。下記の[連携を有効化する](#enabling-the-integration)を参照してください。

## エクスポートされるデータ

各エクスポートは、CDPデータベース内の4つの論理テーブルに書き込みます。`recordings`、`transcript_segments`、`summaries`テーブルはその実行の対象範囲の録音を反映し、`devices`テーブルは選択した日付範囲に関わらず常に組織の全デバイスインベントリを反映します。

録音は処理ステータスに関わらず含まれます。`status`列が各録音の状態を反映し、まだ文字起こしや要約が完了していない録音では`transcription_text`、`summary_text`および関連フィールドは空になります。

| テーブル | 内容 | 粒度 |
|  --- | --- | --- |
| **`recordings`** | 録音ごとに1行: メタデータ、話者ラベル付きの完全な文字起こし、AI要約、アクションアイテム。 | 録音ごとに1行 |
| **`transcript_segments`** | 文字起こしを個々のタイムスタンプ付き発話に分割したもの。話者の帰属とセグメントごとの言語検出を含みます。 | 発話ごとに1行 |
| **`summaries`** | AI生成の要約とアクションアイテムを、結合しやすいよう分離したもの。要約がある録音のみ行が生成されます。 | 要約された録音ごとに1行 |
| **`devices`** | 組織のPLAUDデバイスフリート: 割り当て、ステータス、ファームウェア、最終確認タイムスタンプ。 | デバイスごとに1行 |


すべての行には、ソースレコードから導出された安定した`uuid`が付与されます。同じレコードは常に同じ`uuid`にマッピングされるため、重複する日付範囲でエクスポートを再実行しても、CDP内で`uuid`を基準に重複排除する（例: `uuid`ごとに最新の行を保持する）ことで、重複を作らずに状態を更新できます。

すべての行には`time`列（Unixエポック秒）も付与され、Treasure Data CDPがネイティブの時間パーティショニングに使用します。これによりアナリストは時間で効率的にフィルタリングできます。`time`値は各テーブルで最も意味のあるタイムスタンプに紐付けられます — `recordings`と`summaries`は`recorded_at`、セグメントは発話の開始、デバイスは最終ハートビート（報告がない場合はプロビジョニング時刻）です。

## スキーマリファレンス

スキーマはTreasure AI Voiceが管理します。列は最初の書き込み時にCDPテーブルに追加されるため、事前に宣言する必要はありません。

### `recordings`

| 列 | 型 | 説明 |
|  --- | --- | --- |
| `time` | long | `recorded_at`のUnixエポック秒。時間パーティショニングに使用されます。 |
| `uuid` | string | この録音行の安定した識別子。これを基準に重複排除します。 |
| `id` | string | 録音ID（他のテーブルの`recording_id`と一致）。 |
| `organization_id` | string | 組織の識別子。 |
| `recorded_at` | string | 録音がキャプチャされた日時のISO 8601タイムスタンプ。 |
| `user_email` | string | 録音を作成したメンバーのメールアドレス。 |
| `user_name` | string | 録音を作成したメンバーの表示名。 |
| `file_name` | string | 録音の元のファイル名。 |
| `duration_seconds` | long | 録音の長さ（秒）。 |
| `status` | string | 処理ステータス（例: `COMPLETED`）。 |
| `transcription_language` | string | 文字起こしで検出された主要言語。 |
| `transcription_text` | string | 完全な文字起こし。話者ラベル付き・話者ごとにグループ化されたテキストとしてレンダリングされ、管理者がAI Voice Consoleで録音を開いたときに表示されるものと同じ形式です。 |
| `summary_text` | string | 録音のAI生成要約。 |
| `action_items` | array<string> | AIが抽出したアクションアイテム。 |
| `inferred_name` | string | AIが推測した録音のタイトル。 |
| `tags` | array<string> | 録音に適用されたタグ。 |
| `device_serial_number` | string | 録音のキャプチャに使用されたPLAUDデバイスのシリアル番号。 |
| `team_id` | string | 録音が関連付けられているチームの識別子（ある場合）。 |


### `transcript_segments`

| 列 | 型 | 説明 |
|  --- | --- | --- |
| `time` | long | 録音内のセグメント開始オフセットのUnixエポック秒。 |
| `uuid` | string | このセグメント行の安定した識別子。 |
| `recording_id` | string | 親録音のID。`recordings.id`と結合します。 |
| `organization_id` | string | 組織の識別子。 |
| `segment_index` | long | 録音内でのセグメントの位置（ゼロ始まり）。 |
| `start_ms` | long | 録音の先頭からのセグメント開始オフセット（ミリ秒）。 |
| `end_ms` | long | 録音の先頭からのセグメント終了オフセット（ミリ秒）。 |
| `speaker_id` | string | ダイアライゼーションによる生の話者識別子（例: `spk_0`）。 |
| `speaker_label` | string | AI Voice Consoleで話者名が割り当てられている場合はその名前。割り当てがない場合は空。 |
| `language` | string | セグメントで検出された言語。 |
| `language_probability` | double | セグメントの言語検出の信頼度。 |
| `text` | string | セグメントの文字起こしテキスト。 |


### `summaries`

| 列 | 型 | 説明 |
|  --- | --- | --- |
| `time` | long | `recorded_at`のUnixエポック秒。 |
| `uuid` | string | このサマリー行の安定した識別子。 |
| `recording_id` | string | このサマリーが属する録音。`recordings.id`と結合します。 |
| `organization_id` | string | 組織の識別子。 |
| `recorded_at` | string | 元の録音のISO 8601タイムスタンプ。 |
| `summary_text` | string | AI生成の要約。 |
| `action_items` | array<string> | AIが抽出したアクションアイテム。 |
| `inferred_name` | string | AIが推測した録音のタイトル。 |


### `devices`

| 列 | 型 | 説明 |
|  --- | --- | --- |
| `time` | long | 最終ハートビートのUnixエポック秒（デバイスが一度も報告していない場合はプロビジョニング時刻）。 |
| `uuid` | string | このデバイス行の安定した識別子。 |
| `serial_number` | string | デバイスのシリアル番号。 |
| `organization_id` | string | 組織の識別子。 |
| `status` | string | 現在のデバイスステータス（例: `ACTIVE`、`LOCKED`）。 |
| `device_model` | string | デバイスモデル（例: Note Pro、NotePin S）。 |
| `firmware_version` | string | 現在インストールされているファームウェアバージョン。 |
| `assigned_user_email` | string | デバイスが割り当てられているメンバーのメールアドレス。 |
| `assigned_user_name` | string | デバイスが割り当てられているメンバーの表示名。 |
| `assigned_at` | string | デバイスが割り当てられた日時のISO 8601タイムスタンプ。 |
| `provisioned_at` | string | デバイスがプロビジョニングされた日時のISO 8601タイムスタンプ。 |
| `last_heartbeat_at` | string | デバイスの直近のステータス報告のISO 8601タイムスタンプ。 |
| `last_sync_at` | string | デバイスのモバイルアプリとの直近の同期のISO 8601タイムスタンプ。 |


## 前提条件

エクスポートを実行する前に、以下を準備してください：

- Treasure AI Voiceの**エンタープライズ管理者**アカウント。
- 組織で連携が**有効化**されていること（下記参照）。
- 対象データベースに書き込める、**IMPORT**ロールを持つ**Treasure Data CDP APIキー**。
- Treasure Data CDP内の**書き込み先データベース**。エクスポートは、そのデータベース内で指定したテーブルに書き込み、最初の書き込み時にテーブルを作成します。


Masterキーではなく書き込み専用キーを使用してください
書き込み先データベースにスコープされ、**IMPORT**ロールに限定された専用の**書き込み専用APIキー**を指定してください。**Masterキーは使用しないでください** — アカウント全体へのフルアクセスを付与してしまい、エクスポートに必要な範囲をはるかに超えます。指定したキーは1回のエクスポート実行でイベントを書き込むためだけに使用され、実行中のみメモリに保持され、保存・ログ記録・読み戻しされることはありません。

エクスポートは指定したキーが到達できる任意の宛先に書き込むため、エンタープライズ管理者ロールとここで使用するキーをデータガバナンス管理の一部として扱ってください — ロールを持つ担当者と、キーが書き込めるデータベースを制限してください。

日本リージョンのみ
Treasure AI Voiceは、Treasure Data CDPの**日本（AP01）リージョン**にのみエクスポートします。書き込み先データベースが日本リージョンにあることを確認してください。他のリージョンのキーやデータベースはエクスポートを受け付けません。

## 連携を有効化する

連携は**デフォルトで無効**です。有効にするには：

1. エンタープライズ管理者としてAI Voice Consoleにサインインします。
2. **Export**ページを開きます。
3. **Treasure Data CDP**を宛先として選択します。
4. **Enable export**をクリックします。


有効化するオプションが表示されない場合は、Treasure AIの担当者までお問い合わせください。

## エクスポートを実行する

1. **Export**ページで**Treasure Data CDP**を選択した状態で、以下を入力します：
  - **API Key** — Treasure Data CDP APIキー（IMPORTロール）。
  - **Database** — 書き込み先データベース名（例: `ai_voice_export`）。
2. （任意）**Advanced**を展開してカスタマイズします：
  - **Recordings table**および**Transcript segments table**の名前（デフォルト: `recordings`、`transcript_segments`）。
  - エクスポートする録音を絞り込む**From** / **To**の日付範囲。範囲は各録音がキャプチャされた日時に適用され、**To**の日付はその日の終わりまでを含みます。
3. **Export**をクリックします。


AI Voice Consoleは、録音の読み取り、文字起こしデータの結合、Treasure Data CDPへのイベント送信の進捗を表示します。通常、実行は1分以内に完了します。

日付範囲とデバイス
**From** / **To**の範囲は録音、文字起こしセグメント、要約をフィルタリングします。**devices**スナップショットは常に全フリートを反映するため、選択した範囲に一致する録音がなくてもデバイスの行は表示されます。

## 結果を確認する

各実行は以下のいずれかの状態で完了します：

| 結果 | 意味 |
|  --- | --- |
| **完了（Done）** | 対象範囲のすべての行がTreasure Data CDPに受け入れられました。送信された録音とセグメントの件数がサマリーに表示されます。 |
| **一部拒否ありで完了（Done with some rejections）** | エクスポートは完了しましたが、Treasure Data CDPが一部の行を拒否しました。受け入れ件数と拒否件数がサマリーに表示されます。拒否された行を調査するには、監査ログまたはTreasure Data CDPのテーブルレシートを確認してください。 |
| **エクスポート対象の録音がありません（No recordings to export）** | 選択した範囲に一致するものがありませんでした — 完了済みの録音がまだないか、日付範囲ですべて除外されたかのいずれかです。（デバイススナップショットは送信される場合があります。） |
| **APIキーが拒否されました（API key rejected）** | Treasure Data CDPがAPIキーを受け付けませんでした。キーを再確認して、もう一度お試しください。 |
| **APIキーにIMPORTロールがありません（API key lacks the IMPORT role）** | キーは有効ですが、イベントを書き込めません。Treasure AI管理者にこのキーへのIMPORTロールの付与を依頼するか、書き込み先データベースにスコープされたキーを使用してください。 |
| **録音のサイズが大きすぎて送信できません（A recording is too large to send）** | 1件の録音の文字起こしがTreasure Data CDPのリクエストあたりのサイズ上限を超えたため、エクスポートが停止しました。これはまれで、異常に長い文字起こしの場合にのみ発生します。日付範囲を絞ってその録音を除外するか、Treasure AIの担当者までお問い合わせください。 |


各エクスポート実行は — その結果と行数を含めて — `TD_CDP_EXPORT`イベントタイプとして[監査ログ](/ja/products/ai-voice/administrator-guide#audit-logs)に記録されます。APIキーが監査ログに書き込まれることはありません。

## エクスポートしたデータをクエリする

各テーブルは`recording_id`（`recordings.id`）を共有しているため、CDP内で会議データの任意のビューを再構築できます。例：

- `summaries`を`recording_id`で`recordings`に結合すると、要約と完全な録音メタデータを一緒に取得できます。
- `transcript_segments`を`recording_id`で`recordings`に結合し、`segment_index`で並べ替えると、会話を発話単位で再構築・分析できます。
- `transcript_segments`を`speaker_label`（または`speaker_id`）でピボットすると、参加者ごとの発話時間を分析できます。
- `recordings`を`device_serial_number` = `serial_number`で`devices`に結合すると、会話をデバイスと割り当てられたユーザーに紐付けられます。


データの更新
CDPを最新に保つには、対象の日付範囲でエクスポートを定期的に再実行し、ダウンストリームのモデルで`uuid`を基準に重複排除してください。同じ範囲での再実行は安全です — 一致するレコードは同じ`uuid`を保持します。