# CleverTap Export Integration

This feature is in BETA version. For more information, contact your Customer Success Representative.

## 概要

CleverTapは、アプリ分析とマーケティングツールを組み合わせた、ユーザーエンゲージメントとリテンション向上を支援する主要な顧客エンゲージメント・リテンションプラットフォームです。以下の3つの主要機能を提供します。

- **ユーザー行動の追跡と分析**: ユーザーのアクションを監視し、製品の使用パターンを分析します。
- **セグメンテーションとターゲットキャンペーン**: 行動に基づいてユーザーをセグメント化し、さまざまなチャネルでパーソナライズされたキャンペーンを実行します。
- **キャンペーン分析**: キャンペーンの効果を評価し、ユーザーエンゲージメントとビジネス指標を最適化します。


CleverTap integrationは、Treasure DataとCleverTapを接続し、ユーザープロファイル、イベント、オーディエンスのシームレスな同期を可能にします。このintegrationにより、企業はTreasure Dataの統合データとCleverTapのエンゲージメントツールを活用して、CX、CRM、リテンションマーケティングの取り組みを強化できます。

## 前提条件

- Treasure Dataの基本知識
- CleverTap Engagement Platformの基本知識


## 制限事項

- ユーザーオーディエンスカスタムリストをアップロードする際のファイルサイズの上限は5GBです。


## 新しいコネクションの作成

クエリを実行する前に、TD Console上でデータコネクションを作成し、設定する必要があります。データコネクションの一部として、integrationにアクセスするための認証情報を提供します。以下の手順を実行してください。

![](/assets/screenshot-at-aug-20-14-20-44.4ecf9908bf6b0d6a3fb3d797b5f0186b642ca69788941919b316e44f3ef37254.fe495661.png)

1. TD Consoleを開きます。
2. **Integrations Hub > Catalog**に移動します。
3. **CleverTap**を検索して選択します。
4. **Create Authentication**を選択し、次の表に記載されているintegrationの認証情報を入力します。
5. **Continue**を選択し、Authenticationの名前を入力して、**Done**を選択します。


### 認証フィールド

