# Incremental Activationパラメータ

Incremental Activationはベータリリースです。詳細については、カスタマーサクセス担当者にお問い合わせください。

このリファレンスドキュメントでは、Incremental Activationワークフローテンプレートで使用されるすべてのパラメータについて説明します。パラメータは、ワークフロー設定の`_export.params`ブロックで定義されます。

## パラメータ概要

| パラメータ | 必須 | 自動入力 | 説明 |
|  --- | --- | --- | --- |
| `api_endpoint` | はい | いいえ | Incremental Activationワークフローを取得するAPIエンドポイント |
| `id_key` | はい | いいえ | ソーステーブルの一意識別子カラム |
| `delta_keys` | はい | いいえ | 変更をチェックするカラムの配列 |
| `activation_mappings` | はい | いいえ | デルタレコードからコネクタへのマッピングの配列 |
| `activation_actions_db` | 条件付き | はい（Activation Action） | ソースTDデータベース |
| `activation_actions_table` | 条件付き | はい（Activation Action） | ソーステーブル名 |
| `result_connection_settings` | 条件付き | はい（Activation Action） | 結果コネクタ設定オブジェクト |
| `result_connection_name` | 条件付き | はい（Activation Action） | コネクタ認証名 |


「自動入力」で「はい」とマークされているパラメータは、Audience Studio内でActivation Actionとして実行する場合に自動的に設定されます。スタンドアロンワークフローとして実行する場合は、すべての条件付きパラメータを手動で設定する必要があります。

## api_endpoint

**タイプ**: String
**必須**: はい
**自動入力**: いいえ

Incremental Activationワークフローを取得するためのAPIエンドポイントURL。値はTreasure Dataのサイトロケーションによって異なります。

### TDサイト別の値

| TDサイト | エンドポイントURL |
|  --- | --- |
| US (us01) | `https://integrations-gateway.us01.treasuredata.com` |
| EU (eu01) | `https://integrations-gateway.eu01.treasuredata.com` |
| Asia Pacific (ap02) | `https://integrations-gateway.ap02.treasuredata.com` |
| Japan (co.jp) | `https://integrations-gateway.treasuredata.co.jp` |


### 例


```yaml
_export:
  params:
    api_endpoint: "https://integrations-gateway.us01.treasuredata.com"
```

### バリデーション

- 有効なHTTPS URLである必要があります
- Treasure Dataのサイトロケーションと一致する必要があります
- 不正なエンドポイントはワークフローの失敗を引き起こします


## id_key

**タイプ**: String
**必須**: はい
**自動入力**: いいえ

ソーステーブル内のプロファイルの一意識別子（主キー）として機能するカラム名。このカラムのデータはすべての行で一意である必要があります。

### 目的

`id_key`カラムは以下の目的で使用されます：

- セグメントに追加された新しいプロファイルの識別
- セグメントから削除されたプロファイルの識別
- デルタ計算のためのActivation実行間でのプロファイルのマッチング


### 一般的な値

- `td_customer_id` - Treasure Dataの統合顧客ID
- `email` - メールアドレス
- `phone_number` - 電話番号
- `mobile_ad_id` - モバイル広告ID（IDFA、MAID）
- `customer_id` - カスタム顧客識別子


### 例


```yaml
_export:
  params:
    id_key: "email"
```

### 要件

`id_key`カラムには一意の値が含まれている必要があります。重複する値があると、デルタ計算でエラーが発生し、誤った結果が生成される可能性があります。

- カラムはソーステーブルに存在する必要があります
- 値は一意である必要があります（重複なし）
- 値はnullであってはなりません
- データ型は一貫している必要があります（すべて文字列またはすべて数値）


### ベストプラクティス

1. **安定した識別子を選択する**: まれにしか変更されないカラムを選択してください。IDが変更されると、プロファイルは「unchanged」ではなく「deleted」と「new」として表示されます。
2. **一意性を確認する**: 重複する値がないことを確認するクエリを実行してください：

```sql
SELECT id_key, COUNT(*)
FROM your_table
GROUP BY id_key
HAVING COUNT(*) > 1
```
3. **宛先要件と一致させる**: 宛先プラットフォームが特定の識別子（例：Meta用のメールハッシュ）を必要とする場合、`id_key`が一致していることを確認してください。


## delta_keys

**タイプ**: Array of Strings
**必須**: はい
**自動入力**: いいえ

プロファイルが「updated」か「unchanged」かを判断する際に変更をチェックするカラム名の配列。これらのカラムは、どの属性が更新ステータスをトリガーするかを定義します。

### 目的

`delta_keys`配列は以下を決定します：

