このページはAIにより自動翻訳されており、不正確な内容が含まれている可能性があります。翻訳の誤りを報告するには、ページ右側の目次の下にあるフィードバックをご利用ください。

Amazon S3のクラウドデータ取り込み

このページでは、クラウドデータ取り込み (CDI) を使用してAmazon S3からBrazeにデータを同期するために必要なすべての情報を説明します。作成するAWSリソース、Brazeでソースを接続して同期を作成する方法、データタイプごとのファイル形式、S3固有のトラブルシューティングについて取り上げます。

仕組み

Amazon S3の連携は、スケジュールではなくイベントによって駆動されます。新しいファイルがS3に公開されると、Amazon Simple Queue Service (SQS) のキューにメッセージが送信され、Brazeがそのメッセージを受け取って新しいファイルを取り込みます。

この連携には、以下のリソースが必要です。

データ保存用の S3 バケット
新しいファイルの通知用の SQS キュー
Brazeのアクセス用の IAM ロール

AWS の定義

用語	定義
Amazon リソースネーム (ARN)	ARNはAWSリソースの一意の識別子です。
Identity and Access Management (IAM)	IAMは、AWSリソースへのアクセスを安全に管理できる Web サービスです。このチュートリアルでは、IAM ポリシーを作成して IAM ロールに割り当て、S3 バケットをBrazeのクラウドデータ取り込みと連携させます。
Amazon Simple Queue Service (SQS)	SQSは、分散ソフトウェアシステムとコンポーネントを連携できるホスト型のキューです。

AWSでクラウドデータ取り込みを設定する

ステップ1: ソースバケットを作成する

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

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

ACL 無効
すべてのパブリックアクセスをブロック
バケットのバージョニングを無効化
SSE-S3 暗号化
- サポートされているサーバー側の暗号化タイプはSSE-S3のみです。Amazon KMS 暗号化はサポートされていません。

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

ステップ2: SQS キューを作成する

作成したバケットにオブジェクトが追加されたタイミングを追跡するため、SQS キューを作成します。ここではデフォルトの構成設定を使用してください。

SQS キューはグローバルに一意である必要があります (たとえば、1つの CDI 同期にのみ使用でき、別のワークスペースで再利用することはできません)。

重要

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

SQS キューのARNとURLをメモしておいてください。この設定中に何度も必要になります。

キューにアクセスできるユーザーを定義する JSON オブジェクトの例とともに「Advanced」を選択している画面。

ステップ3: アクセスポリシーを設定する

アクセスポリシーを設定するには、Advanced options を選択します。

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

{
  "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で作成したバケットで、Properties > Event notifications に移動します。
構成に名前を付けます。Brazeに一部のファイルのみを取り込ませたい場合は、必要に応じて対象とするプレフィックスまたはサフィックスを指定します。
Destination で SQS queue を選択し、ステップ2で作成したSQSのARNを入力します。

注

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

ステップ5: IAM ポリシーを作成する

Brazeがソースバケットとやり取りできるように、IAM ポリシーを作成します。まず、アカウント管理者として AWS マネジメントコンソールにサインインします。

AWS コンソールの IAM セクションに移動し、ナビゲーションバーで Policies を選択してから、Create Policy を選択します。
JSON タブを開き、Policy Document セクションに次のコードスニペットを入力します。その際、YOUR-BUCKET-NAME-HERE をバケット名に、YOUR-SQS-ARN-HERE を SQS キュー名に置き換えてください。

{
    "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"
        }
    ]
}

完了したら Review Policy を選択します。
ポリシーに名前と説明を付けて、Create Policy を選択します。

「new-policy-name」という名前のポリシーの例。

ポリシーの説明フィールド。

ステップ6: 認証を設定する

Brazeは、次の認証方法でバケットとキューにアクセスします。

方法	Brazeによる認証方法	Brazeで入力する内容
IAM role	Braze assumes an AWS Identity and Access Management (IAM) role in your account, using an external ID.	Role ARN and External ID

IAM role