| **フィールド** | **説明** |
|  --- | --- |
| **CleverTap Account ID** | CleverTap Account IDの入力フィールド。Account IDを取得するには、[API Quick Start Guide](https://developer.clevertap.com/docs/api-quickstart-guide#get-clevertap-account-credentials-to-authenticate-api-requests)を参照してください。 |
| **CleverTap Passcode** | CleverTap Account PasscodeまたはUser's Passcodeの入力フィールド。Passcodeを取得するには、[API Quick Start Guide](https://developer.clevertap.com/docs/api-quickstart-guide#get-clevertap-account-credentials-to-authenticate-api-requests)を参照してください。 |
| **Rest Endpoint Region** | **Box**を選択して、使用するRest Endpointを決定するAPIリージョンを選択します。Account Regions（Rest Endpoint用）を取得するには、[Common API Components](https://developer.clevertap.com/docs/common-api-components#region)を参照してください。 |


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

TD Consoleは、データをエクスポートする複数の方法をサポートしています。Data Workbenchからデータをエクスポートするには、以下の手順に従ってください。

1. **Data Workbench** > **Queries**に移動します。
2. **New Query**を選択し、クエリを定義します。
3. **Export Results**を選択して、データのエクスポートを設定します。
4. 既存のCleverTap authenticationを選択するか、前述の方法で新しいものを作成します。
5. **Done**を選択します。


### コネクタ設定パラメータ

次の表は、CleverTap export integrationの設定パラメータについて説明しています。

| **フィールド** | **説明** |
|  --- | --- |
| **Target Data Entity** | CleverTap exportのTarget Data Entity。サポートされている値：- **User Profiles:** ユーザープロファイルに関連するデータをアップロードします。
- **User Events:** ユーザーイベントに関連するデータをアップロードします。
- **User Audiences - Custom List:** カスタムリストセグメントをアップロードします。

 |
| **User Profiles Operation** | ユーザープロファイルのアップロードに関連する操作。以下の値のリストから選択します：- **Upload User Profiles:** 性別、電話番号などのユーザープロファイル情報を更新します。
- **Upload Device Tokens:** 既存のデバイストークンをCleverTapユーザープロファイルに追加します。
- **Demege User Profile:** ユーザープロファイルをデマージします。
- **Update Email/Phone Subscription:** 電話番号またはメールのステータスを購読済みまたは購読解除に設定します。
- **Disassociate A Phone Number:** ユーザープロファイルから電話番号を切断します。

 |
| **Array Property Operation**
 | このオプションは、**User Profiles Operation**が**Upload User Profiles**で、カスタム属性値がjson配列の場合にのみ必要です。CleverTapの配列操作（replace、append ($add)、remove ($remove)）を適用します。
サポートされている操作：
- **Replace**
- **Append**
- **Remove**

 |
| **Name for Custom List Upload** | このオプションは、**Target Data Entity**が**User Audiences - Custom List**の場合に必要です。これはCleverTap内のセグメントの名前です。 |
| **Custom List Upload User Email** | このオプションは、**Target Data Entity**が**User Audiences - Custom List**の場合に必要です。メールアドレスはCleverTapの管理者ロールに属している必要があります。 |
| **Segment Operation Mode** | サポートされている値：- **Create New Segment (One-Time):** CleverTapに新しいセグメントを作成します。セグメントが既に存在する場合、ジョブは失敗します。
- **Update Existing Segment (Scheduled):** CleverTapの既存のセグメントを更新します。セグメントはCleverTapに存在している必要があり、そうでない場合、ジョブは失敗します。このオプションは、スケジュールされたジョブに使用できます。

 |
| **Thread Count Number**
 | CleverTapサーバーへの同時リクエスト数。最小：1、最大：10、デフォルト：5。
このパラメータは、Target Data Entity：**User Profiles**と**User Events**にのみ適用されます。
 |
| **Skip on Invalid Record?** | チェックした場合、ジョブは無効なレコードをスキップして次のレコードの処理を続行します。チェックしない場合、ジョブは停止します。 |


## 各Target Data Entityの詳細ガイド

すべてのTarget Data Entityについて、CleverTap APIガイドラインに準拠したデフォルトフィールドとカスタムフィールドの組み合わせを含むデータエクスポートクエリを作成する必要があります。デフォルトフィールドについては、列名が各機能ガイドの「Field/Column-Level Specifications」セクションに記載されている名前と一致することを確認してください。コネクタは列名を自動的に正規化してCleverTapの必要な形式に合わせるため、大文字と小文字の区別を気にする必要はありません。

例えば、デフォルトフィールド「objectId」の場合、エクスポートクエリの列名は「OBJECTID」、「objectid」、「OBJECTid」など、任意の大文字・小文字で記述できます。コネクタは、CleverTapの要件に合わせて列名を「objectId」に標準化します。

## Target Data Entity: User Profiles

User Profiles data entityについては、いくつかの操作モードをサポートしています：

- **Upload User Profiles:** 性別、電話番号などのユーザープロファイル情報を更新します。
- **Upload Device Tokens:** 既存のデバイストークンをCleverTapユーザープロファイルに追加します。
- **Demege User Profile:** ユーザープロファイルをデマージします。
- **Update Email/Phone Subscription:** 電話番号またはメールのステータスを購読済みまたは購読解除に設定します。
- **Disassociate A Phone Number:** ユーザープロファイルから電話番号を切断します。


このドキュメントには、Upload User Profilesモードの詳細ガイドセクションと、残りの4つの操作モードのセクションが含まれています。

### Upload User Profilesの詳細

#### I. エクスポートクエリの作成

ユーザープロファイルデータをCleverTapに正常にアップロード/変更するには、特定のデータ仕様に準拠したエクスポートクエリを作成する必要があります。これらの仕様は2つのレベルに分かれています。

#### エクスポートクエリの仕様

| **仕様** | **説明** |
|  --- | --- |
| **条件付き必須列** | 次のいずれかの列が存在する必要があります：`identity`または`objectid`。 |
| **Null値の列** | Null値を持つ列は無視されます。 |
| **列の命名規則** | - 列名に次の文字を含めることはできません：`&`、`$`、`"`、`,`、`%`、`>`、`<`、`!`。- 列名は120文字を超えてはなりません。 |
| **列値の最大長** | デフォルトフィールドとカスタムフィールドの両方の列値は、512文字を超えてはなりません。 |
| **重複した列** | 重複した列は許可されていません。 |


##### Field/Column-Level Specifications

**デフォルトフィールド列**

| **フィールド** | **説明** | **必須** | **データ型** | **追加仕様** |
|  --- | --- | --- | --- | --- |
| `identity` | ユーザーidentityフィールド | はい（`objectid`が存在しない場合） | スカラー型（string、integer、boolean） |  |
| `objectid` | ユーザーidentityフィールド | はい（`identity`が存在しない場合） | スカラー型（string、integer、boolean） |  |
| `Name` | プロファイル名 | いいえ | String |  |
| `Email` | ユーザーのメールアドレス | いいえ | String | 有効なメールパターンと一致する必要があります。 |
| Phone | ユーザーの電話番号 | いいえ | String | E.164電話番号形式（+[国コード][国内有効番号]）でフォーマットする必要があります。 |
| `Gender` | ユーザーの性別 | いいえ | String | 次の列挙型の値のみ受け入れます：`["M", "F"]`。 |
| `DOB` | ユーザーの生年月日 | いいえ | Unix タイムスタンプ文字列 | このフィールドの値が CleverTap の要件である Unix タイムスタンプ形式 `"$D_unix_time_value"` と一致するには、3つのオプションがあります: 1) **整数型**: カラムのデータが整数型の場合、既に Unix 形式であると仮定してそのまま使用され、形式 `"$D_unix_time_value"` が適用されます。2) **タイムスタンプキャスト**: カラムのデータがタイムスタンプとしてキャストされている場合、コネクタはそれを整数の Unix 時間形式に変換し、次に形式 `"$D_unix_time_value"` を適用します。*例:*`SELECT CAST(timestamp_column AS TIMESTAMP) AS dob`*.* 3) **ISO-8061 文字列形式**: カラムのデータが ISO-8061 形式の文字列型である場合、Unix 時間(整数)に変換され、次に形式 `"$D_unix_time_value"` が適用されます。値の末尾に `"Z"` が含まれていることを確認し、ISO-8601 日時文字列として認識されるようにします。また、常に UTC として認識されることに注意してください。例:`SELECT "2020-08-01T00:00:00Z" AS dob`*.* |


