# Equativ Export Integration

この連携では 2 種類のファイルをエクスポートします。**taxonomy** エクスポートは Equativ 上にセグメント定義を作成し、**profile** エクスポートは個々のユーザーのセグメント所属を設定、追加、または削除します。プロファイルデータを送信する前に、参照先のセグメントが Equativ 上に存在している必要があるため、新規に構築する場合は必ず taxonomy エクスポートから開始します。

## この連携でできること

- Equativ 上にセグメントを定義します。
- ユーザーをセグメントに追加する、特定のセグメントから削除する、または 1 レコードでユーザーのセグメントをすべて置き換えます。
- Equativ が受け付けるあらゆる識別子で所属情報を送信します。
- プロファイルデータを US、EU、APAC のいずれかの Equativ 環境に送信します。


## データ連携の仕組み

Equativ Export Integration は Equativ の API を呼び出しません。エクスポートジョブごとに 1 つのファイルを生成し、Equativ が所有して取り込む Google Cloud Storage バケットにアップロードします。

1. Equativ の Segment Provider ID、エクスポートタイプ、および profile エクスポートの場合はリージョンと識別子タイプを設定します。
2. Treasure AI は、その Segment Provider ID が自身の Treasure AI アカウントに登録済みであることを検証します。
3. 連携はクエリまたはセグメントの結果からファイルを生成します。形式はパイプ区切りの CSV で、ヘッダー行を含み、UTF-8 でエンコードされます。
4. 連携は、エクスポートタイプとリージョンに対応する Equativ のバケットへ、Segment Provider ID から導出されたパスでファイルをアップロードします。
5. Equativ がバケットからファイルを取り込み、内容を適用します。


ファイルベースの連携であり、Equativ から結果が返らないため、Treasure AI のジョブが成功したことはファイルがバケットに受理されたことのみを意味し、Equativ が処理を完了したことは意味しません。結果は Equativ 上で確認してください。

## 前提条件

- Treasure AI の基本知識。
- 有効な Equativ アカウント
- Equativ の Segment Provider ID。Equativ から提供されます。
- Treasure AI に登録済みの Segment Provider ID。登録はオンボーディング時に行われます。Segment Provider ID を追加する場合は、カスタマーサクセス担当者またはテクニカルサポートにお問い合わせください。未登録の ID を使用したエクスポートは `Segment Provider ID not authorized for this account` で失敗します。


## 要件と制限事項

- profile データをエクスポートする前に、対象のセグメントが Equativ 上に存在している必要があります。先に taxonomy エクスポートを実行し、Equativ 上にセグメントが作成されたことを確認してください。
- クエリのカラム名は、このページに記載された名称と完全に一致させてください。大文字小文字は区別されず、前後の空白は無視されますが、大文字小文字または空白だけが異なる 2 つのカラムがある場合はジョブが失敗します。
- カラムの値にパイプ (`|`)、カンマ (`,`)、二重引用符 (`"`)、改行を含めることはできません。出力形式は位置ベースでエスケープ処理を行わないため、これらの文字はレコードを破損させます。
- taxonomy の更新は行全体の置き換えです。以前に設定していたフィールドを含めずにセグメントを再エクスポートすると、そのフィールドの値は失われます。Equativ に保持させたいフィールドは常にすべてエクスポートしてください。
- taxonomy ファイル内に同じ `segment_id` が複数含まれる場合、Equativ は最後の 1 件のみを取り込みます。この連携は重複を除去しません。
- セグメントの削除には Equativ 側の対応が必要です。ターゲティングから除外するには `is_active` を `0` に設定してください。
- 本番環境では 1 フォルダーあたり 1 日 10 GB までに対応します。サンドボックス環境で受け付けられるデータ量はこれよりかなり少なくなります。
- profile データは、対象ユーザーをターゲティングするリージョンに送信する必要があります。誤ったリージョンにアップロードされたユーザーはターゲティングに利用できず、Equativ からエラーは通知されません。


## 新しい接続の作成

クエリを実行する前に、Treasure Console でデータ接続を作成して設定します。この連携には OAuth や認証情報の入力手順はありません。ストレージの認証情報は Treasure AI が内部で保持しており、指定するのは Equativ の Segment Provider ID のみです。

1. **Treasure Console** を開きます。
2. **Integrations Hub > Catalog** に移動します。
3. **Equativ Export** を検索して選択します。


