Braze クラウドデータ取り込みの概要

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

仕組み

Braze のクラウドデータ取り込み (CDI) では、データウェアハウスのインスタンスと Braze ワークスペースとの連携を設定して、定期的にデータを同期します。この同期は設定したスケジュールで実行され、連携ごとに異なるスケジュールを設定できます。同期は最大頻度で 15 分ごと、最小頻度で月に 1 回実行できます。15 分より短い間隔で頻繁に同期を実行する必要がある場合は、カスタマーサクセスマネージャーに相談するか、REST API 呼び出しを使用するリアルタイムのデータ取り込みを検討してください。

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

サポートされるデータソース

クラウドデータ取り込みでは、以下のソースのデータを Braze に同期できます。

• データウェアハウスソース
  • Amazon Redshift
  • Databricks
  • Google BigQuery
  • Snowflake
• ファイルストレージソース
  • Amazon S3

サポートされるデータ型

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

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

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

同期されるデータ

同期が実行されるたびに Braze では、以前に同期されていない行が調べられます。このときに、テーブルまたはビューの UPDATED_AT 列がチェックされます。最後に同期された行よりも UPDATED_AT が後にある行がすべて選択され、Braze に取り込まれます。

データウェアハウスで、次のユーザーと属性をテーブルに追加し、UPDATED_AT の時間をこのデータを追加する時間に設定します。

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

1
2
3
4
5
6
7
8
9
10
11
12
{
  "external_id":"customer_1234",
  "email":"[email protected]",
  "attribute_1":"abcdefg",
  "attribute_2":{
        "attribute_a":"example_value_1",
        "attribute_b":"example_value_2"
    },
  "attribute_3":"2019-07-16T19:20:30+1:00",
  "attribute_4":false,
  "attribute_5":"testing"
}

1
2
3
4
5
6
7
8
9
{
  "external_id":"customer_3456",
  "email":"[email protected]",
  "attribute_1":"abcdefg",
  "attribute_2":42,
  "attribute_3":"2019-07-16T19:20:30+1:00",
  "attribute_4":true,
  "attribute_5":"testing"
}

1
2
3
4
5
6
7
8
9
{
  "external_id":"customer_5678",
  "email":"[email protected]",
  "attribute_1":"abcdefg",
  "attribute_2":42,
  "attribute_3":"2017-08-10T09:20:30+1:00",
  "attribute_4":true,
  "attribute_5":"testing_123"
}

ユースケース:初回の同期とその後の更新

この例では、最初にデータを同期し、その後の更新では変更されたデータ (差分) のみを更新する一般的なプロセスを説明します。いくつかのユーザーデータを含むテーブル 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 行のみが同期されます。

ユースケース:既存のオブジェクト配列内にあるフィールドの更新

この例では、既存のオブジェクト配列内にあるフィールドを更新する方法を説明しします。次のように定義されたソーステーブルがあるとします。

1
2
3
4
5
6
7
8
Create table BRAZE_CLOUD_INGESTION_DEMO.BRAZE_SCHEMA.pet_list (
    pet_id int IDENTITY(1,1), 
    breed VARCHAR, 
    type VARCHAR, 
    name VARCHAR, 
    owner_id VARCHAR, 
    age int
);

この例では、各ユーザー (owner_id に対応) の所有するペットの配列を追加します。具体的には、識別、血統、種類、名前を含めます。次のクエリを使用してテーブルまたはビューにデータを入力できます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
SELECT 
CURRENT_TIMESTAMP as UPDATED_AT,
owner_id as EXTERNAL_ID,
TO_JSON(
    OBJECT_CONSTRUCT(
        '_merge_objects','true',
       'pets',
        OBJECT_CONSTRUCT(
           '$add', ARRAY_AGG( OBJECT_CONSTRUCT(
                'id',
                pet_id,
                'breed',
                breed,
                'type',
                type,
                'name',
                name
                )) WITHIN GROUP (ORDER BY type ASC)    
        )
    )
)
as PAYLOAD from BRAZE_CLOUD_INGESTION_DEMO.BRAZE_SCHEMA.pet_list group by EXTERNAL_ID;

予測される出力は次のようになります。

1
2
3
4
UPDATED_AT	EXTERNAL_ID	PAYLOAD
2023-10-02 19:56:17.377 +0000	03409324	{"_merge_objects":"true","pets":{"$add":[{"breed":"parakeet","id":5,"name":"Mary","type":"bird"}]}}
2023-10-02 19:56:17.377 +0000	21231234	{"_merge_objects":"true","pets":{"$add":[{"breed":"calico","id":2,"name":"Gerald","type":"cat"},{"breed":"beagle","id":1,"name":"Gus","type":"dog"}]}}
2023-10-02 19:56:17.377 +0000	12335345	{"_merge_objects":"true","pets":{"$add":[{"breed":"corgi","id":3,"name":"Doug","type":"dog"},{"breed":"salmon","id":4,"name":"Larry","type":"fish"}]}}

