ベストプラクティス

Brazeクラウドデータ取り込みを使用すると、データウェアハウスやファイルストレージシステムからBrazeへの直接接続を設定して、関連するユーザーデータやカタログデータを同期できます。このデータをBrazeに同期すると、パーソナライゼーション、トリガー、セグメンテーションなどのユースケースに活用できます。

UPDATED_ATによる変更の追跡

注

UPDATED_ATはデータウェアハウス連携にのみ関連するものであり、ファイルストレージ同期には適用されません。

同期が実行されると、Brazeはデータウェアハウスインスタンスに直接接続し、各行のUPDATED_ATタイムスタンプを使用して変更を追跡します。UPDATED_ATは、すべてのデータウェアハウス同期で必須のフィールドです。

重要

CDIは、行の内容がBrazeの現在のデータと同じかどうかに関係なく、UPDATED_ATの値に基づいて厳密に変更を追跡します。不要なデータポイント使用量を避けるために、UPDATED_ATを使用して新規または更新されたデータのみを同期することをBrazeでは推奨しています。

例：定期同期の動作

CDI同期でUPDATED_ATがどのように使用されるかを説明するために、ユーザー属性を更新する定期同期の例を見てみましょう。

同期が実行されるたびに、CDIはまだ同期されていない行を検索します。CDIはテーブルまたはビューのUPDATED_AT列を使用してこれを確認します。Brazeは、UPDATED_ATが最後に同期されたUPDATED_ATの値よりも新しいすべての行を選択してインポートします。境界のタイムスタンプと完全に一致する行も、同じタイムスタンプの新しい行が実行間で追加された場合に再同期される可能性があります。

重要

CDIは、最後に同期されたUPDATED_ATの値における行数を追跡します。同じタイムスタンプの新しい行が実行間で追加された場合、CDIは包括的な境界（>=）に切り替え、そのタイムスタンプのすべての行（すでに処理済みのものを含む）を再同期します。重複同期や不要なデータポイント消費を避けるために、同期実行間で一意のUPDATED_AT値を使用してください。詳細については、重複タイムスタンプによる行の再同期を回避するを参照してください。

データウェアハウスで、以下のユーザーと属性をテーブルに追加し、UPDATED_ATの時刻をデータを追加した時刻に設定します。

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_1",
        "attribute_b":"example_value_1"
    },
    "attribute_3":"2019-07-16T19:20:30+1:00"
}

1
2
3
4
5
6

{
    "attribute_1":"abcdefg",
    "attribute_2":42,
    "attribute_3":"2019-07-16T19:20:30+1:00",
    "attribute_5":"testing"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":true,
    "attribute_5":"testing_123"
}

次のスケジュールされた同期では、Brazeは最後に同期されたタイムスタンプよりも新しいUPDATED_ATタイムスタンプを持つすべての行を同期します。Brazeはフィールドを更新または追加するため、毎回完全なユーザープロファイルを同期する必要はありません。同期後、ユーザープロファイルには新しい更新が反映されます。

定期同期、2回目の実行：2022年7月20日 12:00 PM

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_2",
        "attribute_b":"example_value_2"
    },
    "attribute_3":"2019-07-16T19:20:30+1:00"
}

1
2
3
4
5
6

{
    "attribute_1":"abcdefg",
    "attribute_2":42,
    "attribute_3":"2019-07-16T19:20:30+1:00",
    "attribute_5":"testing"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":true,
    "attribute_5":"testing_123"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":false,
    "attribute_5":"testing_123"
}

customer_9012の新しい行が追加されましたが、そのUPDATED_ATの値（2022-07-16 00:25:30）は保存されたタイムスタンプ（2022-07-19 09:07:23）よりも前のため、同期されません。ただし、customer_5678の既存の行はUPDATED_ATの値が保存されたタイムスタンプと等しいため、包括的な境界により再同期されます。この動作の詳細については、重複タイムスタンプによる行の再同期を回避するを参照してください。保存されたUPDATED_ATは2022-07-19 09:07:23のままです。

定期同期、3回目の実行：2022年7月21日 12:00 PM

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_1",
        "attribute_b":"example_value_1"
    },
    "attribute_3":"2019-07-16T19:20:30+1:00"
}

1
2
3
4
5
6

{
    "attribute_1":"abcdefg",
    "attribute_2":42,
    "attribute_3":"2019-07-16T19:20:30+1:00",
    "attribute_5":"testing"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":true,
    "attribute_5":"testing_123"
}

1
2
3
4
5

{
    "attribute_1":"xyz",
    "attribute_4":false,
    "attribute_5":"testing_123"
}

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_2",
        "attribute_b":"example_value_2"
    },
    "attribute_3":"2019-07-20T19:20:30+1:00"
}