- プロファイルが「updated」としてマークされるかどうか（いずれかのデルタキー値が変更された場合）
- プロファイルが「unchanged」としてマークされるかどうか（すべてのデルタキー値が同じままの場合）
- どの属性変更が再Activationをトリガーするか


### 例

**職種と組織の変更を追跡**：


```yaml
delta_keys: ["job_title", "organization"]
```

**サブスクリプションステータスの変更を追跡**：


```yaml
delta_keys: ["subscription_status", "tier_level"]
```

**ロケーションの変更を追跡**：


```yaml
delta_keys: ["city", "country", "postal_code"]
```

**複数の属性を追跡**：


```yaml
delta_keys: ["status", "tier", "email", "phone_number"]
```

### デフォルトの動作

`delta_keys`が空または指定されていない場合、デフォルトで`id_key`の値になります：


```yaml
# id_keyが"email"の場合、これら2つの設定は同等です
delta_keys: []
# は以下になります
delta_keys: ["email"]
```

### デルタキーの動作原理

ワークフローは各プロファイルの`delta_keys`カラムのハッシュを計算します：

1. **現在の実行**: 現在の`delta_keys`値のハッシュ
2. **前回の実行**: 前回の`delta_keys`値のハッシュ
3. **比較**: ハッシュが異なる場合、プロファイルは「updated」としてマークされます


**例**：

| 実行 | email | job_title | organization | デルタキーハッシュ | ステータス |
|  --- | --- | --- | --- | --- | --- |
| 1 | john@example.com | Engineer | Acme Corp | abc123 | new |
| 2 | john@example.com | Senior Engineer | Acme Corp | def456 | updated |
| 3 | john@example.com | Senior Engineer | Acme Corp | def456 | unchanged |


### ベストプラクティス

1. **関連する属性のみを含める**: 頻繁に変更されるが再Activationを必要としないカラム（例：`last_login_timestamp`）は含めないでください。
2. **ダウンストリームへの影響を考慮する**: 宛先プラットフォームがデータポイントの更新ごとに課金する場合、不要なデルタキーを最小限に抑えてください。
3. **代表的なデータでテストする**: デルタキーが過度にトリガーすることなく、関心のある変更をキャプチャしていることを確認してください。
4. **選択を文書化する**: 将来の参照のために、特定のカラムがデルタキーとして選択された理由を記録してください。


### 一般的なパターン

**Eコマース - ロイヤルティティアの変更**：


```yaml
delta_keys: ["loyalty_tier", "points_balance"]
```

**B2B - リードスコアリングの更新**：


```yaml
delta_keys: ["lead_score", "engagement_level", "company_size"]
```

**マーケティング - プリファレンス管理**：


```yaml
delta_keys: ["email_opt_in", "sms_opt_in", "preferred_channel"]
```

## activation_mappings

**タイプ**: Array of Objects
**必須**: はい
**自動入力**: いいえ

デルタレコードが宛先コネクタにどのように送信されるかを定義するマッピングオブジェクトの配列。各マッピングはデルタステータスをコネクタ設定に接続します。

詳細については、[Incremental Activationマッピング](/ja/products/customer-data-platform/audience-studio/activation/incremental-activation-mappings)を参照してください。

### 構造

各マッピングオブジェクトには以下が含まれます：

| フィールド | タイプ | 必須 | 説明 |
|  --- | --- | --- | --- |
| `delta_status` | String | はい | `new`、`updated`、`deleted`、`unchanged`のいずれか |
| `connector_field` | String | はい | コネクタ設定フィールド名（例：`mode`、`operation`） |
| `connector_field_value` | String | はい | 設定する値（例：`append`、`delete`、`replace`） |


### 例


```yaml
activation_mappings: [
  {
    "delta_status": "new",
    "connector_field": "mode",
    "connector_field_value": "append"
  },
  {
    "delta_status": "updated",
    "connector_field": "mode",
    "connector_field_value": "append"
  },
  {
    "delta_status": "deleted",
    "connector_field": "mode",
    "connector_field_value": "delete"
  }
]
```

### 制限

- 最大4つのマッピング要素（デルタステータスタイプごとに1つ）
- 各`delta_status`値は一度だけ出現する必要があります


## activation_actions_db

**タイプ**: String
**必須**: 条件付き
**自動入力**: はい（Activation Actionとして実行する場合）

処理するテーブルを含むソースTDデータベースの名前。

### 自動入力される場合

Audience Studio内でActivation Actionとして実行する場合、このパラメータはシンジケーションデータベース（例：`cdp_syndication_123`）に自動的に設定されます。

### 必須の場合

スタンドアロンワークフローとして実行する場合、このパラメータを手動で指定する必要があります：


```yaml
_export:
  params:
    activation_actions_db: "my_customer_database"
```

### バリデーション

- データベースがTDアカウントに存在する必要があります
- ユーザーはデータベースに対する適切な権限を持っている必要があります


