ベストプラクティス

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

UPDATED_AT列について

注

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

同期が実行されると、Brazeはデータウェアハウスインスタンスに直接接続し、指定されたテーブルからすべての新しいデータを取得し、Brazeダッシュボード上の対応するデータを更新します。同期が実行されるたびに、Brazeは更新されたデータを反映します。

重要

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

例：定期的な同期

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

• ファイルストレージソース
  • Amazon S3

サポートされるデータ型

Cloud Data Ingestionは以下のデータ型をサポートしています：

• ユーザー属性（以下を含む）:
  • 階層化カスタム属性
  • オブジェクトの配列
  • 購読ステータス
• カスタムイベント
• 購入イベント
• カタログアイテム
• ユーザー削除リクエスト

データ型の問題を回避する

CDIを使用して外部ソース（DatabricksやSnowflakeなど）からデータを同期する場合、同期前にソースカラムが正しいデータ型を使用していることを確認してください。一般的な問題には以下のようなものがあります：

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

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

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

同期される内容

同期が実行されるたびに、Brazeはまだ同期されていない行を検索します。これはテーブルまたはビューの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時

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の時刻が同期の時刻と同じにならないようにするを参照してください。保存されたUPDATED_ATは2022-07-19 09:07:23のままです。

定期同期、3回目の実行：2022年7月21日午後12時

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）は保存されたタイムスタンプよりも後のため、同期されます。この新しい行と、保存されたタイムスタンプと同じUPDATED_ATを持つcustomer_5678の既存の行の両方が同期されます。保存されたUPDATED_ATは2022-07-21 08:30:00に更新されます。

注

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

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日目のテーブルには次の値があります：

このデータをCDIが期待する形式に変換するには、次のクエリを実行します：

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タイプを含めないでください。

属性を削除する

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

増分更新を行う

同時更新による意図しない上書きを防ぐため、データに増分更新を行ってください。

重要

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

この動作を防ぐ最善の方法は、CDI同期のソースデータが各ユーザーの最新の状態のみを反映するようにするか、特定のユーザーまたはユーザー＋属性ペアのすべての更新を単一の行に含めることです。

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

各属性を個別の列に内部的に保存する場合は、Brazeとの同期を設定するために、それらの列をJSON文字列に変換する必要があります。これを行うには、次のようなクエリを使用できます。

• snowflake
• redshift
• bigquery
• databricks
• microsoft fabric

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";

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,
    JSON_SERIALIZE(
        OBJECT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    ) as PAYLOAD FROM "EXAMPLE_USER_DATA";

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (attribute_1 string,
     attribute_2 STRING,
     attribute_3 NUMERIC,
     my_user_id STRING);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
      STRUCT(
        'attribute_1' AS attribute_1,
        'attribute_2'AS attribute_2,
        'yet_another_attribute'AS attribute_3
      )
    ) as PAYLOAD
  FROM BRAZE.EXAMPLE_USER_DATA;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (
    attribute_1 string,
    attribute_2 STRING,
    attribute_3 NUMERIC,
    my_user_id STRING
);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
      STRUCT(
        attribute_1,
        attribute_2,
        attribute_3
      )
    ) as PAYLOAD
  FROM BRAZE.EXAMPLE_USER_DATA;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
CREATE TABLE [braze].[users] (
    attribute_1 VARCHAR,
    attribute_2 VARCHAR,
    attribute_3 VARCHAR,
    attribute_4 VARCHAR,
    user_id VARCHAR
)
GO

CREATE VIEW [braze].[user_update_example]
AS SELECT
    user_id as EXTERNAL_ID,
    CURRENT_TIMESTAMP as UPDATED_AT,
    JSON_OBJECT('attribute_1':attribute_1, 'attribute_2':attribute_2, 'attribute_3':attribute_3, 'attribute_4':attribute_4) as PAYLOAD

FROM [braze].[users] ;

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

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

テーブルの設定

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

データのフォーマット

クラウドデータ取り込みのテーブル設定要件とペイロードのフォーマット要件は、クラウドデータ取り込みのテーブル設定に記載されています。

このページでは以下を区別できます。

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

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

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

製品の制限事項