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

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

このガイドは、Incremental Activationワークフローを使用する際の一般的な問題を診断および解決するのに役立ちます。

## 一般的な問題

### 「Duplicate ID Key」エラーでワークフローが失敗する

**症状**: ワークフローの実行中に、`id_key`列に重複した値があることを示すエラーメッセージで失敗します。

**原因**: `id_key`として指定された列に一意でない値が含まれているため、正確な差分計算ができません。

**解決策**:

1. 次のクエリを実行して、`id_key`列に一意の値のみが含まれていることを確認します。

```sql
SELECT id_key_column, COUNT(*) as count
FROM your_database.your_table
GROUP BY id_key_column
HAVING COUNT(*) > 1
```
2. 重複が存在する場合は、次のいずれかを実行します。
  - 一意であることが保証されている別の列を選択します(例:`td_customer_id`)
  - 一意性を確保するためにソースデータをクリーンアップします
  - 複合キーアプローチを使用します(ガイダンスについてはサポートにお問い合わせください)
3. ワークフローの`id_key`パラメータを一意の列名で更新します。


### 差分の代わりに完全エクスポートが実行される

**症状**: すべてのアクティベーションが、差分変更のみではなくセグメント全体をエクスポートします。

**考えられる原因**:

1. **初回実行**: 初回のワークフロー実行では、常にベースラインを確立するために完全エクスポートが実行されます。
2. **Delta Keyの変更**: `id_key`または`delta_keys`パラメータを変更すると、ワークフローは完全エクスポートをトリガーします。
3. **履歴テーブルの削除**: ワークフローの履歴テーブルが手動で削除またはクリアされました。
4. **ワークフロー名の変更**: ワークフロー名を変更すると、履歴のない新しいワークフローインスタンスが作成されます。


**解決策**:

1. **初回実行の場合**: これは期待される動作です。後続の実行では、差分のみがエクスポートされます。
2. **パラメータ変更の場合**: `id_key`または`delta_keys`を変更した後、1回の完全エクスポートが必要です。この実行を期待されるものとしてマークし、後続の実行を監視してください。
3. **履歴削除の場合**: 履歴テーブル(`cdp_audience_{id}`データベース内)が削除された場合、次回の実行時に再作成されます。1回の完全エクスポートが必要です。
4. **ワークフロー名変更の場合**: ワークフローの名前変更は避けてください。必要な場合は、変更後に1回の完全エクスポートが行われることを想定してください。


### セグメントが変更されているにもかかわらず、差分レコードが送信されない

**症状**: セグメントに新規または変更されたプロファイルがありますが、ワークフローは宛先に送信されたレコード数を0と報告します。

**考えられる原因**:

1. **Activation Mappingsが設定されていない**: `activation_mappings`に、期待する差分ステータスが含まれていません。
2. **Delta Keysが変更を捕捉していない**: `delta_keys`の列に、変更された属性が含まれていません。
3. **ID Keyの不一致**: `id_key`が実行間で一致しません(例:一部のメールが変更されたときにメールを使用)。


**解決策**:

1. **アクティベーションマッピングを確認**: 期待されるすべての差分ステータスのマッピングがあることを確認します。

```yaml
activation_mappings: [
  {"delta_status": "new", "connector_field": "mode", "connector_field_value": "append"},
  {"delta_status": "updated", "connector_field": "mode", "connector_field_value": "append"}
]
```
2. **delta keysを確認**: 変更された列を`delta_keys`に追加します。

```yaml
delta_keys: ["status", "tier", "email", "phone"]
```
3. **ID keyの安定性を確認**: `id_key`列の値が実行間で変更されないことを確認します。


### 「Unsupported Mode」エラーでコネクタが失敗する

**症状**: ワークフローは差分計算を完了しますが、サポートされていないモードまたは操作に関するエラーで結果エクスポート中に失敗します。

**原因**: コネクタが、アクティベーションマッピングで指定された`connector_field_value`をサポートしていません。

**解決策**:

1. サポートされている操作については、コネクタのドキュメントを確認してください。
  - 一部のコネクタは`append`のみをサポート
  - 一部は`delete`または`remove`をサポートしていません
  - フィールド名はコネクタによって異なります(`mode` vs `operation` vs `action`)
2. `activation_mappings`をサポートされている値を使用するように更新します。
**例 - delete操作をサポートしていないコネクタ**:

```yaml
# サポートされていない場合はdeleteマッピングを削除
activation_mappings: [
  {"delta_status": "new", "connector_field": "mode", "connector_field_value": "append"},
  {"delta_status": "updated", "connector_field": "mode", "connector_field_value": "append"}
  # "deleted"マッピングを削除
]
```
3. 機能が制限されているコネクタの場合、別のアクティベーションモードまたはコネクタの使用を検討してください。


### APIエンドポイントエラー / 404 Not Found

**症状**: ワークフローが404エラーまたは「endpoint not found」で即座に失敗します。

**原因**: `api_endpoint`パラメータがTreasure Dataサイトの場所と一致していません。

**解決策**:

TDサイトに合わせて`api_endpoint`を更新します。

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


修正例:


```yaml
_export:
  params:
    api_endpoint: "https://integrations-gateway.eu01.treasuredata.com"  # us01からeu01に変更
```

### 「Column Not Found」エラーでワークフローが失敗する

**症状**: `id_key`または`delta_keys`で指定された列が存在しないことを示すエラーでワークフローが失敗します。

**原因**: 列名のスペルが間違っているか、ソーステーブルに列が存在しません。

**解決策**:

1. ソーステーブルの列名を確認します。

```sql
DESCRIBE your_database.your_table
```
2. 正確な列名(大文字小文字を区別)でワークフローパラメータを更新します。

```yaml
id_key: "td_customer_id"  # テーブルスキーマからの正確な名前
delta_keys: ["subscription_status", "loyalty_tier"]  # 正確な名前
```
3. Activation Actionとして実行している場合は、セグメント出力がOutput Mappingに必要な列を含んでいることを確認します。


### アクティベーションされたプロファイル数が正しくない

**症状**: 送信されたプロファイル数が期待と一致しません(多すぎるか少なすぎる)。

**考えられる原因**:

1. **Delta Keysが敏感すぎる**: `delta_keys`に列が多すぎて、ほとんどのプロファイルが「更新済み」とマークされています。
2. **Delta Keysが十分に敏感でない**: `delta_keys`に重要な列が欠けており、実際の変更が見逃されています。
3. **マッピングロジックエラー**: アクティベーションマッピングが意図した動作と一致していません。


**解決策**:

1. **差分の感度をテスト**: テストクエリを実行して、変更されたとマークされるプロファイルの数を確認します。

```sql
SELECT
  COUNT(*) as total_profiles,
  SUM(CASE WHEN status_changed THEN 1 ELSE 0 END) as changed_profiles
FROM your_table
```
2. **delta keysを調整**: どの変更が再アクティベーションをトリガーするかに基づいて、列を追加または削除します。

```yaml
# 敏感すぎる - すべてのプロファイル変更が更新をトリガー
delta_keys: ["last_login", "last_page_view", "session_count"]

# より良い - 意味のある変更のみが更新をトリガー
delta_keys: ["subscription_tier", "email_opt_in"]
```
3. **アクティベーションログを確認**: ワークフロー実行ログを確認して、差分ステータスの内訳を確認します。


### Permission Deniedエラー

**症状**: データベース、テーブル、またはコネクタにアクセスする際に「permission denied」でワークフローが失敗します。

**原因**: ワークフローを実行しているユーザーに必要な権限がありません。

**解決策**:

1. **ワークフロー権限**: ワークフローに、アクティベーション作成者のViewおよびRunアクセス権があることを確認します。[ワークフロー権限の設定](/products/control-panel/security/policies/configuring-workflow-permissions)を参照してください。
2. **データベース権限**: ユーザーが以下を持っていることを確認します。
  - ソースデータベースとテーブルへの読み取りアクセス
  - `cdp_audience_{id}`データベースへの書き込みアクセス(履歴テーブル用)
3. **コネクタ権限**: ユーザーが結果コネクタ認証にアクセスできることを確認します。
4. 必要な権限を付与するには、TD管理者にお問い合わせください。


### スタンドアロンワークフローの失敗 - パラメータの欠落

**症状**: スタンドアロンワークフローが`activation_actions_db`、`activation_actions_table`、または接続パラメータの欠落に関するエラーで失敗します。

**原因**: スタンドアロンワークフロー(Activation Actionとしてではなく)として実行する場合、これらのパラメータを手動で設定する必要があります。

**解決策**:

スタンドアロンモードに必要なすべてのパラメータを追加します。


```yaml
_export:
  params:
    api_endpoint: "https://integrations-gateway.us01.treasuredata.com"
    id_key: "email"
    delta_keys: ["status", "tier"]
    activation_mappings: [
      {"delta_status": "new", "connector_field": "mode", "connector_field_value": "append"}
    ]
    # スタンドアロンモードに必要:
    activation_actions_db: "my_database"
    activation_actions_table: "my_table"
    result_connection_name: "my_connector_auth"
    result_connection_settings:
      type: "snowflake"
      database: "TARGET_DB"
      schema: "PUBLIC"
      table: "TARGET_TABLE"
      mode: "append"
```