#### エクスポートクエリのフィールド/カラムレベル名

| フィールド名 | クエリ値 | フィールド用途 |
|  --- | --- | --- |
| phone | phone | ユーザーの電話番号 |
| name | name | ユーザー名 |
| email | email | ユーザーメール |
| MSG-whatsapp | MSG-whatsapp | Whatsapp ユーザー設定 |
| MSG-sms | MSG-sms | SMS ユーザー設定 |
| MSG-push | MSG-push | ユーザープッシュ設定 |


**クエリ例:**


```sql
SELECT
  IDENTITY,
  CAST(
 'objectid' AS VARCHAR
  ) AS objectId,
  name,
  email,
  'M',
  CAST(
 '+1234567890123456789' AS VARCHAR
  ) phone,
  '1995-05-15T00:00:00Z',
  CAST(
 email_pref AS BOOLEAN
  ) AS MSG_email,
  CAST(
 'true' AS BOOLEAN
  ) AS MSG_push,
  CAST(
 'true' AS BOOLEAN
  ) AS MSG_sms,
  CAST(
 'true' AS BOOLEAN
  ) AS MSG_whatsapp,
  CAST(
 json_parse('["Newsletters", "Promotions"]') AS arrayvarchar
  ) "Custom Value 1"
FROM
  clever_tap_upload_user_profiles LIMIT 1
```

**カスタムフィールドカラム**

| **カラムタイプ** | **説明** | **マッピング** | **追加仕様** |
|  --- | --- | --- | --- |
| 非デフォルトフィールド | デフォルトフィールドとしてリストされていないカラムは、カスタムフィールドとして扱われます。 | `profileData` オブジェクトのキー/値ペアとしてマッピング | カラム名と値はそのままマッピングされます。日時カラムは "timestamp" としてキャストするか、ISO-8601 日時文字列としてフォーマットする必要があります。配列カラムのプロパティ値は文字列である必要があり、100項目に制限され、各値は512文字に制限されます。日時または文字列配列のカスタムフィールドの処理に関するガイダンスについては、次のセクションを参照してください。 |


**日時の処理**

この統合では、日時カスタムフィールドカラムに対して、タイムスタンプとしてキャストされた値、または ISO-8601 日時文字列形式の値を処理できます。ISO-8601 日時文字列を使用する場合は、値の末尾に文字 "Z" を含めることで、コネクタが日時値を検出して Unix 時間値に変換し、CleverTap の API 契約で要求される形式 "$D_unix_time_value" を適用できるようにします。

#### 日時カスタムフィールドカラムの処理例

**1. タイムスタンプとしてのキャスト**

- ソースデータテーブルに文字列型のカラムを作成します:



```sql
ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;
```

- そのカラムに日時値文字列を挿入します:



```sql
INSERT INTO source_data_table (id, date_time_field)VALUES(1, '2024-08-28'),(2, '2024-08-28 15:30:00'),(3, '2024-08-28T15:30:00');
```

- カラム値をタイムスタンプとしてキャストします:



```sql
SELECT id, CAST(date_time_field AS timestamp) AS date_time_field FROM source_data_table;
```

**2. ISO-8601 日時文字列の使用**

- ソースデータテーブルに文字列型のカラムを作成します:

```
ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;
```
- そのカラムに日時値文字列を挿入します。"T" 区切り文字と末尾の "Z" を含む ISO-8601 形式であることを確認します:



```sql
INSERT INTO source_data_table (id, date_time_field)VALUES(1, '2024-08-28T00:00:00Z'),(2, '2024-05-28T15:30:00.123Z'),(3, '2024-02-28T15:30:00Z');
```

- クエリでカラムを直接使用します:



```sql
SELECT id, date_time_field FROM source_data_table;
```

**文字列配列カスタムフィールドカラムの処理**

