Incremental Activationパラメータ

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Cursorに接続

  CursorにMCPサーバーをインストール
• VS Codeに接続

  VS CodeにMCPサーバーをインストール

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

パラメータ概要

api_endpoint

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

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

TDサイト別の値

例

_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 - カスタム顧客識別子

例

_export:
  params:
    id_key: "email"

要件

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

ベストプラクティス

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

例

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

delta_keys: ["job_title", "organization"]

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

delta_keys: ["subscription_status", "tier_level"]

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

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

複数の属性を追跡：

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

デフォルトの動作

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

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

デルタキーの動作原理

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

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

例：

ベストプラクティス

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

一般的なパターン

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

delta_keys: ["loyalty_tier", "points_balance"]

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

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

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

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

activation_mappings

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

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

詳細については、Incremental Activationマッピングを参照してください。

構造

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

例

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）に自動的に設定されます。

必須の場合

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

_export:
  params:
    activation_actions_db: "my_customer_database"

バリデーション

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

activation_actions_table

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

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

自動入力される場合

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

必須の場合

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

_export:
  params:
    activation_actions_table: "customer_profiles"

バリデーション

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

result_connection_settings

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

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

自動入力される場合

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

必須の場合

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

例 - Snowflake

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

例 - Google Sheets

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で選択された認証に基づいて自動的に入力されます。

必須の場合

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

_export:
  params:
    result_connection_name: "my_snowflake_connection"

バリデーション

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

完全なパラメータ例

Activation Actionモード

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

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"
      }
    ]

スタンドアロンモード

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

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の設定
• Incremental Activationマッピング
• Incremental Activationのトラブルシューティング

関連トピック

• Incremental Activation概要
• Activation Actionsパラメータ