# Equativ Batch File Export Integration

Treasure AI から [Equativ](https://www.equativ.com/) へ、Equativ が提供する Google Cloud Storage (GCS) バケットに CSV ファイルをエクスポートすることで、セグメントタクソノミーおよびユーザープロファイルデータを送信できます。この連携では、[Google Cloud Storage Export V2](/int/google-cloud-storage-export-v2-integration) コネクタと Equativ のバッチファイル同期サービスを使用します。

ファイルが指定バケットに到着すると Equativ が自動的に取り込むため、Treasure AI の親セグメントや Audience Studio のアクティベーションからセグメント定義とプロファイル所属を制御できます。

Equativ 側の仕様については、[Sync Segments and Profiles - Batch File](https://help.equativ.com/sync-segments-and-profiles-batch-file) を参照してください。

## 前提条件

- [TD Toolbelt](https://toolbelt.treasuredata.com/) を含む Treasure AI の基本知識。
- バッチファイル同期が有効化された Equativ アカウント。
- Equativ 担当者から提供される GCS サービスアカウント認証情報 (JSON キー) と対象バケット名。
- Equativ が要求するカラムを出力するクエリ、または Audience Studio セグメント。


バケットの選択
Equativ はタクソノミーとプロファイルそれぞれに別のバケットを用意しており、さらに環境 (sandbox/production) およびリージョン (US, EU, APAC) ごとにも異なります。接続を構成する前に、Equativ から正確なバケット名を確認してください。例:

- タクソノミー: `taxonomy_importer_audience_prod`、`taxonomy_importer_audience_sandbox`
- プロファイル: `profile_importer_audience_us_prod`、`profile_importer_audience_eu_prod`、`profile_importer_audience_apac_prod`


## Treasure Data Integration の静的 IP アドレス

セキュリティポリシーで IP ホワイトリストが必要な場合は、接続を成功させるために Treasure Data の IP アドレスを許可リストに追加する必要があります。

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります:
[IP Addresses for Integrations](/apis/endpoints/ip-addresses-integrations-result-workers)

## ファイルフォーマット概要

Equativ では、以下の特性を持つ CSV ファイルが必要です:

| プロパティ  | 値  |
|  --- | --- |
| フォーマット | CSV |
| 区切り文字 | パイプ文字 (`|`) |
| エンコーディング | UTF-8 |
| 大文字小文字の区別 | カラム値は大文字小文字を区別します |
| ヘッダ行 | 任意。含める場合は、Equativ のカラム名と完全一致する必要があります (例: `UserID`、`SegmentToAdd`)。 |
| ファイル種別の判定 | アップロード先のバケットで決まります。タクソノミーファイルはタクソノミー用バケット、プロファイルファイルはリージョンに応じたプロファイル用バケットへアップロードしてください。 |


### タクソノミーファイルのカラム

タクソノミーファイルを使って、Equativ にセグメント定義を登録または更新します。

| カラム  | 必須  | 型  | 説明  |
|  --- | --- | --- | --- |
| `SegmentId` | 必須 | string (200 文字以内) | タクソノミー内で一意のセグメント識別子。 |
| `Name` | 必須 | string (200 文字以内) | ユーザーが識別しやすいセグメント名。 |
| `IsActive` | 必須 | boolean | セグメントを有効化する場合は `1`、無効化する場合は `0`。デフォルトは `1`。 |
| `IsSelectable` | 必須 | boolean | Equativ UI で選択可能にする場合は `1`。デフォルトは `1`。 |
| `Price` | 必須 | float | セグメントに適用する CPM 価格。デフォルトは `0`。 |
| `TTL` | 必須 | integer (分単位) | セグメントの有効期間 (分)。デフォルトは `43200` (30 日)。 |
| `ParentSegmentId` | 任意 | string | 階層的タクソノミーでの親セグメント。 |
| `Description` | 任意 | string (255 文字以内) | セグメントの任意の説明。 |


### プロファイルファイルのカラム

プロファイルファイルを使って、個々のユーザーのセグメント所属を追加・削除・置き換えします。

| カラム  | 必須  | 説明  |
|  --- | --- | --- |
| `UserID` | 必須 | ユーザー識別子。Equativ では Cookie ID、モバイル広告 ID (MAID)、パブリッシャー提供 ID、代替 ID、IP アドレス、郵便番号がサポートされています。 |
| `SegmentToAdd` | 条件付き | このユーザーに追加する `SegmentId` のカンマ区切りリスト。例: `123,456`。 |
| `SegmentToRemove` | 条件付き | このユーザーから削除する `SegmentId` のカンマ区切りリスト。 |
| `SegmentToSet` | 条件付き | ユーザーの現在の所属を置き換える `SegmentId` のカンマ区切りリスト。 |


プロファイルレコードの保持期間
Equativ はプロファイルレコードを 14 日間保持します。この 14 日間のプロファイルレコード保持期間は、タクソノミーファイルのセグメントごとの `TTL` カラムとは別のものです。所属を最新状態に保つため、この保持期間より短い間隔でプロファイルエクスポートを実行してください。

## Treasure コンソールで接続を作成する

### 新しい認証を作成する

1. **Treasure コンソール** を開きます。
2. **Integrations Hub** > **Catalog** に移動します。
3. **Google Cloud Storage V2** を検索して選択します。
4. **Create Authentication** を選択します。
5. 認証方式として **JSON Keyfile** を選択し、Equativ から提供されたサービスアカウント JSON キーを貼り付けます。
6. 接続名を入力します (例: `equativ-batch-file`)。
7. **Continue** を選択します。


Workload Identity Federation を含む GCS の認証オプションの詳細については、[Google Cloud Storage Export V2 Integration](/int/google-cloud-storage-export-v2-integration#use-the-td-console-to-create-your-connection) のドキュメントを参照してください。

## ソースクエリを作成する

クエリは、Equativ が想定するカラムと値のフォーマットを正確に出力する必要があります。区切り文字としてパイプ (`|`) を使用し、必要なカラムではカンマ区切りリストを生成してください。

### タクソノミーファイル用クエリの例


```sql
SELECT
  segment_id      AS "SegmentId",
  segment_name    AS "Name",
  CAST(is_active     AS INTEGER) AS "IsActive",
  CAST(is_selectable AS INTEGER) AS "IsSelectable",
  CAST(price AS DOUBLE)          AS "Price",
  CAST(ttl_minutes   AS INTEGER) AS "TTL",
  parent_segment_id              AS "ParentSegmentId",
  description                    AS "Description"
FROM equativ_taxonomy
```

### プロファイルファイル用クエリの例

以下の例では、セグメント ID の配列を Equativ が要求するカンマ区切り形式に変換しています。


```sql
SELECT
  user_id AS "UserID",
  ARRAY_JOIN(segments_to_add,    ',') AS "SegmentToAdd",
  ARRAY_JOIN(segments_to_remove, ',') AS "SegmentToRemove",
  ARRAY_JOIN(segments_to_set,    ',') AS "SegmentToSet"
FROM equativ_profile_updates
WHERE TD_INTERVAL(time, '-1d/now')
```

パイプ区切りを使用する
エクスポートを構成する際は、**Delimiter** に `|` を設定してください。これにより、`SegmentToAdd` などのカラム内に含まれるカンマ区切りのセグメントリストが、別カラムに分割されることを防げます。

## エクスポートを定義する

Data Workbench クエリの結果、または Audience Studio のアクティベーションのいずれからもエクスポートできます。

### オプション 1: クエリ結果をエクスポートする

1. [Creating a Destination Integration](/products/customer-data-platform/integration-hub/batch/export/creating-a-destination-integration) の手順を完了します。
2. **Data Workbench** > **Queries** に移動し、Equativ 向けフォーマットの結果セットを生成するクエリを開きます。
3. クエリを実行して出力を検証します。
4. **Export Results** を選択し、作成した Equativ 向け Google Cloud Storage 認証を選びます。
5. 後述の Integration Parameters を構成します。
6. **Done** を選択してクエリを実行します。


### オプション 2: Audience Studio からアクティベートする

## Audience Studio で Segment をアクティベートする

Audience Studio で activation を作成することで、segment データをターゲットプラットフォームに送信することもできます。

1. **Audience Studio** に移動します。
2. parent segment を選択します。
3. ターゲット segment を開き、右クリックして、**Create Activation** を選択します。
4. **Details** パネルで、Activation 名を入力し、前述の Configuration Parameters のセクションに従って activation を設定します。
5. **Output Mapping** パネルで activation 出力をカスタマイズします。


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- Attribute Columns
  - **Export All Columns** を選択すると、変更を加えずにすべての列をエクスポートできます。
  - **+ Add Columns** を選択して、エクスポート用の特定の列を追加します。Output Column Name には、Source 列名と同じ名前があらかじめ入力されます。Output Column Name を更新できます。**+ Add Columns** を選択し続けて、activation 出力用の新しい列を追加します。
- String Builder
  - **+ Add string** を選択して、エクスポート用の文字列を作成します。次の値から選択します:
    - String: 任意の値を選択します。テキストを使用してカスタム値を作成します。
    - Timestamp: エクスポートの日時。
    - Segment Id: segment ID 番号。
    - Segment Name: segment 名。
    - Audience Id: parent segment 番号。


1. **Schedule** を設定します。


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

- スケジュールを定義する値を選択し、オプションでメール通知を含めます。


1. **Create** を選択します。


batch journey の activation を作成する必要がある場合は、[Creating a Batch Journey Activation](/products/customer-data-platform/journey-orchestration/batch/creating-a-batch-journey-activation) を参照してください。

アクティベーションを構成する際は、Equativ 向け GCS 認証を指定し、次のセクションに記載した Integration Parameters と同じ値を使用してください。

### Integration Parameters

| パラメータ  | 必須  | 推奨値  | 説明  |
|  --- | --- | --- | --- |
| Bucket | 必須 | ファイル種別、環境、リージョンに応じて Equativ から提供されるバケット。 | 例: タクソノミー本番アップロード用は `taxonomy_importer_audience_prod`、US 本番プロファイルアップロード用は `profile_importer_audience_us_prod`。 |
| File Path | 必須 | `<customer_folder>/taxonomy_${session_unixtime}.csv` または `<customer_folder>/profile_${session_unixtime}.csv` | ファイル名を含むオブジェクトパス。`<customer_folder>` は Equativ から割り当てられたフォルダ名に置き換えてください。各バッチが独立して処理されるよう、実行ごとに一意のファイル名 (例: セッションタイムスタンプ) を使用してください。 |
| Format | 必須 | `csv` | Equativ では CSV が必須です。 |
| Delimiter | 必須 | `|` | Equativ が要求するパイプ文字。 |
| Header line? | 必須 | `true` | Equativ はヘッダの有無どちらでも受け付けます。ヘッダを含めると運用上のデバッグが容易になります。 |
| End-of-line character | 任意 | `LF` | `LF` と `CRLF` のどちらでも受け付けます。 |
| Encoders / Compression | 任意 | `none` | Equativ ではバッチ取り込みに圧縮は不要です。 |


GCS V2 エクスポートパラメータの全リストについては、[Integration Parameters for Google Cloud Storage](/int/google-cloud-storage-export-v2-integration#integration-parameters-for-google-cloud-storage) を参照してください。

## エクスポートをスケジュールする

Equativ はバケットにファイルが到着すると即座に処理します。タクソノミーとプロファイルのデータを最新に保つには:

- **タクソノミーエクスポート** はセグメント定義が変更されたタイミング (通常は日次またはオンデマンド) でスケジュールします。
- **プロファイルエクスポート** は 14 日間のプロファイルレコード保持期間より短い周期でスケジュールします。日次の差分エクスポートが一般的なパターンです。


エクスポートのスケジュール方法は次のとおりです:

- Audience Studio のアクティベーションで **Schedule** を設定する
- スケジュールクエリを駆動する [Treasure ワークフロー](/products/customer-data-platform/data-workbench/workflows/treasure-workflow-quick-start-using-td-toolbelt-in-a-cli) の `td>` タスクを使用する


## エクスポートを検証する

1. 想定した `File Path` で、Equativ 管理下のバケットにファイルが存在することを確認します。
2. ファイルを開き、以下を検証します:
  - パイプ区切りのカラム
  - UTF-8 エンコーディング
  - カンマ区切りの `SegmentToAdd` / `SegmentToRemove` / `SegmentToSet` の値
3. Equativ の取り込みレポートまたは管理画面で、セグメントタクソノミーまたはプロファイル更新が適用されたことを確認します。


Equativ がファイルを拒否する場合は、[ファイルフォーマット概要](#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%83%95%E3%82%A9%E3%83%BC%E3%83%9E%E3%83%83%E3%83%88%E6%A6%82%E8%A6%81) のセクションに照らしてファイルを確認し、ファイル種別、環境、リージョンに対応した正しいバケットへアップロードしているかを確認してください。