統合がカラムのデータを正確に解釈し、CleverTap の文字列配列ユーザープロパティにマッピングするには、次のオプションを利用できます:

**1. 配列カラムの直接使用**

- ソースデータテーブルに文字列配列のカラムを作成します:



```sql
ALTER TABLE source_data_table ADD COLUMN array_column ARRAYVARCHAR;
```

- このカラムに文字列値の配列を挿入します:



```sql
INSERT INTO source_data_table (id, array_column)VALUES(2, ARRAY['fig', 'grape', 'honeydew', 'kiwi', 'lemon']),(3, ARRAY['mango', 'nectarine', 'orange', 'pear', 'quince']),(4, ARRAY['raspberry', 'strawberry', 'tangerine', 'ugli fruit', 'vanilla bean']),(5, ARRAY['watermelon', 'ximenia', 'yellow apple', 'zucchini', 'apricot']);
```

- クエリで文字列配列カラムを直接使用します:



```sql
SELECT id, array_column FROM source_data_table;
```

**2. JSON または JSON 配列にキャストされた文字列カラムの使用**

- ソースデータテーブルに文字列データ型のカラムを作成します:



```sql
ALTER TABLE source_data_table ADD COLUMN array_string_column VARCHAR;
```

- このカラムに配列文字列値を挿入します:



```sql
INSERT
  INTO
 source_data_table(
   id,
   array_string_column
 )
  VALUES(
 1,
 '["apple", "banana", "cherry", "date", "elderberry"]'
  ),
  (
 2,
 '["fig", "grape", "honeydew", "kiwi", "lemon"]'
  ),
  (
 3,
 '["mango", "nectarine", "orange", "pear", "quince"]'
  ),
),
(
  4,
  '["raspberry", "strawberry", "tangerine", "ugli fruit", "vanilla bean"]'
),
(
  5,
  '["watermelon", "ximenia", "yellow apple", "zucchini", "apricot"]'
)
;
```

- データセットエクスポートクエリで、文字列配列カラムをJSON配列またはJSONにキャストして使用します：
  - 配列としてキャスト：



```
SELECT id, CAST(json_parse(array_string_column) AS ARRAYVARCHAR) AS array_column FROM source_data_table;
```

- JSON配列としてキャスト：



```
SELECT id, CAST(json_parse(array_string_column) AS JSON) AS array_column FROM source_data_table;
```

### II. コネクタ設定

![](/assets/config_user_profiles.847c6ab8f4b75b5265bb7d27d5d2f6326a3ae34b6210fd18b2f3a7ddccf63403.b90d17e3.png)

| **設定オプション** | **値** | **説明** |
|  --- | --- | --- |
| Target Data Entity | User Profiles | この機能では「User Profiles」に設定します。 |
| User Profiles Operation | Upload User Profiles | ユーザープロファイルをアップロードする操作を指定します。 |
| Array Property Operation | replace/append/remove | 配列プロパティの処理方法を決定します：- **replace**: 既存の配列プロパティを新しい値で上書きします。- **append**: 既存の配列プロパティに指定された値を追加します。- **remove**: 既存の配列プロパティから指定された値を削除します。 |


### User Profilesのその他の操作モードの詳細ガイド

**User Profiles**操作では、ユーザープロファイルデータを管理および更新するためのさまざまな操作を実行できます。以下のセクションでは、この機能で利用可能な4つの異なる操作モードについて説明します：

1. **Upload Device Tokens**: ユーザープロファイルに関連付けられたデバイストークンを追加または更新します。
2. **Demerge User Profile**: マージされたユーザープロファイルを分離します。
3. **Update Email/Phone Subscription**: 既存のユーザープロファイルのメールまたは電話のサブスクリプションステータスを設定します。
4. **Disassociate a Phone Number**: 既存のユーザープロファイルから電話番号を切り離します。


各操作モードには、CleverTapへのデータアップロードを確実に成功させるために従う必要がある特定の要件と設定があります。

### I. エクスポートクエリの構築

前述の操作を実行するには、特定のデータ仕様に準拠したエクスポートクエリを作成する必要があります。これらは2つのレベルに分かれています。

#### エクスポートクエリの仕様

| **操作モード** | **必須カラム** | **説明** |
|  --- | --- | --- |
| **Upload Device Tokens** | `objectId`, `id`, `type` | クエリ結果には、`objectId`（CleverTapオブジェクトID）、`id`（デバイストークン）、および`type`（デバイスプラットフォームタイプ）を含める必要があります。追加の必須フィールド：Chromeベースのトークンには`p256dh`と`auth`が必要です。 |
| **Demerge User Profile** | `identity` | クエリ結果には、分離するユーザーIDを含む`identity`カラムを含める必要があります。 |
| **Update Email/Phone Subscription** | `type`, `value`, `status` | クエリ結果には、`type`（連絡先タイプ）、`value`（連絡先の値）、および`status`（サブスクリプションステータス）を含める必要があります。 |
| **Disassociate a Phone Number** | `value` | クエリ結果は、切り離す電話番号を含む`value`カラムで構成される必要があります。 |