この3回目の実行では、customer_1234の新しい行が追加され、そのUPDATED_ATの値（2022-07-21 08:30:00）は保存されたタイムスタンプよりも新しいものです。この新しい行と、customer_5678の既存の行（UPDATED_ATが保存されたタイムスタンプと等しい）の両方が同期されます。保存されたUPDATED_ATは2022-07-21 08:30:00に更新されます。

注

UPDATED_ATの値は、特定の同期の実行開始時刻よりも未来の値を設定することも可能です。ただし、これは推奨されません。最後のUPDATED_ATタイムスタンプが「未来」に押し出され、それ以降の同期ではそれよりも前の値が同期されなくなるためです。

データ型の問題を防ぐ

CDIを使用して外部ソース（DatabricksやSnowflakeなど）からデータを同期する場合は、同期する前にソース列で正しいデータ型が使用されていることを確認してください。よくある問題は次のとおりです。

• 文字列として保存されたタイムスタンプ: ソースデータベースの日付列では、varcharや文字列ではなく、timestampまたはdatetime型を使用してください。
• 文字列として保存された数値: 同期する前に、ソースクエリで数値列をintegerまたはfloat型にキャストしてください。
• 同期間での型の不一致: 同期の間に列の型が変わると、Brazeが新しいデータを拒否する場合があります。ソーススキーマが一貫していることを確認してください。

Brazeダッシュボードでカスタム属性のデータ型を強制または変更する方法については、カスタムデータを管理するを参照してください。

ユーザーデータは、external ID、ユーザーエイリアス、Braze ID、メール、または電話番号で更新できます。ユーザーは、external ID、ユーザーエイリアス、またはBraze IDで削除できます。

UPDATED_AT 列にはUTCタイムスタンプを使用する

UPDATED_AT 列は、夏時間による問題を防ぐためにUTCである必要があります。可能な限り、CURRENT_DATE() ではなく SYSDATE() など、UTCのみを使用する関数を優先してください。

重複タイムスタンプによる行の再同期を避ける

CDIは、最後に同期されたUPDATED_ATタイムスタンプにおける行数を追跡します。CDIが前回の実行以降に同じタイムスタンプで新しい行が追加されたことを検出すると、包含境界（>=）を使用してそのタイムスタンプのすべての行（すでに処理済みのものを含む）を再選択します。それ以外の場合、CDIは排他境界（>）を使用し、最後に同期された値よりも厳密に後の行のみを選択します。

例えば、同期がUPDATED_AT = 2025-04-01 00:00:00の5行を処理し、後から同じタイムスタンプで6行目が追加された場合、次の同期はカウントの変化を検出し、6行すべてを再同期します。これにより、重複データや不要なデータポイント消費が発生する可能性があります。

これを避けるには：

• VIEWに対して同期を設定する場合、デフォルト値としてCURRENT_TIMESTAMPを使用しないでください。UPDATED_ATフィールドがクエリの実行時刻に評価されるため、同期が実行されるたびにすべてのデータが同期されてしまいます。
• 長時間実行されるパイプラインやクエリがソーステーブルにデータを書き込んでいる場合、同期と同時に実行することを避けるか、挿入される各行に同じタイムスタンプを使用することを避けてください。
• トランザクションを使用して、同じタイムスタンプを共有するすべての行を書き込みます。
• ユニークで単調増加するUPDATED_ATの値を使用して、処理済みの行が再選択されることを防ぎます。

例：後続の更新を管理する

この例では、最初にデータを同期し、その後の更新では変更されたデータ（差分）のみを更新する一般的なプロセスを示します。ユーザーデータを含むテーブルEXAMPLE_DATAがあるとします。1日目のテーブルには次の値があります：

このデータをPAYLOAD列に変換するには、次のクエリを実行します：

1
2
3
4
5
6
7
8
9
10
11
12

SELECT
    CURRENT_TIMESTAMP AS UPDATED_AT,
    EXTERNAL_ID AS EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT(
            'attribute_1', attribute_1,
            'attribute_2', attribute_2,
            'attribute_3', attribute_3,
            'attribute_4', attribute_4
        )
    ) AS PAYLOAD
FROM EXAMPLE_DATA;

このデータはまだBrazeに同期されていないため、CDIのソーステーブルにすべて追加します：

同期が実行され、Brazeは「2023-03-16 15:00:00」までの利用可能なすべてのデータを同期したことを記録します。次に、2日目の朝にETLが実行され、ユーザーテーブルの一部のフィールドが更新されます（*で示されています）：

ここで、変更された値のみをCDIソーステーブルに追加する必要があります。古い行を更新するのではなく、これらの行を追加（アペンド）できます。そのテーブルは次のようになります：

CDIは新しい行のみを同期するため、次に実行される同期では最後の5行のみが同期されます。

その他のヒント

消費を最小限に抑えるため、新規または更新された属性のみを書き込む