### 一貫性のない差分結果または状態の競合

**症状**: 差分計算が予期しない結果を生成し、新規、更新、または削除されたプロファイルの数が正しくありません。複数のワークフロー実行で一貫性のない動作または競合する状態が表示されます。

**原因**: 同じソーステーブルに対して複数のワークフローが同時に実行されています。操作中にテーブルがロックされないため、同時実行ワークフローが互いの差分計算に干渉し、状態の競合につながる可能性があります。

**解決策**:

1. **ワークフロースケジュールの確認**: 同じソーステーブルに対して同時に実行されるようにスケジュールされている複数のワークフローまたはアクティベーションがあるかどうかを確認します。
2. **スケジュールの調整**: 特定のテーブルを一度に1つのワークフローのみで処理するようにします。
  - ワークフロースケジュールをずらして、同時ではなく順次実行するようにします
  - 完了を確保するために、実行間に十分なバッファー時間を追加します
  - 複数の関連ワークフローを実行する場合は、ワークフロー依存関係を使用します
3. **例 - ずらしたスケジュール**:

```
table_1のワークフローA: 00:00に実行(約15分かかる)
table_1のワークフローB: 00:30に実行(安全、重複なし)
table_2のワークフローC: 00:00に実行(安全、異なるテーブル)
```
4. **実行の監視**: ワークフロー実行ログを使用して、ワークフローが重複していないことを確認します。
5. **ベストプラクティス**: 同じセグメントを複数の宛先にアクティベートする必要がある場合は、複数のアクティベーションマッピングを持つ単一のIncremental Activationワークフローを作成するか、並列ワークフローの代わりに順次アクティベーションアクションを使用します。


## デバッグのヒント

### 詳細ログを有効にする

ワークフローにログを追加して、差分計算を追跡します。


```yaml
+fetch_incremental_activation_wf:
  http_call>: "${params.api_endpoint}/integration_workflow/workflows/incremental_activation/fetch"
  # ... 残りの設定 ...

+log_completion:
  echo>: "Incremental activation completed successfully"
```

### 履歴テーブルを確認する

ワークフローは`cdp_audience_{id}`データベースに履歴テーブルを作成します。これらのテーブルをクエリして、差分計算に使用されたデータを理解できます。


```sql
-- 最後のアクティベーションスナップショットを表示
SELECT * FROM cdp_audience_123.incremental_activation_history
LIMIT 100
```

### 小さなセグメントでテストする

本番環境にデプロイする前に:

1. 小さなテストセグメント(100〜1000プロファイル)を作成します
2. incremental activationワークフローを実行します
3. 差分結果が期待と一致することを手動で確認します
4. 徐々にセグメントサイズを増やします


### ワークフロー実行ログを確認する

1. **TD Data Workbench** > **Workflows**に移動します
2. Incremental Activationワークフローを開きます
3. 最近の実行をクリックします
4. エラーメッセージと差分レコード数のログを確認します


## サポートを受ける

問題が継続する場合:

1. **診断情報を収集**:
  - ワークフロー設定(サニタイズ済み、認証情報なし)
  - ワークフローログからのエラーメッセージ
  - 期待される動作と実際の動作
  - TDサイトの場所(US、EU、AP、JP)
2. **サポートに問い合わせ**:
  - TDコンソールからサポートチケットを送信
  - カスタマーサクセス担当者に連絡
  - 収集したすべての診断情報を含める
3. **ベータフィードバック**:
  - これはベータ機能であるため、フィードバックは製品の改善に役立ちます
  - 予期しない動作や機能リクエストをCSRに報告してください


## 次のステップ

- [Incremental Activationの概要](/ja/products/customer-data-platform/audience-studio/activation/incremental-activation-overview)
- [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-parameters)
- [Incremental Activationマッピング](/ja/products/customer-data-platform/audience-studio/activation/incremental-activation-mappings)


## 関連トピック

- [Activation Actions](/ja/products/customer-data-platform/audience-studio/activation/activation-actions)
- [Activation Actionsパラメータ](/ja/products/customer-data-platform/audience-studio/activation/activation-actions-parameters)
- [ワークフローの作成と編集](/products/customer-data-platform/data-workbench/workflows/getting-started-with-treasure-workflow)