Azure Blob Storageのクラウドデータ取り込み
このページでは、クラウドデータ取り込み (CDI) を使用して Azure Blob Storageから Brazeにデータを同期するために必要なすべての情報を説明します。作成する Azure リソース、Brazeでのソースの接続方法と同期の作成方法、各データタイプのファイル形式、Azure 固有のトラブルシューティングについて取り上げます。
仕組み
Azure Blob Storageの統合は、スケジュールベースではなくイベント駆動型です。コンテナーに新しいファイルが作成されると、Azure Event Gridのイベントサブスクリプションが Blob Created イベントを Azure Storage キューに発行します。Brazeはキューからこれらのメッセージを読み取り、新しいファイルを取り込みます。
この統合には、次のリソースが必要です。
- データストレージ用の BLOB コンテナーを含むストレージアカウント
- 新しいファイルの通知用の Azure Storage キューとイベントサブスクリプション
- CDIがコンテナーとキューを読み取るために使用する Microsoft Entra ID サービスプリンシパル
Azureの用語
| 用語 | 定義 |
|---|---|
| ストレージアカウント | ストレージアカウントは、CDIがファイルを読み取るコンテナーと、CDIが通知を読み取るキューの両方を保持する最上位の Azure リソースです。 |
| コンテナー | コンテナーには、CDIに取り込ませたいデータファイルが格納されます。コンテナーはストレージアカウント内に存在します。 |
| Azure Storage キュー | キューはコンテナーから新しいファイルの通知を受け取ります。CDIはこのキューのメッセージを読み取って確認し、取り込むファイルを判断します。 |
| イベントサブスクリプション | イベントサブスクリプションは、Azure Event Grid サービスを使用して、ストレージアカウントからのイベントを宛先にルーティングします。Blob Created イベントをキューに送信するように設定します。 |
| システムトピック | システムトピックはイベントのソースを表します。最初のイベントサブスクリプションを追加すると、Event Gridがストレージアカウント用に作成します。 |
| サービスプリンシパル | サービスプリンシパルは、CDIが認証に使用する Microsoft Entra IDの ID です。アプリの登録を通じて作成し、その認証情報を Brazeに入力します。 |
| Azure ロールの割り当て | ロールの割り当ては、特定のスコープでサービスプリンシパルに一連のアクセス許可を付与します。ストレージアカウントで、Brazeのサービスプリンシパルに 3 つの組み込みロールを割り当てます。 |
Azureでクラウドデータ取り込みを設定する
ステップ 1: コンテナーを作成する
コンテナーとキューは同じストレージアカウント内に存在する必要があります。既存のストレージアカウントを再利用することもできます。まだお持ちでない場合は、Azure portalで Storage accounts > + Create に移動して作成してください。
- Azure portalでストレージアカウントに移動し、Data storage > Containers に移動します。
- + Add container を選択し、名前を付けます。
ストレージアカウント名とコンテナー名を控えておいてください。Brazeでソースを設定する際に両方が必要になります。
ステップ 2: キューを作成する
- 同じストレージアカウントで、Data storage > Queues に移動します。
- + Queue を選択し、名前を付けます。
キュー名を控えておいてください。同期を作成する際に必要になります。また、同期ごとに専用のキューが必要です。
ステップ 3: イベントサブスクリプションを作成する
ファイルが到着するたびにコンテナーからキューに通知されるように、イベントサブスクリプションを作成します。
- 同じストレージアカウントで Events に移動し、+ Event Subscription を選択します。
- Event Subscription Details で Name を入力し、Event Schema を Event Grid Schema に設定します。
- Topic Details で System Topic Name を確認します。ストレージアカウントにまだシステムトピックがない場合は、名前を入力して作成します。すでにある場合は、フィールドにその名前が表示され、変更することはできません。ストレージアカウント上のすべてのイベントサブスクリプションは、同じシステムトピックを使用します。
- Event Types で、Filter to Event Types を Blob Created のみに設定します。Blob Deleted もデフォルトで選択されているため、選択を解除してください。
- Endpoint Details で、Endpoint Type を Storage Queue に設定します。エンドポイントタイプを選択すると、Configure an endpoint リンクが表示されます。
- Configure an endpoint を選択し、作業中のストレージアカウントを選択します。
- Select existing queue を選択し、ステップ 2で作成したキューを選択します。
- Select を選択してエンドポイントを確定します。
- Create を選択します。
ステップ 4: 認証を設定する
CDIは次の認証方法でストレージアカウントに接続します。
| 方法 | Brazeによる認証方法 | Brazeで入力する内容 |
|---|---|---|
| Service principal | Braze authenticates as a Microsoft Entra ID service principal with a client secret. | Tenant ID, Principal ID, and Client Secret |
Service principal
CDIは、Microsoft Entra ID 認証を使用するサービスプリンシパルを介してストレージアカウントに接続します。Brazeが接続するには、次の情報が必要です。
- AzureアカウントのテナントID（ディレクトリとも呼ばれます）
- サービスプリンシパルのプリンシパルID（アプリケーションIDとも呼ばれます）
- Brazeが認証に使用するクライアントシークレット
アプリケーションを登録するには、Microsoft Entra IDでアプリ登録を作成する権限が必要です。この権限がない場合は、Entra 管理者にこのステップの実行を依頼し、認証情報を共有してもらってください。
- Azureポータルで、Microsoft Entra管理センターに移動し、App Registrationsを選択します。
- Identity > Applications > App registrationsの下にある+ New registrationを選択します。
- 名前を入力し、サポートされるアカウントの種類として
Accounts in this organizational directory onlyを選択します。次に、Registerを選択します。 - 作成したアプリケーション（サービスプリンシパル）を選択し、Certificates & secrets > + New client secretに移動します。
- シークレットの説明を入力し、シークレットの有効期限を設定します。次に、Addを選択します。
- 作成されたクライアントシークレットをメモしておき、Brazeの設定で使用します。
Azureでは、サービスプリンシパルのシークレットの有効期限を無期限に設定することはできません。Brazeへのデータフローを維持するため、有効期限が切れる前に認証情報を更新してください。
CDI 専用のサービスプリンシパルを作成することをおすすめします。そうすることで、アクセス範囲を同期対象のコンテナーとキューに限定できます。Microsoft Fabric ソース用にすでにサービスプリンシパルを設定している場合は再利用できますが、その場合は両方にアクセスできるようになります。いずれの場合も、次のステップのロール割り当てが必要です。
ステップ 5: サービスプリンシパルにアクセス許可を割り当てる
CDIに必要なのは、ファイルを読み取り、キューのメッセージを処理するのに十分なアクセス権のみです。ロールの割り当ては下位に継承されるため、これら 3 つの組み込みロールは、サブスクリプションやリソースグループではなく、ストレージアカウント自体に割り当ててください。Storage Blob Data Contributor、Storage Account Contributor、Owner などのより広範なロールは割り当てないでください。これらは CDIが使用しない書き込み権限や管理権限を付与します。
- ストレージアカウントに移動し、Access Control (IAM) に移動します。
- Add > Add role assignment を選択します。
- ステップ 4で作成したサービスプリンシパルを名前で検索します。
- 次の組み込みロールを割り当てます。
- Storage Blob Data Reader: CDIがコンテナー内のファイルを読み取れるようにします。
- Storage Queue Data Reader: CDIがキュー自体を読み取れるようにし、同期で指定したキューを見つけてそのプロパティを確認できるようにします。
- Storage Queue Data Message Processor: CDIがキューのメッセージをピーク、取得、削除できるようにします。
コンテナー内の BLOBへの読み取りアクセス、キューへの読み取りアクセス、キューのメッセージの受信と削除の機能のみを付与するものであれば、代わりにカスタムロールを使用することもできます。
Add role assignment がグレー表示されている場合、お使いのアカウントではこのストレージアカウントでロールを割り当てることができません。これには Owner や User Access Administrator などのロールが必要です。Azureの管理者にこのステップの実施を依頼してください。
Brazeでクラウドデータ取り込みを設定する
- Brazeで データ設定 > クラウドデータ取り込み > ソース に移動し、データソースを追加 を選択して、Azure Blob を選択します。
- Azure Blob 接続の詳細 のフィールドに入力します。
- 認証情報: ステップ 4で設定した認証方法のフィールド。Tenant ID, Principal ID, and Client Secretを入力します。
- 設定: ストレージアカウント と コンテナー
- 接続をテスト を選択してから、ソースに接続 を選択します。
- 同期を作成します。データ設定 > クラウドデータ取り込み > 同期 に移動し、データ同期を作成 を選択します。
- 設定 で同期名を指定し、Azure Blob ソースを選択して、データタイプ (ユーザー属性、カスタムイベント、購入イベント、カタログ、ユーザーの削除 など) を選択します。
- データ定義 で、次の項目を指定します。
- ストレージキュー名: ステップ 2で作成したキュー。同期ごとに専用のキューが必要です (共有コンテナー内のフォルダーを同期するを参照)。
- フォルダーパス (オプション): コンテナー内のパスプレフィックス
- プレビューと検証 を選択して、CDIがキューに到達でき、取り込み可能なファイルを一覧表示できることを確認します。テストが成功するとコンテナー内の既存のファイルが一覧表示されますが、それらのファイルは自動的には同期されません。接続の検証が成功するまで、同期は有効になりません。
- 通知 で、エラー通知用の連絡先メールアドレスを追加します。
- ファイルストレージの同期では、スケジュール にオプションはありません。Azure Blob Storageの同期はイベント駆動型のため、CDIは新しいファイルがアップロードされると取り込みます。
- 概要 を確認し、同期を作成 を選択します。
共有コンテナー内のフォルダーを同期する
1 つのコンテナーを複数の同期で再利用できますが、各同期には専用のストレージキューと専用のフォルダーが必要です。
2 つの同期で同じストレージキューを使用することはできません。別の同期ですでに使用されているキューを入力すると、CDIがそれを警告し、既存の同期へのリンクを表示します。
共有コンテナー内で同期したいフォルダーごとに、次の手順を実行します。
- ステップ 2と同様に、そのフォルダー用のキューを作成します。
- ステップ 3と同様に、コンテナーの Blob Created イベントをそのキューに送信するイベントサブスクリプションを作成します。
- Brazeで同期を作成する際に、そのフォルダーの ストレージキュー名 を入力し、フォルダーパス (オプション) に
attributes/などのフォルダープレフィックスを設定します。CDIは、パスがそのプレフィックスで始まるファイルのみを取り込みます。
必要なファイル形式
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で処理するには、同期したいファイルをソースバケットに再アップロードしてください。
トラブルシューティング
ファイルのアップロードと処理
CDIは、同期の作成後にアップロードされたファイルのみを処理します。新しい BLOBごとに Blob Created イベントがキューにトリガーされます。コンテナー内にすでに存在するファイルを取り込むには、再度アップロードしてください。
予期しないファイルエラーへの対処
ファイルが取り込まれない場合は、次の点を確認してください。
- イベントサブスクリプションがストレージアカウント上に存在し、Blob Created にフィルターされていること。
- イベントサブスクリプションが Event Grid Schema を使用していること。CDIは他のスキーマで配信されたイベントを読み取ることができません。
- イベントサブスクリプションのエンドポイントが、別のキューではなく、同期で設定したキューを指していること。
- Brazeのサービスプリンシパルに、ストレージアカウントで Storage Blob Data Reader、Storage Queue Data Reader、Storage Queue Data Message Processor が割り当てられていること。
- サービスプリンシパルのクライアントシークレットの有効期限が切れていないこと。Azureではクライアントシークレットに有効期限が適用され、有効期限が切れたシークレットは同期を停止させます。
詳細については、Microsoftのドキュメントの Azure Blob Storage as an Event Grid source を参照してください。
不正な統合オブジェクトエラー
このエラーは、2 つ以上のワークスペースに同じクラウドストレージバケットまたはフォルダーを指す統合がある場合に発生します。各クラウドストレージの場所は、一度に 1 つの統合でのみ使用できます。解決手順については、よくある質問を参照してください。
関連ページ
- 必須の列とペイロードの形式については、テーブルの設定を参照してください。
- 同期のスケジュール設定とデータポイントの効率化については、ベストプラクティスを参照してください。
- 同期実行のモニタリングについては、同期ログとオブザーバビリティを参照してください。
- すべてのソースに共通する質問については、よくある質問を参照してください。