ベストプラクティス

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

コラムUPDATED_ATを理解する

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

例: 定期的な同期

CDI同期における`UPDATED_AT`の使用方法を示すため、ユーザー属性を更新する定期同期の例を考えてみよう：

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

サポートされるデータ型

クラウドデータ取り込みは、次のデータ型をサポートします。

• ユーザー属性、含む：
  • 階層化カスタム属性
  • オブジェクト配列
  • サブスクリプションステータス
• カスタムイベント
• 購入イベント
• カタログ項目
• ユーザー削除リクエスト

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

同期されるデータ

同期が実行されるたびに Braze では、以前に同期されていない行が調べられます。このときに、テーブルまたはビューの UPDATED_AT 列がチェックされます。Brazeは、最後の正常な同期ジョブからの最終UPDATED_ATタイムスタンプと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"
}

行が追加されたが、そのUPDATED_AT値は（最初の実行時に2022-07-19 09:07:23保存された）よりも早い。その結果、これらの行はいずれも今回の実行では同期されない。同期の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"
}

この三度目の実行では、新たな行が追加された。さて、1つの行のUPDATED_AT値がより遅い2022-07-19 09:07:23。つまり、同期されるのは1行だけだ。最後のものは今UPDATED_AT、に設定された2022-07-21 08:30:00。

UPDATED_AT列にUTCタイムスタンプを使用します

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

同期する時間UPDATED_ATと時間が同じでないことを確認せよ

CDI同期では、いずれかのUPDATED_ATフィールドが前回の正常な同期ジョブの最終UPDATED_ATタイムスタンプと完全に一致する場合、重複データが生じる可能性がある。これは、CDI は以前の同期と同じ時刻の行を特定すると「包含境界」を選択し、それらの行を同期可能にするためです。CDI は、これらの行を再取り込みし、重複データを作成します。

重複データを避けるための提案をいくつか挙げる：

• 同期を設定する場合VIEW、デフォルト値としてCURRENT_TIMESTAMPを使用するな。使用すると、同期が実行されるたびにすべてのデータが同期されます。これは、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(...)) を使用します。

増分更新を行う

データのインクリメンタル更新を行うことで、同時更新時の意図しない上書きを防ぐことができます。

この動作を防ぐ最善の方法は、CDI同期のデータソースが各ユーザーの最新の状態のみを反映していること、あるいは特定のユーザーまたはユーザーと属性の組み合わせに対する全ての更新が単一の行に含まれていることを保証することだ。

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

各属性を内部的に独自の列に格納する場合は、それらの列を JSON 文字列に変換して、Braze との同期を取り込む必要があります。そのために、次のようなクエリを使用できます。

• 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 タイムスタンプを使用します。同期の実行中に同じタイムスタンプを持つ多くの行が書き込まれると、データが重複して Braze に同期される可能性があります。データの重複を回避するための推奨事項をいくつか示します。

• VIEW に対して同期を設定する場合は、CURRENT_TIMESTAMP をデフォルト値として使用しないでください。使用すると、同期が実行されるたびにすべてのデータが同期されます。これは、UPDATED_AT フィールドの評価結果がクエリの実行時間になるためです。
• 非常に長時間実行されるパイプラインやクエリがソーステーブルにデータを書き込んでいる場合、同期と同時に実行することを避けるか、挿入される各行に同じタイムスタンプを使用することを避けてください。
• トランザクションを使用して、同じタイムスタンプを持つすべての行を書き込みます。

テーブル構成

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

データのフォーマット

階層化カスタム属性の更新、サブスクリプションステータスの追加、カスタムイベントまたは購入の同期など、Braze の /users/track エンドポイントを通じて可能な操作はすべて、クラウドデータ取り込みでサポートされます。

ペイロード内のフィールドは、対応する/users/trackエンドポイントと同じ形式に従う必要があります。詳細な書式設定の要件については、次を参照してください。

ネストされた属性で日付をキャプチャするための特別な要件に注意してください。

• nested custom attributes
• event
• purchase
• subscription groups

1
2
3
4
5
6
7
8
9
10
11
12
{
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "genre": "Jazz",
        "play_analytics": {
            "count": 1000,
            "top_10_listeners": true
        }
      }
}

1
2
3
4
5
6
7
8
9
{
    "app_id" : "your-app-id",
    "name" : "rented_movie",
    "time" : "2013-07-16T19:20:45+01:00",
    "properties": {
        "movie": "The Sad Egg",
        "director": "Dan Alexander"
    }
} 

1
2
3
4
5
6
7
8
9
10
11
12
{
    "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
    "product_id" : "Completed Order",
    "currency" : "USD",
    "price" : 219.98,
    "time" : "2013-07-16T19:20:30+01:00",
    "properties" : {
        "products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99 },
        { "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99 }
        ]
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "subscription_groups" : [
        {
            "subscription_group_id": "subscription_group_identifier_1",
            "subscription_state": "unsubscribed"
        },
        {
            "subscription_group_id": "subscription_group_identifier_2",
            "subscription_state": "subscribed"
        },
        {
            "subscription_group_id": "subscription_group_identifier_3",
            "subscription_state": "subscribed"
        }
      ]
}

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

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

製品の制限事項