- **NULL値カラム**: NULL値を持つカラムは無視されます。
- **無視されるカラム**: 選択した操作モードに必要ないカラムは無視されます。


#### 2. フィールドレベルの詳細

**各操作のデフォルトフィールドカラム**

| **操作モード** | **フィールド** | **説明** | **必須** | **データ型** | **追加仕様** |
|  --- | --- | --- | --- | --- | --- |
| **Upload Device Tokens** | `objectId` | CleverTapのobjectId | はい | String | ユーザーを一意に識別する必要があります。 |
|  | `id` | デバイストークン | はい | String | 有効なデバイストークンである必要があります。 |
|  | `type` | デバイスプラットフォームタイプ | はい | String | サポートされる値は`apns`、`gcm`、`fcm`、`wns`、`mpns`、`chrome`です。 |
|  | `p256dh` | Chrome Web プッシュ通知に使用される暗号化キー | 条件付き | String | `type`が`chrome`の場合のみ必須です。 |
|  | `auth` | Chrome Web プッシュ通知の認証シークレット | 条件付き | String | `type`が`chrome`の場合のみ必須です。 |
| **Demerge User Profile** | `identity` | 分離するプロファイルのユーザーID | はい | String |  |
| **Update Email/Phone Subscription** | `type` | 連絡先タイプ | はい | String | 列挙型から次の値のみを受け入れることができます：`["phone", "email", "WhatsApp"]`。 |
|  | `value` | 連絡先の値 | はい | String | 電話番号はE.164形式（`+[国コード][国内有効番号]`）またはメールアドレスです。 |
|  | `status` | 連絡先のサブスクリプションステータス | はい | String | 次の列挙型の値のみ受け付けます: `["Unsubscribe", "Resubscribe"]`. |
| **電話番号の関連付け解除** | `value` | 電話番号の値 | はい | String | E.164電話番号形式でフォーマットする必要があります。形式は `+[国コード][国内有意番号]` です。 |


### II. コネクタの設定

![](/assets/config_user_profiles_other-modes.378422c79d66ac7b3d26487ee6d2a7e8d1fdc66d5b4c06af586b667ae57ec74e.b90d17e3.png)

各操作モードに対して、コネクタは特定の設定で構成する必要があります。

| **設定オプション** | **値** | **説明** |
|  --- | --- | --- |
| **Target Data Entity** | User Profiles | すべての操作で「User Profiles」に設定します。 |
| **User Profiles Operation** | Upload Device Tokens | デバイストークンを追加または更新するには、「Upload Device Tokens」を選択します。 |
|  | Demerge User Profile | マージされたプロファイルを分離するには、「Demerge User Profile」を選択します。 |
|  | Update Email/Phone Subscription | メールまたは電話のサブスクリプションステータスを設定するには、「Update Email/Phone Subscription」を選択します。 |
|  | Disassociate a Phone Number | ユーザープロファイルから電話番号の接続を解除するには、「Disassociate a Phone Number」を選択します。 |
| **Array Property Operation** | 無視 | この設定はすべての操作で無視されます。 |


## Target Data Entity: User Events

### I. エクスポートクエリの作成

CleverTapにユーザーイベントデータを正常にアップロードするには、エクスポートクエリが以下の詳細なデータ仕様に準拠する必要があります。このセクションでは、デフォルトフィールドとカスタムフィールドの両方の要件、および特定のカラム命名規則とデータ制約について説明します。

#### 1. エクスポートクエリ仕様

| **仕様** | **説明** |
|  --- | --- |
| **必須カラム** | - 次のカラムの少なくとも1つが存在する必要があります: `identity` または `objectid`。 - `evtName` カラムは必須です。 |
| **Null値のカラム** | Null値を持つカラムは無視されます。 |
| **カラム命名規則** | - カラム名には次の文字を含めることはできません: `&`, `$`, `"`, `,`, `%`, `>`, `<`, `!`. - カラム名は120文字を超えてはいけません。 |
| **最大カラム値の長さ** | デフォルトフィールドとカスタムフィールドの両方のカラム値は、512文字を超えてはいけません。 |
| **重複カラム** | 重複したカラムは許可されません。 |


#### 2. フィールド/カラムレベルの仕様

**デフォルトフィールドのカラム**