Braze は、お客様の AWS アカウント内の IAM ロールを引き受けます。ロールを作成し、作成した IAM ポリシーをそのロールにアタッチします。

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

「Create role」ボタン。

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

ソース名と S3 接続の詳細セクションが表示された「新しいソースを追加」ページ。

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

S3 の「Create Role」ページ。このページには、ロール名、ロールの説明、信頼されたエンティティ、ポリシー、アクセス許可の境界のフィールドがあります。

IAM ポリシーをロールにアタッチします。検索バーでポリシーを検索し、ポリシーの横にあるチェックマークを選択してアタッチします。完了したら Next を選択します。

new-policy-name が選択されたロール ARN。

ロールに名前と説明を付けて、Create Role を選択します。

「new-role-name」という名前のロールの例。

作成したロールの ARN と生成した external ID を控えておきます。これらはクラウドデータ取り込みの統合を作成する際に必要です。

Brazeでクラウドデータ取り込みを設定する

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

認証方法の認証情報。Role ARN and External IDを入力します。
バケット名
リージョン

認証情報 (AWSの設定とBrazeの設定) と構成フィールドを表示している S3 接続詳細セクション。

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

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

同期の名前を決めます。次に、アクティブな S3 ソースを選択し、同期のソーステーブルを入力します。データタイプを選択し、接続をテスト を選択します。

データプレビューで接続をテストするオプション。

AWSの設定プロセスで取得した残りの情報を入力します。以下を指定します。
- SQS URL (新しい連携ごとに一意である必要があります)
- フォルダーパス (任意、ワークスペース内の同期間で一意である必要があります)
データタイプを選択し、接続をテスト を選択して、Brazeが取り込み可能なファイルを一覧表示できることを確認します (ファイル内のデータではありません)。成功したら、次へ: 通知 を選択します。
アクセスや権限の問題で同期が中断した場合の通知先として、連絡先のメールアドレスを追加します。必要に応じて、ユーザーレベルのエラーや同期の成功に関する通知をオンにします。
同期を作成します。

必要なファイル形式

Cloud Data Ingestionは、JSON、CSV、Parquet の各ファイルをサポートしています。必要な列はデータタイプによって異なります。Braze では、ファイルストレージプロバイダーが定める要件以外に、ファイル名に関する追加の要件はありません。ファイル名は一意にしてください。タイムスタンプを付加すると一意性を確保しやすくなります。

注

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

サポートされているすべてのファイルタイプの例については、braze-examples のサンプルファイルを参照してください。

同期するデータタイプのタブを選択してください。

各行には、ユーザー識別子を 1 つだけと PAYLOAD 列が必要です。ソースファイルには異なる識別子タイプの行を混在させることができますが、個々の行で使用する識別子は 1 つだけにしてください。

識別子	説明
`EXTERNAL_ID`	更新するユーザーを識別します。Braze で使用されている `external_id`の値と一致する必要があります。
`ALIAS_NAME` および `ALIAS_LABEL`	この 2 つの列でユーザーエイリアスオブジェクトを作成します。`alias_name`は一意の識別子である必要があり、`alias_label`はエイリアスのタイプを指定します。ユーザーは異なるラベルを持つ複数のエイリアスを持つことができますが、`alias_label` ごとに `alias_name`は 1 つだけです。
`BRAZE_ID`	Braze のユーザー識別子です。これは Braze SDK によって生成されます。Cloud Data Ingestion では、Braze IDを使用して新しいユーザーを作成することはできません。新しいユーザーを作成するには、外部ユーザー ID またはユーザーエイリアスを指定してください。
`EMAIL`	ユーザーのメールアドレスです。同じメールアドレスを持つプロファイルが複数存在する場合、最後に更新されたプロファイルが優先的に更新されます。メールと電話番号の両方を含めた場合、Brazeはメールをプライマリ識別子として使用します。
`PHONE`	ユーザーの電話番号です。同じ電話番号を持つプロファイルが複数存在する場合、最後に更新されたプロファイルが優先的に更新されます。

