ファイルストレージの連携

このページでは、クラウドデータ取り込みのサポートを設定し、S3 から Braze に関連データを同期する方法について説明します。

仕組み

S3 用のクラウドデータ取り込み (CDI) を使用して、AWS アカウントの1つ以上の S3 バケットを Braze と直接統合できます。新規ファイルが S3 にパブリッシュされると、メッセージが SQS に投稿され、Braze のクラウドデータ取り込みがそれらの新規ファイルを取り込みます。

クラウドデータ取り込みは、以下をサポートしています。

• JSON ファイル
• CSVファイル
• Parquet ファイル
• 属性、カスタムイベント、購入イベント、ユーザー削除、カタログデータ

前提条件

連携には次のリソースが必要です。

• データストレージ用の S3 バケット
• 新規ファイル通知用の SQS キュー
• Braze アクセス用の IAM ロール

AWS の定義

まず、この作業で使用される用語を定義します。

AWS でのクラウドデータ取り込みの設定

ステップ 1: ソースバケットの作成

AWS アカウントでデフォルト設定の汎用 S3 バケットを作成します。S3 バケットは、フォルダーが一意である限り、同期間で再利用できます。

デフォルト設定は次のとおりです。

• ACL 無効
• すべてのパブリックアクセスをブロック
• バケットのバージョン管理を無効化
• SSE-S3 暗号化
  • SSE-S3 はサポートされている唯一のサーバーサイド暗号化方式です。Amazon KMS の暗号化はサポートされていません。

バケットを作成したリージョンをメモしておいてください。次のステップでは同じリージョンに SQS キューを作成します。

ステップ 2: SQS キューの作成

作成したバケットにオブジェクトが追加されたときに追跡する SQS キューを作成します。ここでは、デフォルトの設定を使用します。

SQS キューはグローバルに一意でなければなりません（例えば、CDI 同期には1つしか使用できず、別のワークスペースで再利用することはできません）。

重要

この SQS は、バケットを作成したリージョンと同じリージョンに必ず作成してください。

この設定では ARN と SQS の URL を頻繁に使用するため、それらを必ずメモしてください。

ステップ 3: アクセスポリシーの設定

アクセスポリシーを設定するには、詳細オプションを選択します。

次のステートメントをキューのアクセスポリシーに追加します。YOUR-BUCKET-NAME-HERE をバケット名に、YOUR-SQS-ARN を SQS キューの ARN に、YOUR-AWS-ACCOUNT-ID を AWS アカウント ID にそれぞれ置き換えてください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "Sid": "braze-cdi-s3-sqs-publish",
  "Effect": "Allow",
  "Principal": {
    "Service": "s3.amazonaws.com"
  },
  "Action": "SQS:SendMessage",
  "Resource": "YOUR-SQS-ARN",
  "Condition": {
    "StringEquals": {
      "aws:SourceAccount": "YOUR-AWS-ACCOUNT-ID"
    },
    "ArnLike": {
      "aws:SourceArn": "arn:aws:s3:::YOUR-BUCKET-NAME-HERE"
    }
  }
}

ステップ 4: S3 バケットへのイベント通知の追加

1. ステップ 1 で作成したバケットで、Properties > Event notifications に移動します。
2. 設定に名前を付けます。オプションで、ファイルのサブセットのみを Braze で取り込む場合は、対象とするプレフィックスまたはサフィックスを指定します。
3. Destination で SQS queue を選択し、ステップ 2 で作成した SQS の ARN を指定します。

注

S3 バケットのルートフォルダーにファイルをアップロードした後、一部のファイルをバケット内の特定のフォルダーに移動すると、予期しないエラーが発生することがあります。代わりに、イベント通知をプレフィックス内のファイルについてのみ送信するように変更するか、プレフィックス外のファイルを S3 バケットに入れないようにするか、またはプレフィックスなしで連携を更新すること（すべてのファイルが取り込まれる）ができます。

ステップ 5: IAM ポリシーの作成

ソースバケットの操作を Braze に許可する IAM ポリシーを作成します。まず、アカウント管理者として AWS 管理コンソールにサインインします。

1. AWS コンソールの [IAM] セクションに移動し、ナビゲーションバーの Policies を選択してから Create Policy を選択します。
   
   
   
   