![Integrations Hub の Catalog に表示された Equativ Export コネクタ](/assets/new_connector_logo.c399e24994fdf6177118e1471a6cea6e4a9099093866d8f57e3baf9bdb8aac7d.0168b08c.webp)

1. **Create Authentication** を選択し、Segment Provider ID を入力します。


![Segment Provider ID を入力する Equativ Export の認証設定画面](/assets/new_connector_config.a5e71e95384fc66f55846dc08fb0fe48034418e6939c20c1d93a586ab786be9e.0168b08c.webp)

1. **Continue** を選択し、認証の名前を入力して **Done** を選択します。


### 認証フィールド

| フィールド名  | 型  | 説明  |
|  --- | --- | --- |
| **JSON keyfile** (必須) | string | サービスアカウントのキーファイルの内容。 |
| **Segment Provider ID** (必須) | string | Equativ がアカウントに対して発行する一意の識別子。自身の Treasure AI アカウントに登録済みの Segment Provider ID のいずれかである必要があります。 |


## クエリ結果のエクスポート設定

Treasure Console では複数の方法でデータをエクスポートできます。Data Workbench からエクスポートする場合は次のとおりです。

1. **Data Workbench > Queries** に移動します。
2. **New Query** を選択し、クエリを定義します。
3. **Export Results** を選択して、データエクスポートを設定します。
4. 既存の Equativ 認証を選択するか、前のセクションの手順で新しい認証を作成します。
5. エクスポートパラメーターを設定します。
6. **Done** を選択します。


## クエリの定義

クエリは、設定したエクスポートタイプが必要とするカラムを返す必要があります。それ以外のカラムは無視されます。必須カラムが null または空の場合、そのレコードは無効となります。**Skip Invalid Records** が有効な場合はレコードがスキップされ、無効な場合はジョブが失敗します。

### taxonomy のカラム

taxonomy エクスポートはセグメント自体を定義します。

| カラム  | 必須  | データ型  | デフォルト  | 検証内容  | 説明  |
|  --- | --- | --- | --- | --- | --- |
| `segment_id` | はい | string | — | 空でない、200 文字以内 | 独自のセグメント識別子。 |
| `parent_segment_id` | いいえ | string | 空 | 200 文字以内 | 親セグメント。Equativ 上に表示される階層を構成します。空の場合は最上位のセグメントになります。 |
| `name` | はい | string | — | 空でない、200 文字以内 | Equativ 上に表示されるセグメント名。 |
| `description` | いいえ | string | 空 | 255 文字以内 | 任意のセグメント説明。 |
| `price` | いいえ | long または double | `0` | 0 以上 | セグメントの価格。価格を設定しない場合は `0` を使用します。 |
| `is_selectable` | いいえ | boolean または long | `1` | `0`、`1`、`true`、`false` | セグメントがターゲティング可能な場合は `1`、階層構成のためだけに存在する場合は `0`。 |
| `ttl` | いいえ | long | `43200` | 正の整数 | ユーザーとセグメントの関連付けの有効期間。単位は**分**です。デフォルトの `43200` は 30 日を表します。 |
| `is_active` | いいえ | boolean または long | `1` | `0`、`1`、`true`、`false` | セグメントが有効な場合は `1`、無効化してターゲティングから除外する場合は `0`。 |


任意のカラムが存在しない場合や空の場合はデフォルト値が使用されるため、最小構成の taxonomy クエリは `segment_id` と `name` のみを返します。

クエリ出力の例:

| segment_id | parent_segment_id | name | description | price | is_selectable | ttl | is_active |
|  --- | --- | --- | --- | --- | --- | --- | --- |
| 123 |  | Gender: Male |  | 0.50 | true | 24000 | true |
| LF-1001 |  | Sport Readers |  |  |  |  |  |


この出力から次のファイルが生成されます。2 行目は、任意のカラムがすべてデフォルト値をとった場合の例です。

```
SegmentId|ParentSegmentId|Name|Description|Price|IsSelectable|TTL|IsActive
123||Gender: Male||0.50|1|24000|1
LF-1001||Sport Readers||0|1|43200|1
```

### profile のカラム

profile エクスポートは、ユーザーのセグメント所属を設定、追加、または削除します。1 レコードが 1 ユーザーに対応します。