## activation_actions_table

**タイプ**: String
**必須**: 条件付き
**自動入力**: はい（Activation Actionとして実行する場合）

処理するデータを含むデータベース内のソーステーブルの名前。

### 自動入力される場合

Audience Studio内でActivation Actionとして実行する場合、このパラメータはセグメントシンジケーションテーブル（例：`segment_12345`）に自動的に設定されます。

### 必須の場合

スタンドアロンワークフローとして実行する場合、このパラメータを手動で指定する必要があります：


```yaml
_export:
  params:
    activation_actions_table: "customer_profiles"
```

### バリデーション

- テーブルは指定されたデータベースに存在する必要があります
- テーブルには`id_key`と`delta_keys`で指定されたカラムが含まれている必要があります
- ユーザーはテーブルに対する読み取り権限を持っている必要があります


## result_connection_settings

**タイプ**: Object
**必須**: 条件付き
**自動入力**: はい（Activation Actionとして実行する場合）

結果エクスポートコネクタの設定オブジェクト。構造は宛先コネクタのタイプによって異なります。

### 自動入力される場合

Audience Studio内でActivation Actionとして実行する場合、このパラメータはActivation設定に基づいて自動的に入力されます。

### 必須の場合

スタンドアロンワークフローとして実行する場合、コネクタ設定を手動で指定する必要があります。

### 例 - Snowflake


```yaml
result_connection_settings:
  type: "snowflake"
  database: "MARKETING_DB"
  schema: "PUBLIC"
  table: "CUSTOMER_SEGMENTS"
  mode: "append"
```

### 例 - Google Sheets


```yaml
result_connection_settings:
  type: "google_sheets"
  spreadsheet_id: "1ABC...xyz"
  sheet_name: "Customer List"
  mode: "replace"
```

### コネクタ固有の要件

必須フィールドとサポートされる値については、宛先コネクタのドキュメントを参照してください。

## result_connection_name

**タイプ**: String
**必須**: 条件付き
**自動入力**: はい（Activation Actionとして実行する場合）

Treasure Dataで設定されたコネクタ認証の名前。

### 自動入力される場合

Audience Studio内でActivation Actionとして実行する場合、このパラメータはActivationで選択された認証に基づいて自動的に入力されます。

### 必須の場合

スタンドアロンワークフローとして実行する場合、認証名を手動で指定する必要があります：


```yaml
_export:
  params:
    result_connection_name: "my_snowflake_connection"
```

### バリデーション

- 認証がTDアカウントに存在する必要があります
- 認証が有効で期限切れでない必要があります
- ユーザーは認証を使用する権限を持っている必要があります


## 完全なパラメータ例

### Activation Actionモード

ユーザー指定のパラメータのみを設定します：


```yaml
timezone: "UTC"
_export:
  params:
    api_endpoint: "https://integrations-gateway.us01.treasuredata.com"
    id_key: "email"
    delta_keys: ["subscription_status", "tier"]
    activation_mappings: [
      {
        "delta_status": "new",
        "connector_field": "mode",
        "connector_field_value": "append"
      },
      {
        "delta_status": "deleted",
        "connector_field": "mode",
        "connector_field_value": "delete"
      }
    ]
```

### スタンドアロンモード

すべてのパラメータを設定します：


```yaml
timezone: "UTC"
_export:
  params:
    api_endpoint: "https://integrations-gateway.us01.treasuredata.com"
    id_key: "email"
    delta_keys: ["subscription_status", "tier"]
    activation_mappings: [
      {
        "delta_status": "new",
        "connector_field": "mode",
        "connector_field_value": "append"
      },
      {
        "delta_status": "updated",
        "connector_field": "mode",
        "connector_field_value": "append"
      }
    ]
    activation_actions_db: "customer_data"
    activation_actions_table: "unified_profiles"
    result_connection_name: "snowflake_production"
    result_connection_settings:
      type: "snowflake"
      database: "MARKETING"
      schema: "SEGMENTS"
      table: "ACTIVE_SUBSCRIBERS"
      mode: "append"
```

## 次のステップ

- [Incremental Activationの設定](/ja/products/customer-data-platform/audience-studio/activation/configure-incremental-activation)
- [Incremental Activationマッピング](/ja/products/customer-data-platform/audience-studio/activation/incremental-activation-mappings)
- [Incremental Activationのトラブルシューティング](/ja/products/customer-data-platform/audience-studio/activation/troubleshooting-incremental-activation)


## 関連トピック

- [Incremental Activation概要](/ja/products/customer-data-platform/audience-studio/activation/incremental-activation-overview)
- [Activation Actionsパラメータ](/ja/products/customer-data-platform/audience-studio/activation/activation-actions-parameters)