2. JSON タブを開き、Policy Document セクションに以下のコードスニペットを入力します。YOUR-BUCKET-NAME-HERE をバケット名に、YOUR-SQS-ARN-HERE を SQS キュー名にそれぞれ置き換えてください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE"]
        },
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE/*"]
        },
        {
            "Effect": "Allow",
            "Action": [
                "sqs:DeleteMessage",
                "sqs:GetQueueUrl",
                "sqs:ReceiveMessage",
                "sqs:GetQueueAttributes"
            ],
            "Resource": "YOUR-SQS-ARN-HERE"
        }
    ]
}

3. 入力が終わったら、Review Policy を選択します。

4. ポリシーの名前と説明を指定し、Create Policy を選択します。

ステップ 6: IAM ロールの作成

AWS での設定を完了するには、IAM ロールを作成し、ステップ 5 の IAM ポリシーをそれにアタッチします。

1. IAM ポリシーを作成したコンソールの同じ [IAM] セクションで、Roles > Create Role に移動します。

2. AWS で、信頼できるエンティティセレクターのタイプとして Another AWS Account を選択します。Braze アカウント ID を入力します。Require external ID チェックボックスを選択します。
3. Braze で、データ設定 > クラウドデータ取り込み > ソース に移動し、データソースを追加 を選択して、ファイルソースセクションから Amazon S3 を選択します。
4. 自動生成された Braze アカウント ID をコピーします。

6. AWS で、アカウント ID を貼り付けてから Next を選択します。

7. ステップ 4 で作成したポリシーをロールにアタッチします。検索バーでポリシーを検索し、ポリシーの横のチェックマークを選択してアタッチします。完了したら Next を選択します。

ロールに名前と説明を指定し、Create Role を選択します。

8. 作成したロールの ARN と生成した External ID をメモしておいてください。クラウドデータ取り込みの連携を作成する際に必要になります。

Braze でのクラウドデータ取り込みの設定

1. まず、Braze ダッシュボードで新しいソースを作成します。データ設定 > クラウドデータ取り込み > ソース に移動し、データソースを追加 を選択して、Amazon S3 を選択します。
2. ソースの名前を選択し、AWS の設定プロセスからの情報を入力して新しいソースを作成します。次の項目を指定します。

• ロールの ARN
• External ID
• バケット名
• リージョン

3. Test connection を選択して、Braze がバケットにアクセスできることを確認します。テストが成功したら、Connect to Source を選択します。接続に失敗した場合は、問題のトラブルシューティングに役立つエラーメッセージが表示されます。

4. 次に、新しい同期を作成します。データ設定 > クラウドデータ取り込み > 同期 に移動し、データ同期を作成 を選択します。

5. 同期の名前を選択します。次に、アクティブな S3 ソースを選択し、同期のソーステーブルを入力します。データタイプを選択し、Test Connection を選択します。

1. AWS の設定プロセスからの残りの情報を入力します。次の項目を指定します。
   • SQS URL（新しい連携ごとに一意である必要があります）
   • フォルダーパス（オプション、ワークスペース内の同期間で一意である必要があります）
2. データタイプを選択し、Test Connection を選択して、Braze が取り込み可能なファイル（ファイル内のデータではなく）を一覧表示できることを確認します。成功したら、Next: Notifications を選択します。
3. アクセスや権限の問題で同期が中断した場合に通知を受け取る連絡先メールアドレスを追加します。オプションで、ユーザーレベルのエラーと同期の成功の通知をオンにします。
4. 同期を作成します。

必要なファイル形式

クラウドデータ取り込みは、JSON、CSV、および Parquet のファイルをサポートしています。必要な列はデータタイプによって異なります。

• ユーザーデータ（属性、カスタムイベント、購入イベント）はユーザー識別子とペイロードを使用します
• カタログデータはカタログ識別子を使用します

S3 をカタログデータに使用している場合は、このページとカタログデータの同期と削除を併せて参照し、カタログ固有の要件と動作を確認してください。

Braze は、AWS によって強制される以上の追加のファイル名要件を強制しません。ファイル名は一意でなければなりません。一意性を確保するためにタイムスタンプを付加することを推奨します。

サポートされているすべてのファイルタイプ（属性、カスタムイベント、購入、カタログ、ユーザー削除）の例については、braze-examples のサンプルファイルを参照してください。

ユーザー識別子

ユーザーデータの同期（属性、カスタムイベント、購入イベント）では、ソースファイルの各行に正確に1つのユーザー識別子と PAYLOAD 列が必要です。ソースファイルには異なる識別子タイプの行を含めることができますが、各行では1つの識別子のみを使用する必要があります。

識別子に加えて、各行には Braze のユーザーに同期させたいフィールドの JSON 文字列を含む PAYLOAD 列が必要です。

注

データウェアハウスソースとは異なり、UPDATED_AT 列はファイルストレージ同期では必須ではなく、サポートもされていません。

カタログ識別子

カタログ同期では、ソースファイルに以下の列を含める必要があります。カタログファイルはユーザーデータファイルとは異なる識別子を使用します。

例

• json attributes
• json custom events
• json purchase events
• csv attributes
• csv catalogs

1
2
3
4
5
6
7
{"external_id":"s3-qa-0","payload":"{\"name\": \"GT896\", \"age\": 74, \"subscriber\": true, \"retention\": {\"previous_purchases\": 21, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600803\"}"}
{"external_id":"s3-qa-1","payload":"{\"name\": \"HSCJC\", \"age\": 86, \"subscriber\": false, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600824\"}"}
{"external_id":"s3-qa-2","payload":"{\"name\": \"YTMQZ\", \"age\": 43, \"subscriber\": false, \"retention\": {\"previous_purchases\": 23, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600831\"}"}
{"external_id":"s3-qa-3","payload":"{\"name\": \"5P44M\", \"age\": 15, \"subscriber\": true, \"retention\": {\"previous_purchases\": 7, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600838\"}"}
{"external_id":"s3-qa-4","payload":"{\"name\": \"WMYS7\", \"age\": 11, \"subscriber\": true, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600844\"}"}
{"external_id":"s3-qa-5","payload":"{\"name\": \"KCBLK\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 11, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600850\"}"}
{"external_id":"s3-qa-6","payload":"{\"name\": \"T93MJ\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 10, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600856\"}"}

重要

ソースファイルのすべての行に有効な JSON が含まれている必要があります。含まれていない場合、ファイルはスキップされます。

1
2
{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}

重要

ソースファイルのすべての行に有効な JSON が含まれている必要があります。含まれていない場合、ファイルはスキップされます。

1
2
{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}

重要

ソースファイルのすべての行に有効な JSON が含まれている必要があります。含まれていない場合、ファイルはスキップされます。

1
2
3
4
external_id,payload
s3-qa-load-0-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""SNXIM"", ""age"": 54, ""subscriber"": true, ""retention"": {""previous_purchases"": 19, ""vip"": true}, ""last_visit"": ""2023-08-08T16:03:26.598806""}"
s3-qa-load-1-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""0J747"", ""age"": 73, ""subscriber"": false, ""retention"": {""previous_purchases"": 22, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598816""}"
s3-qa-load-2-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""EP1U0"", ""age"": 99, ""subscriber"": false, ""retention"": {""previous_purchases"": 23, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598822""}"

1
2
3
ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

オプションの DELETED 列を含めます。DELETED が true の場合、そのカタログアイテムは Braze のカタログから削除されます。必要な列の完全なリストについては、カタログ識別子を参照してください。削除の動作については、カタログアイテムの削除を参照してください。エンドツーエンドのカタログ設定フロー（ターゲットカタログの作成と同期の動作を含む）については、カタログデータの同期と削除を参照してください。

データの削除

S3 向けクラウドデータ取り込みは、ファイルアップロードを通じてユーザーとカタログアイテムの削除をサポートしています。それぞれに別々の同期とファイル形式を使用します。

• ユーザーの削除 – データタイプ Delete Users で同期を作成し、ユーザー識別子のみを含むファイル（ペイロードなし）をアップロードします。
• カタログアイテムの削除 – 既存のカタログ同期を使用し、削除対象のアイテムをマークする deleted（または DELETED）列を追加します。

ユーザーの削除

S3 のファイルを使って Braze でユーザープロファイルを削除するには：

1. 新しいクラウドデータ取り込み同期を作成します（他の同期と同じ AWS と Braze の設定を使用します）。
2. Braze で同期を設定する際、Data Type を Delete Users に設定します。
3. S3 バケットに、ユーザー識別子列のみを含むファイルをアップロードします。PAYLOAD 列を含めないでください。ペイロードが存在すると、誤削除を防ぐために同期が失敗します。

ファイルの各行は、次のいずれかを使用して正確に1人のユーザーを識別する必要があります。

重要

ユーザーの削除は永続的で元に戻すことはできません。削除する予定のユーザーのみを含めてください。詳細については、クラウドデータ取り込みを使用したユーザーの削除を参照してください。

例 – JSON（ユーザー削除）：

{"external_id":"user-to-delete-001"}
{"external_id":"user-to-delete-002"}
{"braze_id":"braze-id-from-profile"}

例 – CSV（ユーザー削除）：

1
2
3
external_id
user-to-delete-001
user-to-delete-002

同期が実行されると、Braze はバケット内の新規ファイルを処理し、対応するユーザープロファイルを削除します。

カタログアイテムの削除

ファイルストレージを使用してカタログからアイテムを削除するには：

1. カタログデータの同期（データタイプ：Catalogs）に使用するのと同じ S3 同期を使用します。
2. CSV ファイルや JSON ファイルに、オプションの deleted（または DELETED）列を追加します。
3. Braze のカタログから削除したいカタログアイテムには、deleted を true に設定します。

各行にはまだ ID と PAYLOAD が必要です。削除対象の行については、ペイロードは最小限で構いません。Braze は ID でアイテムを削除します。

例 – JSON（カタログアイテム削除）：

{"id":"85","payload":"{\"product_name\": \"Product 85\", \"price\": 85.85}"}
{"id":"1","payload":"{\"product_name\": \"Product 1\", \"price\": 1.01}","deleted":true}

例 – CSV（カタログアイテム削除）：

1
2
3
ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

同期が実行されると、deleted: true の行に対応するカタログアイテムが Braze から削除されます。カタログデータの完全な同期と削除の動作については、カタログデータの同期と削除を参照してください。

知っておくべきこと

• S3 ソースバケットに追加するファイルは 512 MB を超えてはなりません。512 MB を超えるファイルはエラーになり、Braze に同期されません。
• 1ファイルあたりの行数に追加の制限はありませんが、同期の速度を向上させるために、小さなファイルを使用することをお勧めします。例えば、500 MB のファイルの取り込みは、100 MB のファイルを5つに分けて取り込む場合よりもかなり時間がかかります。
• 一定期間内にアップロードできるファイルの数に追加の制限はありません。
• ファイル内やファイル間の順序付けはサポートされていません。競合が予想される状況を監視している場合は、定期的に更新をバッチ処理することをお勧めします。

トラブルシューティング

ファイルのアップロードと処理

CDI は、同期が作成された後に追加されたファイルのみを処理します。このプロセスでは、Braze が新しいファイルの追加を検知し、SQS への新しいメッセージがトリガーされます。これにより、新しいファイルを処理するための新しい同期が開始されます。

既存のファイルを使って、Braze がバケットにアクセスでき、取り込むファイルを検出できることを確認できますが、それらのファイルは Braze に同期されません。CDI がそれらを処理するには、同期したい既存のファイルを S3 に再アップロードする必要があります。

予期しないファイルエラーの処理

エラーや失敗ファイルが多い場合は、CDI のターゲットフォルダー以外のフォルダーにある S3 バケットに、別のプロセスがファイルを追加している可能性があります。

ファイルがソースバケットにアップロードされたがソースフォルダーには含まれていない場合、CDI は SQS 通知を処理しますが、ファイルに対してアクションを実行しないため、エラーとして表示されることがあります。

問題が S3 通知や SQS 送信先の権限に関連している場合（例えば、送信先の検証エラー）は、AWS のドキュメントを参照してください。

• Amazon S3 コンソールを使用したイベント通知の有効化と設定
• 送信先へのイベント通知メッセージの発行権限の付与
• Amazon SQS の問題のトラブルシューティング