| **フィールド/カラム/エイリアス** | **説明** | **必須** | **データ型** | **追加仕様** |
|  --- | --- | --- | --- | --- |
| `identity` | ユーザーIDフィールド | はい、`objectid` が存在しない場合 | スカラー型（string、integer、boolean） |  |
| `objectid` | ユーザーIDフィールド | はい、`identity` が存在しない場合 | スカラー型（string、integer、boolean） |  |
| `ts` | イベントのタイムスタンプ | いいえ | Integer/Long | CleverTapのUnixタイムスタンプ形式の要件に合わせるため、このフィールドの値には3つのオプションがあります: 1) **Integer型**: カラムのデータがinteger型の場合、すでにUnix形式であると想定してそのまま使用されます。 2) **Timestampキャスト**: カラムのデータがtimestampとしてキャストされている場合、コネクタはそれをinteger Unix時刻形式に変換します。例: `SELECT CAST(timestamp_field AS TIMESTAMP) AS ts`。 3) **ISO-8061文字列形式**: カラムのデータがISO-8061形式の文字列型の場合、Unix時刻（integer）に変換されます。ISO-8601日時文字列として認識されるように、値が「Z」で終わることを確認し、常にUTCとして認識されることに注意してください。例: `SELECT "2020-08-01T00:00:00Z" AS ts`。 |
| `evtName` | イベント名 | はい | String |  |
| `Items[index].KeyName` | 「Charged Event」の製品/アイテムのリスト | いいえ | Array of Objects | `Items` フィールドは、`evtName` オブジェクトのオブジェクトの配列である必要があります。特定のカラム名パターンに従うと、コネクタがこのオブジェクトの配列を作成するのに役立ちます: - **カラムパターン**: カラム名は次のパターンに従う必要があります: *Items*`[x].field_name、例: ``Items[0].Category`*、*`Items[0].Book name`。ここで `x` は配列インデックスを表す整数です。 - **ハードコーディングとフォーマット**: プレフィックス `Items` はハードコーディングされており、変更しないでください。カラム名の `field_name` 部分は、再フォーマットせずにそのまま使用する必要があります。 - **配列のインデックス**: 配列インデックス `x` が整数であることを確認してください。インデックス値は0から始める必要はありません。配列インデックスで数値をスキップすることも許可されています。  **例:**  カラム/エイリアス: *Items[0].Book name, Items[0].Category, Items[0].Quantity* は以下のように変換されます  `"evtData": {       "Items": [        {            "Category": "books",            "Book name": "The millionaire next door",            "Quantity": 1        }    ]}` |


**カスタムフィールドのカラム**

| **カラムタイプ** | **説明** | **マッピング** | **追加仕様** |
|  --- | --- | --- | --- |
| デフォルト以外のフィールド | デフォルトフィールドとしてリストされていないカラムは、カスタムフィールドとして扱われます。 | `evtData` オブジェクト内のキー/値ペアとしてマップされます | カラム名と値はそのままマップされます。日時カラムは「timestamp」としてキャストするか、ISO-8601日時文字列としてフォーマットする必要があります。詳細については、Upload User Profilesガイドの「日時カスタムフィールドカラムの処理」セクションを参照してください。 |


### II. コネクタの設定

![](/assets/config_user_events.50873c4323f3e21584c7970d3177add14104ae3ee55cc729c49c23637f365447.b90d17e3.png)

| **設定オプション** | **値** | **説明** |
|  --- | --- | --- |
| Target Data Entity | User Events | この機能では「User Events」に設定します。 |


## Target Data Entity: User Audiences - Custom List

この機能を使用すると、ユーザーIDのリストをCleverTapにアップロードして、ユーザーのセグメントを作成できます。以下の詳細は、エクスポートクエリの作成とコネクタの設定をガイドします。

### I. エクスポートクエリの作成

CleverTapにユーザーIDのリストをアップロードしてセグメントを正常に作成するには、特定のデータ仕様に準拠するエクスポートクエリを構築する必要があります。これらは2つのレベルに分かれています。

#### 1. エクスポートクエリ仕様

| **仕様** | **説明** |
|  --- | --- |
| **必須カラム** | クエリ結果には `type` と `identity` カラムを含める必要があります。 |
| **Null値のカラム** | Null値を持つカラムは無視されます。 |
| **無視されるカラム** | 必須カラムのいずれでもないカラムは無視されます。 |


#### 2. フィールド/カラムレベルの仕様

**デフォルトのフィールドカラム**

| **フィールド** | **説明** | **必須** | **データ型** | **追加仕様** |
|  --- | --- | --- | --- | --- |
| `type` | ユーザーID タイプ | はい | String | 値は `g` または `i` のみです。 |
| `identity` | ユーザーID 値 | はい | String または Integer |  |


### II. コネクタ設定

![](/assets/config_custom_llist.6501304b5abfdb137e71bb8663c8c888be79de616a4248502453c1fa941db18e.b90d17e3.png)