| カラム  | 必須  | データ型  | 説明  |
|  --- | --- | --- | --- |
| `user_id` | はい | string | ユーザー識別子。 |
| `segment_to_set` | 3 つのいずれか 1 つ以上 | string | ユーザーの現在のセグメントを**すべて置き換える**セグメントのカンマ区切りリスト。 |
| `segment_to_add` | 3 つのいずれか 1 つ以上 | string | **追加する**セグメントのカンマ区切りリスト。ユーザーの既存のセグメントは変更されません。 |
| `segment_to_remove` | 3 つのいずれか 1 つ以上 | string | **削除する**セグメントのカンマ区切りリスト。リストに含まれるセグメントのみが削除されます。 |
| `profile_id_source` | いいえ | string | 識別子の由来となるアイデンティティグラフ。Equativ 側でのバックエンド有効化が必要です。有効化されていない場合は無視され、プロファイル自体は取り込まれます。パイプ、二重引用符、改行を含めることはできません。空の値は指定なしとして扱われます。 |


各レコードは、3 つのファミリー全体で少なくとも 1 つのセグメント値を持つ必要があります。また、セグメント値は 1 つあたり 200 文字までです。

#### 連番付きのセグメントカラム

3 つのセグメントファミリーはいずれも連番付きのカラムを受け付けるため、クエリ内でセグメントを連結する必要はありません。

| ファミリー  | 使用できるカラム名  |
|  --- | --- |
| set | `segment_to_set`、`segment_to_set1`、`segment_to_set2`、… |
| add | `segment_to_add`、`segment_to_add1`、`segment_to_add2`、… |
| remove | `segment_to_remove`、`segment_to_remove1`、`segment_to_remove2`、… |


1 つのファミリーに属する値は、カラム名の順序でカンマ区切りの単一フィールドにまとめられます。連番は `1` から始まる必要はなく、連続している必要もありません。null、空文字、空白のみの値は空の要素として送信されず、スキップされます。各値は前後の空白が除去され、同一ファミリー内で重複する値は 1 度だけ送信されます。重複除去はファミリーごとに行われるため、同じセグメントが `segment_to_add` と `segment_to_remove` の両方に含まれる場合は両方に送信されます。この矛盾はクエリ側で解消してください。

値を持たないファミリーは、区切り文字を保持したまま空のフィールドとして送信されます。3 つのファミリーがすべて空のレコードは無効です。

クエリ出力の例:

| user_id  | segment_to_set  | segment_to_set1  | segment_to_add  | segment_to_add1  | segment_to_remove  |
|  --- | --- | --- | --- | --- | --- |
| glVQoCkEgJcWya7NrUYac | 123 |  |  |  |  |
| ll1iA1FJMNDYGUHZef_3WCIMpc9e |  |  | 123 | 456 |  |
| nwGPW6UZeX4Esgcrz2_TbU87L |  |  | 111 | 112 | 113 |
| FR:75001 | 789 | 101 |  |  |  |


この出力から次のファイルが生成されます。

```
UserID|SegmentToSet|SegmentToAdd|SegmentToRemove
glVQoCkEgJcWya7NrUYac|123||
ll1iA1FJMNDYGUHZef_3WCIMpc9e||123,456|
nwGPW6UZeX4Esgcrz2_TbU87L||111,112|113
FR:75001|789,101||
```

`profile_id_source` を返した場合は、各レコードに 5 番目のフィールドが追加されます。

## 設定パラメーター

![taxonomy エクスポートのパラメーター設定画面](/assets/export_taxonomy.23b963afca6f344d1e87e4a2432754717f1365d0700469637ccb4f3affb05244.0168b08c.webp)
![profile エクスポートのパラメーター設定画面](/assets/export_profile.a9b3ef6bc23b4b89c6905960dedcc645118664e5e38a69d0517e256ecb3b8fc6.0168b08c.webp)

Equativ Export Integration にはエクスポート用のパラメーターが 4 つあります。