同期が実行されるたびに、Brazeは以前に同期されていない行を検索します。この確認には、テーブルまたはビューのUPDATED_AT列を使用します。Brazeは、UPDATED_ATが最後に同期されたUPDATED_AT値より後の行をすべて選択してインポートします。これは、その行が現在のユーザープロファイルの内容と同じかどうかに関係ありません。また、境界のタイムスタンプと同じタイムスタンプを持つ新しい行がある場合、そのタイムスタンプの行が再同期されることもあります。そのため、追加または更新したい属性のみを同期することをお勧めします。

CDIを使用した場合のデータポイント使用量は、REST APIやSDKなどの他の取り込み方法と同じです。そのため、ソーステーブルには新規または更新された属性のみを追加するようにしてください。

EXTERNAL_IDをPAYLOAD列から分離する

PAYLOADオブジェクトには、external IDやその他のIDタイプを含めないでください。

属性を削除する

PAYLOAD列では、ユーザーのプロファイルから属性を除外したい場合に、その属性をnullに設定できます。属性を変更せずに残したい場合は、更新されるまでその属性をBrazeに送信しないでください。属性を完全に削除するには、TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...))を使用します。

増分更新を行う

データの増分更新を行うことで、複数の更新が同時に行われた際の意図しない上書きを防ぐことができます。

重要

• 異なる属性への更新：ほとんどの場合、2つの更新がユーザーの同じ属性に影響しなければ、それぞれの結果は完全に独立しています。たとえば、ユーザーのColor属性を更新し、別途Size属性を更新した場合、数秒以内に行われたとしても、両方の更新が正しく適用されます。
• 同じ属性への更新：1回の同期実行内で複数の更新が同じ属性を対象とする場合、競合が発生することがあります。このようなまれなケースでは、ある更新が別の更新を上書きする可能性があります。この動作を防ぐ最善の方法は、CDI同期のソースデータが各ユーザーの最新の状態のみを反映するようにするか、特定のユーザーまたはユーザーと属性の組み合わせに対するすべての更新が1つの行に含まれるようにすることです。
• オブジェクト配列演算子：独立した更新の唯一の例外は、オブジェクト配列に対する$add、$remove、$update演算子です。これらの場合、同じ配列への更新が互いに影響し合う可能性があります。
• イベント：各イベントは一意であり、関連付けられたタイムスタンプを持つため、競合はイベントには影響しません。

この動作を防ぐ最善の方法は、CDI同期のソースデータが各ユーザーの最新の状態のみを反映するようにするか、特定のユーザーまたはユーザーと属性の組み合わせに対するすべての更新が1つの行に含まれるようにすることです。

別のテーブルからJSON文字列を作成する

PAYLOAD列を使用し、内部で各属性を個別の列に保存している場合は、それらの列をJSON文字列に変換してPAYLOADに入力します。JSON文字列を作成せずに個別の列を同期するには、代わりにVisualまたはSQLオプションを使用します。詳細については、データ定義オプションを選択するを参照してください。

各ソースのページには、そのデータウェアハウスのSQL方言による実例が掲載されています。

• Snowflake
• Amazon Redshift
• Google BigQuery
• Databricks
• Microsoft Fabric

たとえば、Snowflakeの場合は次のようになります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

CREATE TABLE "EXAMPLE_USER_DATA"
    (attribute_1 string,
     attribute_2 string,
     attribute_3 number,
     my_user_id string);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    )as PAYLOAD FROM "EXAMPLE_USER_DATA";

UPDATED_ATタイムスタンプを使用する

BrazeはUPDATED_ATタイムスタンプを使用して、正常に同期されたデータをトラッキングします。CDIは、最後に同期されたタイムスタンプにおける行数もトラッキングします。実行の合間に同じタイムスタンプを持つ新しい行が追加された場合、CDIはそのタイムスタンプのすべての行を再同期するため、データが重複する可能性があります。詳細とヒントについては、タイムスタンプが重複する行の再同期を回避するを参照してください。

テーブル設定

顧客がベストプラクティスやコードスニペットを共有するための公開GitHubリポジトリがあります。ご自身のスニペットを投稿するには、プルリクエストを作成してください。

データのフォーマット

Cloud Data Ingestionのテーブル設定要件とペイロードのフォーマット要件は、Cloud Data Ingestionのテーブル設定に記載されています。

このページを参照して、次の点を区別してください。

• ソーステーブルの要件（必須列、識別子列、UPDATED_ATの動作）
• ペイロードの要件（各データタイプで/users/trackオブジェクト形式と一致させる必要があるフィールド）

データウェアハウスクエリのタイムアウトを回避する

最適なパフォーマンスを得て潜在的なエラーを回避するため、クエリは1時間以内に完了させることをお勧めします。クエリがこの時間を超える場合は、データウェアハウスの設定を見直すことを検討してください。ウェアハウスに割り当てられたリソースを最適化すると、クエリの実行速度を向上させることができます。

製品の制限