| **設定オプション** | **値** | **説明** |
|  --- | --- | --- |
| Target Data Entity | User Audiences - Custom List | この機能には「User Audiences - Custom List」に設定します。 |
| Name for Custom List Upload | [Custom List Segment Name] | CleverTap ダッシュボード UI でセグメント名を指定します。 |
| Custom List Upload User Email | [User Email] | カスタムリストセグメントのアップロードを実行した CleverTap ユーザーのユーザーメールを入力します。Admin Role のメールを入力する必要があります。それ以外の場合、ジョブは失敗します。 |
| Segment Operation Mode | Create New Segment / Update Existing Segment | CleverTap に新しいセグメントを追加する1回限りのジョブには「Create New Segment」を選択します。既存のセグメントを変更するには「Update Existing Segment」を選択します。これは定期的に実行するようにスケジュールできます。 |


## (オプション) CLI を使用したエクスポート統合

[TD Toolbelt](https://toolbelt.treasuredata.com/) は、CLI からクエリ結果のエクスポートをトリガーできます。`td query` コマンドの `--result` オプションを使用して、エクスポートジョブのパラメーターを指定するのが最適です。詳細については、[この記事](https://docs.treasuredata.com/articles/pd/querying-and-importing-data-to-treasure-data-from-the-command-line)を参照してください。

オプションの形式は JSON で、一般的な構造は次のとおりです。

**User Profiles**


```json
{
  "type": "clever_tap",
  "account_id": "986-XXX-XXYY",
  "passcode": "XXYY",
  "region": "UNITED_STATES",
  "target_data_entity": "USER_PROFILES",
  "user_profiles_operation": "UPLOAD_USER_PROFILES",
  "array_operation": "REPLACE",
  "skip_invalid_record": true,
  "thread_count": 5
}
```

**User Event**


```json
{
  "type": "clever_tap",
  "account_id": "986-XXX-XXYY",
  "passcode": "XXYY",
  "region": "UNITED_STATES",
  "target_data_entity": "USER_EVENTS",
  "skip_invalid_record": true,
  "thread_count": 5
}
```

**Custom List**


```json
{
  "type": "clever_tap",
  "account_id": "986-XXX-XXYY",
  "passcode": "XXYY",
  "region": "UNITED_STATES",    "target_data_entity": "USER_AUDIENCES_CUSTOM_LIST",
  "name_for_custom_list_upload": "demo name",
  "email_for_custom_list_upload": "demo@example.com",
  "segment_operation_mode": "UPDATE",
  "skip_invalid_record": true
}
```

### CLI パラメーター

| 名前 | 説明 | 値 | デフォルト値 | 必須 |
|  --- | --- | --- | --- | --- |
| td_authentication_id | TD コンソールに存在する CleverTap 認証の ID です。 |  |  |  |
| account_id | CleverTap のアカウント ID | String | null | はい、td_authentication_id が存在しない場合 |
| passcode | CleverTap のパスコード | String | null | はい、td_authentication_id が存在しない場合 |
| region | CleverTap のインスタンスリージョン | サポートされる値:  - INDIA - SINGAPORE - UNITED_STATES - INDONESIA - MIDDLE_EAST - EUROPE | UNITED_STATES | はい、td_authentication_id が存在しない場合 |
| target_data_entity | エクスポート対象データ | サポートされる値:   - USER_PROFILES   - USER_EVENTS  - USER_AUDIENCES_CUSTOM_LIST | USER_PROFILES | はい |
| user_profiles_operation | ユーザープロファイルのエクスポートモード | サポートされる値:   - UPLOAD_USER_PROFILES - UPLOAD_DEVICE_TOKENS - DEMERGE_USER_PROFILE - UPDATE_EMAIL_PHONE_SUBSCRIPTION - DISASSOCIATE_A_PHONE_NUMBER | UPLOAD_USER_PROFILES | はい、target_data_entity が USER_PROFILES の場合 |
| array_operation | Upload User Profiles 時の JSON 配列カラムの配列操作 | サポートされる値:   - REPLACE - APPEND - REMOVE | REPLACE | はい、user_profiles_operation が UPLOAD_USER_PROFILES の場合 |
| name_for_custom_list_upload | セグメントの名前 | String |  | はい、target_data_entity が USER_AUDIENCES_CUSTOM_LIST の場合 |
| email_for_custom_list_upload | アップロード結果を受信するメール。メールは CleverTap の Admin ロールに属している必要があります。 | String |  | はい、target_data_entity が USER_AUDIENCES_CUSTOM_LIST の場合 |
| segment_operation_mode | セグメント操作モード。新しいセグメントを作成するか、既存のセグメントを更新します。 | サポートされる値:   - CREATE - UPDATE | UPDATE | はい、target_data_entity が USER_AUDIENCES_CUSTOM_LIST の場合 |
| thread_count | CleverTap サーバーへの同時リクエスト数。 | Number | 5 | はい、target_data_entity が USER_PROFILES または USER_EVENTS の場合 |
| skip_invalid_record | 無効なレコードを処理する際にジョブの実行を継続するか停止するかを制御するフラグ。 | Boolean | false | いいえ |


### 使用例

1. **Upload User Profiles**



```bash
td query \
  -d db_name \
  -w "select identity,
             objectid,
             name,
             email,
             gender,
             phone,
             dob,
             msg_email,
             msg_push,
             msg_sms,
             msg_whatsapp,
             CAST(json_parse('["Newsletters", "Promotions"]') AS JSON) AS 'Custom Value 1'
      from tbl_name" \
  --type presto \
  --result '{
    "type": "clever_tap",
    "td_authentication_id": 514830,
    "target_data_entity": "USER_PROFILES",
    "user_profiles_operation": "UPLOAD_USER_PROFILES",
    "array_operation": "REPLACE",
    "thread_count": 5,
    "skip_invalid_record": true
  }'
```

1. **Upload Device Tokens**



```bash
td query \
  -d db_name \
  -w "select objectId,
             Id,
             Type,
             p256dh,
             auth
      from tbl_name" \
  --type presto \
  --result '{
    "type": "clever_tap",
    "td_authentication_id": 514830,
    "target_data_entity": "USER_PROFILES",
    "user_profiles_operation": "UPLOAD_DEVICE_TOKENS",
    "thread_count": 5,
    "skip_invalid_record": true
  }'
```

1. **De-Merge User Profile**



```bash
td query \
  -d db_name \    -w "select identity
     from tbl_name" \
 --type presto \
 --result '{
   "type": "clever_tap",
   "td_authentication_id": 514830,
   "target_data_entity": "USER_PROFILES",
   "user_profiles_operation": "DEMERGE_USER_PROFILE",
   "thread_count": 5,
   "skip_invalid_record": true
 }'
```

1. **メール/電話のサブスクリプションを更新**



```bash
td query \
 -d db_name \
 -w "select type,
            value,
            status
     from tbl_name" \
 --type presto \
 --result '{
   "type": "clever_tap",
   "td_authentication_id": 514830,
   "target_data_entity": "USER_PROFILES",
   "user_profiles_operation": "UPDATE_EMAIL_PHONE_SUBSCRIPTION",
   "thread_count": 5,
   "skip_invalid_record": true
 }'
```

1. **電話番号の関連付けを解除**



```bash
td query \
 -d db_name \
 -w "select value
     from tbl_name" \
 --type presto \
 --result '{
   "type": "clever_tap",
   "td_authentication_id": 514830,
   "target_data_entity": "USER_PROFILES",
   "user_profiles_operation": "DISASSOCIATE_A_PHONE_NUMBER",
   "thread_count": 5,
   "skip_invalid_record": true
 }'
```

1. **ユーザーイベントをアップロード**



```bash
td query \
 -d db_name \
 -w "select identity,
            objectid,
            ts,
            evtname,
            product_name as 'Product name',
            category as 'Category',
            price as 'Price',
            currency as 'Currency',
            amount as 'Amount',
            payment_mode as 'Payment mode',
            delivery_by as 'Delivery By',
            items_0__category AS 'Items[0].Category',
            items_0__book_name as 'Items[0].Book name',
            items_0__quantity as 'Items[0].Quantity',
            items_1__category AS 'Items[1].Category',
            items_1__book_name as 'Items[1].Book name',
            items_1__quantity as 'Items[1].Quantity'
     from tbl_name" \
 --type presto \
 --result '{
   "type": "clever_tap",
   "td_authentication_id": 514830,
   "target_data_entity": "USER_EVENTS",
   "thread_count": 5,
   "skip_invalid_record": true
 }'
```

1. **カスタムリストをアップロード**



```bash
td query \
 -d db_name \
 -w "select type,
            identity
     from tbl_name" \
 --type presto \
 --result '{
   "type": "clever_tap",
   "td_authentication_id": 514830,
   "target_data_entity": "USER_AUDIENCES_CUSTOM_LIST",
   "name_for_custom_list_upload": "Test",
   "email_for_custom_list_upload": "test@example.com",
   "segment_operation_mode": "UPDATE",
   "skip_invalid_record": true
 }'
```

## 関連記事

#### その他の設定

- Result Exportは、定期的にターゲット宛先にデータをアップロードするように[スケジュール](https://docs.treasuredata.com/articles/pd/scheduling-jobs-using-td-console)できます。
- すべてのインポートおよびエクスポート統合は、[TD Workflow](https://docs.treasuredata.com/articles/pd/about-treasure-workflow)に追加できます。**td**データオペレーターは、クエリ結果を指定された統合にエクスポートできます。詳細については、[Treasure Dataオペレーターのリファレンス](https://docs.treasuredata.com/articles/pd/reference-for-treasure-data-operators/a/h1_76525622)を参照してください。