| パラメーター名  | 型  | デフォルト  | 説明  |
|  --- | --- | --- | --- |
| **Export Type** (必須) | string | `taxonomy` | エクスポートで作成する対象。`taxonomy` は Equativ 上にセグメントを定義し、`profile` はユーザーのセグメント所属を設定、追加、削除します。 |
| **Profile Region** (`profile` の場合は必須) | string | `us` | データを受け取る Equativ のリージョン。`us`、`eu`、`apac` のいずれかです。Export Type が `taxonomy` の場合は無視されます。 |
| **Encrypted Alternative IDs** (任意) | string | `none` | `user_id` に特定プロバイダーの暗号化された代替 ID が含まれる場合に `utiq.com` または `id5-sync.com` を設定します。それ以外の識別子の場合は `none` のままにします。Export Type が `taxonomy` の場合は無視されます。 |
| **Skip Invalid Records** (任意) | boolean | `true` | 有効な場合、無効なレコードはカウントされてスキップされます。無効な場合、最初の無効なレコードでジョブが失敗し、何もアップロードされません。 |


### (オプション) Query Export ジョブをスケジュールする

Scheduled Jobs と Result Export を使用して、指定したターゲット宛先に出力結果を定期的に書き込むことができます。

Treasure Data のスケジューラー機能は、高可用性を実現するために定期的なクエリ実行をサポートしています。

2 つの仕様が競合するスケジュール仕様を提供する場合、より頻繁に実行するよう要求する仕様が優先され、もう一方のスケジュール仕様は無視されます。

例えば、cron スケジュールが `'0 0 1 * 1'` の場合、「月の日」の仕様と「週の曜日」が矛盾します。前者の仕様は毎月 1 日の午前 0 時 (00:00) に実行することを要求し、後者の仕様は毎週月曜日の午前 0 時 (00:00) に実行することを要求するためです。後者の仕様が優先されます。

#### Treasure コンソール を使用してジョブをスケジュールする