次に、更新された名前フィールドと新しい年齢フィールドを所有者ごとに送信するために、次のクエリを使用してテーブルまたはビューにデータを入力できます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
SELECT 
CURRENT_TIMESTAMP as UPDATED_AT,
owner_id as EXTERNAL_ID,
TO_JSON(
    OBJECT_CONSTRUCT(
        '_merge_objects','true',
       'pets',
        OBJECT_CONSTRUCT(
           '$update', ARRAY_AGG( OBJECT_CONSTRUCT(
                '$identifier_key','id',
                '$identifier_value',pet_id,
                '$new_object',OBJECT_CONSTRUCT(
                    'name',name,
                    'age',age
                )
                )) WITHIN GROUP (ORDER BY type ASC)    
        )
    )
)
as PAYLOAD from BRAZE_CLOUD_INGESTION_DEMO.BRAZE_SCHEMA.pet_list group by EXTERNAL_ID; 

予測される出力は次のようになります。

1
2
3
4
UPDATED_AT	EXTERNAL_ID	PAYLOAD
2023-10-02 19:50:25.266 +0000	03409324	{"_merge_objects":"true","pets":{"$update":[{"$identifier_key":"id","$identifier_value":5,"$new_object":{"age":7,"name":"Mary"}}]}}
2023-10-02 19:50:25.266 +0000	21231234	{"_merge_objects":"true","pets":{"$update":[{"$identifier_key":"id","$identifier_value":2,"$new_object":{"age":3,"name":"Gerald"}},{"$identifier_key":"id","$identifier_value":1,"$new_object":{"age":3,"name":"Gus"}}]}}
2023-10-02 19:50:25.266 +0000	12335345	{"_merge_objects":"true","pets":{"$update":[{"$identifier_key":"id","$identifier_value":3,"$new_object":{"age":6,"name":"Doug"}},{"$identifier_key":"id","$identifier_value":4,"$new_object":{"age":1,"name":"Larry"}}]}}

データポイント使用量

クラウドデータ取り込みのデータポイント請求は、/users/track エンドポイント を介した更新の請求に相当します。詳細については、「データポイント」を参照してください。

データ設定に関する推奨事項

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

同期が実行されるたびに Braze では、以前に同期されていない行が調べられます。このときに、テーブルまたはビューの UPDATED_AT 列がチェックされます。最後に同期された行よりも UPDATED_AT が後にある行は、現在ユーザープロファイルにある行と同じかどうかにかかわらず、選択されて Braze に取り込まれます。そのため、追加または更新を行う属性のみを同期することをお勧めします。

CDI を使用したデータポイントの消費は、REST API や SDK などの他の取り込み方法と同じであるため、ソーステーブルに新規の属性または更新された属性のみを追加するかどうかはお客様次第です。

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

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

UPDATED_AT の時刻が同期と同じでないことを確認します

UPDATED_AT フィールドが前回の同期とまったく同じ時刻にある場合、CDI 同期に重複データがある可能性があります。これは、CDI が”inclusive boundary&quot を選択するためです。これは、前回の同期と同じ時間の行が見つかり、行が同期可能になる場合です。CDI は、これらの行を再取り込みし、重複データを作成します。

EXTERNAL_ID をPAYLOAD カラムから分離します

PAYLOAD オブジェクトには、外部ID またはその他のID タイプを含めることはできません。

属性を削除する

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

増分更新を行う

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

次の例では、ユーザーに2 つの属性があります。

• 色:”グリーン&クォート;
• サイズ:”Large”

次に、Braze は、そのユーザに対して次の2 つの更新を同時に受信します。

• リクエスト1:色を”Red”に変更します。
• リクエスト2:サイズを”Medium”に変更します。

Request 1 が最初に発生するため、ユーザーの属性は次のように更新されます。

• 色:”Red”
• サイズ:”Large”

ただし、Request 2 が発生すると、Braze は元の属性値(“Green” および”Large”) で開始し、ユーザーの属性を次のように更新します。

• 色:”グリーン&クォート;
• サイズ:”Medium”

リクエストが終了すると、リクエスト2はリクエスト1からの更新を上書きします。このため、更新をずらしてリクエストが上書きされないようにすることをお勧めします。

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

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

• snowflake
• redshift
• bigquery
• databricks

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;

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

Braze に正常に同期されたデータの追跡には、UPDATED_AT タイムスタンプを使用します。同期の実行中に同じタイムスタンプを持つ多くの行が書き込まれると、データが重複して Braze に同期される可能性があります。データの重複を回避するための推奨事項をいくつか示します。

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

テーブル構成

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

データのフォーマット

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

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

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

• 階層化カスタム属性
• イベント
• 購入
• サブスクリプショングループ

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 時間以内に完了することをお勧めします。クエリがこの時間枠を超える場合は、データウェアハウスの構成を見直すことを検討してください。倉庫に割り当てられたリソースを最適化することで、クエリ実行速度を向上させることができます。

製品の制限事項