PAYLOAD 列には、Braze のユーザーに同期するフィールドをユーザー属性オブジェクトの形式に従って記述した JSON 文字列が含まれます。

JSON の例

{"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\"}"}

CSV の例

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

重要

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

カスタムイベントでは、ユーザー属性と同じユーザー識別子の列を使用します。PAYLOAD 列はイベントオブジェクトの形式に従います。

{"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が含まれている必要があります。そうでない場合、そのファイルはスキップされます。

購入イベントでは、ユーザー属性と同じユーザー識別子の列を使用します。PAYLOAD 列は購入オブジェクトの形式に従います。

{"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が含まれている必要があります。そうでない場合、そのファイルはスキップされます。

カタログファイルでは、ユーザーデータファイルとは異なる識別子を使用します。カタログ同期を作成する前に、Braze で対象のカタログを作成してください。カタログのワークフロー全体については、カタログデータの同期と削除を参照してください。

列	必須	説明
`ID`	はい	カタログアイテムの一意の識別子です。Braze でアイテムを作成、更新、または削除するために使用されます。
`PAYLOAD`	はい	同期するカタログのフィールドと値の JSON 文字列です。Braze のカタログのスキーマと一致する必要があります。
`DELETED`	いいえ	`true`の場合、`ID`が一致するカタログアイテムが Braze のカタログから削除されます。作成または更新の操作では、この列を省略するか `false` に設定してください。

JSON の例

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

DELETED 列を含む CSV の例

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

DELETED 列を含まない CSV の例

ID,PAYLOAD
85,"{""product_name"": ""Product 85"", ""price"": 85.85}"
86,"{""product_name"": ""Product 86"", ""price"": 86.86}"

キャンバストリガーは、ゼロコピーパーソナライゼーションを実現します。送信先キャンバスの設定と考慮事項については、ゼロコピーパーソナライゼーションを参照してください。

フィールド	必須	説明
`EXTERNAL_ID`	はい。`external_id`、または `alias_name`と `alias_label`のいずれか	更新するユーザーを識別します。Braze で使用されている `external_id`の値と一致する必要があります。
`ALIAS_NAME` および `ALIAS_LABEL`	はい。`external_id`、または `alias_name`と `alias_label`のいずれか	この 2 つの列でユーザーエイリアスオブジェクトを作成します。`alias_name`は一意の識別子である必要があり、`alias_label`はエイリアスのタイプを指定します。ユーザーは異なるラベルを持つ複数のエイリアスを持つことができますが、`alias_label` ごとに `alias_name`は 1 つだけです。
`PROPERTIES`	はい	キャンバスでパーソナライゼーションプロパティとして使用できるようにするフィールドの JSON 文字列です。ユーザー固有の情報を含める必要があります。

開始するには、新しい同期を作成する際に キャンバストリガー データタイプを選択します。

ソースバケット内のファイルを使用して Braze のユーザープロファイルを削除するには、次の手順に従います。

他の同期と同じ設定を使用して、新しい Cloud Data Ingestion 同期を作成します。
Braze で同期を設定する際に、データタイプをユーザーを削除に設定します。
ユーザー識別子の列のみを含むファイルをソースバケットにアップロードします。PAYLOAD 列は含めないでください。誤って削除されることを防ぐため、ペイロードが存在すると同期は失敗します。

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

識別子	説明
`EXTERNAL_ID`	Braze で使用されている `external_id`と一致します。
`ALIAS_NAME` および `ALIAS_LABEL`	両方の列を組み合わせて、エイリアスでユーザーを識別します。
`BRAZE_ID`	Brazeが生成したユーザー ID です (既存のユーザーのみ)。

JSON の例

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

CSV の例

external_id
user-to-delete-001
user-to-delete-002

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

重要

ユーザーの削除は永続的であり、元に戻すことはできません。削除する予定のユーザーのみを含めてください。詳細については、Cloud Data Ingestionを使用したユーザーの削除を参照してください。

カタログアイテムの削除

ファイルストレージを使用してカタログからアイテムを削除するには、以下の手順に従います。

カタログデータの同期に使用しているものと同じ同期を使用します (データタイプは カタログ)。
CSVファイルまたはJSONファイルに、オプションの deleted (または DELETED) 列を追加します。
Brazeのカタログから削除したいカタログアイテムについて、deleted を true に設定します。

各行には引き続き ID と PAYLOAD が必要です。削除対象としてマークした行では、ペイロードは最小限でかまいません。Brazeは ID に基づいてアイテムを削除します。

同期が実行されると、deleted: true が設定された行に一致するカタログアイテムがBrazeで削除されます。カタログの同期と削除の動作の詳細については、カタログデータの同期と削除を参照してください。

知っておくべきこと

ソースバケットまたはコンテナーに追加するファイルは、512 MBを超えないようにしてください。この制限は、Amazon S3、Google Cloud Storage、Azure Blob Storageに適用されます。512 MBを超えるファイルはエラーとなり、Brazeに同期されません。Azure Blob Storage自体ははるかに大きなファイルを扱えますが、CDIはすべてのファイルストレージソースに同じ512 MBの制限を適用します。
ファイルあたりの行数に追加の制限はありませんが、同期の実行速度を向上させるため、Brazeでは小さいファイルの使用を推奨しています。たとえば、500 MBのファイル1つを取り込む場合は、100 MBのファイル5つを個別に取り込む場合よりも大幅に時間がかかります。
一定期間内にアップロードできるファイル数に追加の制限はありません。
ファイル内およびファイル間の順序付けはサポートされていません。想定される競合をモニタリングしている場合、Brazeでは定期的に更新をバッチ処理することをおすすめします。
CDIは、同期の作成後に追加されたファイルのみを処理します。既存のファイルを使用して、Brazeがバケットにアクセスし、取り込むファイルを検出できることを検証できますが、それらのファイルはBrazeに同期されません。既存のファイルをCDIで処理するには、同期したいファイルをソースバケットに再アップロードしてください。
BrazeがSQS メッセージを削除するのは、ファイルが正常に読み込まれ、その結果の行がBrazeの内部システムに取り込まれた場合のみです。Brazeは可視性タイムアウトを延長しません。デッドレターキューにメッセージが表示される場合は、最大のファイルの処理にかかる時間に合わせて可視性タイムアウトを延長することを検討してください。また、Brazeは各ファイルのメタデータを追跡しています。ファイルが正常に取り込まれた後にそのファイルの重複した SQS メッセージが届いた場合、Brazeは重複したメッセージを直ちに削除します。ファイルが正常に取り込まれなかった場合、BrazeはSQS メッセージを通常どおり処理します。

トラブルシューティング

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

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

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

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

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

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

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

統合オブジェクトが正しくないエラー

このエラーは、2つ以上のワークスペースに、同じクラウドストレージのバケットまたはフォルダーを指す連携がある場合に発生します。各クラウドストレージの場所は、一度に1つの連携でのみ使用できます。解決手順については、よくある質問を参照してください。

必須の列とペイロードの形式については、テーブルの設定を参照してください。
同期のスケジュール設定とデータポイントの効率化については、ベストプラクティスを参照してください。
同期実行のモニタリングについては、同期ログとオブザーバビリティを参照してください。
すべてのソースに共通する質問については、よくある質問を参照してください。

New Stuff!

Amazon S3のクラウドデータ取り込み

仕組み

AWS の定義

AWSでクラウドデータ取り込みを設定する

ステップ1: ソースバケットを作成する

ステップ2: SQS キューを作成する

ステップ3: アクセスポリシーを設定する

ステップ4: S3 バケットにイベント通知を追加する

ステップ5: IAM ポリシーを作成する

ステップ6: 認証を設定する

IAM role

Brazeでクラウドデータ取り込みを設定する

必要なファイル形式

カタログアイテムの削除

知っておくべきこと

トラブルシューティング

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

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

統合オブジェクトが正しくないエラー

関連ページ