1. **Data Workbench > Queries** に移動します
2. 新しいクエリを作成するか、既存のクエリを選択します。
3. **Schedule** の横にある None を選択します。
![](/assets/image2021-1-15_17-28-51.f1b242f6ecc7666a0097fdf37edd1682786ec11ef80eff68c66f091bc405c371.0f87d8d4.png)
4. ドロップダウンで、次のスケジュールオプションのいずれかを選択します:
![](/assets/image2021-1-15_17-29-47.45289a1c99256f125f4d887e501e204ed61f02223fde0927af5f425a89ace0c0.0f87d8d4.png)
| ドロップダウン値 | 説明 |
|  --- | --- |
| Custom cron... | [Custom cron... の詳細](#custom-cron-details)を参照してください。 |
| @daily (midnight) | 指定されたタイムゾーンで 1 日 1 回午前 0 時 (00:00 am) に実行します。 |
| @hourly (:00) | 毎時 00 分に実行します。 |
| None | スケジュールなし。 |


#### Custom cron... の詳細

![](/assets/image2021-1-15_17-30-23.0f94a8aa5f75ea03e3fec0c25b0640cd59ee48d1804a83701e5f2372deae466c.0f87d8d4.png)

| **Cron 値** | **説明** |
|  --- | --- |
| `0 * * * *` | 1 時間に 1 回実行します。 |
| `0 0 * * *` | 1 日 1 回午前 0 時に実行します。 |
| `0 0 1 * *` | 毎月 1 日の午前 0 時に 1 回実行します。 |
| "" | スケジュールされた実行時刻のないジョブを作成します。 |


```
 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)
```

次の名前付きエントリを使用できます:

- Day of Week: sun, mon, tue, wed, thu, fri, sat.
- Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.


各フィールド間には単一のスペースが必要です。各フィールドの値は、次のもので構成できます:

div
| フィールド値  | 例  | 例の説明  |
|  --- | --- | --- |
| 各フィールドに対して上記で表示された制限内の単一の値。 |  |  |
| フィールドに基づく制限がないことを示すワイルドカード
`'*'`。 | `'0 0 1 * *'` | 毎月 1 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 範囲 `'2-5'`
フィールドの許可される値の範囲を示します。 | `'0 0 1-10 * *'` | 毎月 1 日から 10 日までの午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| カンマ区切りの値のリスト `'2,3,4,5'`
フィールドの許可される値のリストを示します。 | `0 0 1,11,21 * *'` | 毎月 1 日、11 日、21 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 周期性インジケータ `'*/5'`
フィールドの有効な値の範囲に基づいて、
スケジュールが実行を許可される頻度を表現します。 | `'30 */2 1 * *'` | 毎月 1 日、00:30 から 2 時間ごとに実行するようにスケジュールを設定します。
`'0 0 */5 * *'` は、毎月 5 日から 5 日ごとに午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| `'*'`
ワイルドカードを除く上記の
いずれかのカンマ区切りリストもサポートされています
`'2,*/5,8-10'` | `'0 0 5,*/10,25 * *'` | 毎月 5 日、10 日、20 日、25 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |


1. (オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。


### クエリを実行する

クエリに名前を付けて保存して実行するか、単にクエリを実行します。クエリが正常に完了すると、クエリ結果は指定された宛先に自動的にエクスポートされます。

設定エラーにより継続的に失敗するスケジュールジョブは、複数回通知された後、システム側で無効化される場合があります。

(オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。

## 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) を参照してください。

## (任意) Treasure Workflow を使ったエクスポート

このエクスポートは Treasure Workflow 内でも実行できます。詳細は [TD Toolbelt でワークフローを使ってデータをエクスポートする](/tools/cli-and-sdks/api#workflow-commands) を参照してください。

taxonomy エクスポートでセグメントを作成します。

```yaml
_export:
  td:
    database: equativ_db

+equativ_taxonomy_task:
  td>: taxonomy.sql
  database: ${td.database}
  result_connection: new_created_equativ
  result_settings:
    type: equativ
    json_keyfile:
      content: |
      {xxxxxxxx}
    segment_provider_id: "abc28132y484ry24givncdkmn"
    export_type: taxonomy
    skip_invalid_records: true
```

セグメントに対してプロファイルの所属情報を送信します。

```yaml
_export:
  td:
    database: equativ_db

+equativ_profile_task:
  td>: profile.sql
  database: ${td.database}
  result_connection: new_created_equativ
  result_settings:
    type: equativ
    json_keyfile:
      content: |
      {xxxxxxxx}
    segment_provider_id: "abc28132y484ry24givncdkmn"
    export_type: profile
    profile_region: eu
    skip_invalid_records: true
```

### パラメーター

| 名前  | 説明  | 値  | デフォルト  | 必須  |
|  --- | --- | --- | --- | --- |
| `type` | コネクタタイプ | `equativ` | N/A | はい |
| `json_keyfile` | Equativ が提供する Google サービスアカウント JSON キー。content プロパティを持つオブジェクトです。例:
json_keyfile:
content: |
{xxxxxxxx} | N/A | N/A | はい |
| `segment_provider_id` | データを受け取る Equativ の Segment Provider ID | N/A | N/A | はい |
| `export_type` | エクスポートで作成する対象 | `taxonomy`、`profile` | `taxonomy` | はい |
| `profile_region` | profile データを受け取る Equativ のリージョン | `us`、`eu`、`apac` | `us` | export_type が profile の場合は必須 |
| `eid_provider` | `user_id` に含まれる暗号化された代替 ID のプロバイダー | `none`、`utiq.com`、`id5-sync.com` | `none` | いいえ |
| `skip_invalid_records` | ジョブを失敗させる代わりに無効なレコードをスキップする | `true`、`false` | `true` | いいえ |


profile エクスポート用のクエリ例:

```sql
SELECT
  user_id,
  segment_to_add,
  segment_to_add1
FROM (
  VALUES ('glVQoCkEgJcWya7NrUYac', '123', '456')
) tbl (user_id, segment_to_add, segment_to_add1)
```

## トラブルシューティング

ジョブは成功したものの Equativ 上にデータが表示されない場合は、次の項目を順に確認してください。

- セグメントが存在すること。taxonomy エクスポートで作成されていないセグメントを参照する profile データはターゲティングに利用できず、Equativ からエラーは通知されません。
- taxonomy の行が完全であること。必須フィールドが欠けているセグメントは、Equativ 側で通知なく破棄されます。
- **Profile Region** が、対象ユーザーをターゲティングするリージョンと一致していること。他のリージョンにアップロードされたユーザーは利用できません。
- profile エクスポートのセグメント ID が、taxonomy エクスポートの `segment_id` の値と一致していること。
- 日次のデータ量がフォルダーあたり 10 GB を超えていないこと。


## その他

- [スケジュールジョブ](/products/customer-data-platform/job-management/scheduling-jobs-using-td-console) と Result Export を組み合わせて、定期的に Equativ へデータをアップロードできます。