イベント配信のセマンティクス
このページでは、データウェアハウスストレージパートナーに送信するフラットファイルのイベントデータをCurrentsがどのように管理するかを概説および定義します。
データストレージ用のCurrentsは、弊社のプラットフォームから、データウェアハウスのパートナー接続の1つにあるストレージバケットに送信されるデータの連続ストリームです。Currentsは通常のしきい値に達するとストレージバケットにAvroファイルを書き込むので、独自のビジネスインテリジェンス (BI) ツールセットを使用してイベントデータの処理および分析ができます。
このコンテンツは、データウェアハウスストレージパートナー (Google Cloud Storage、Amazon S3、Microsoft Azure Blob Storage) に送信するフラットファイルのイベントデータにのみ適用されます。
他のパートナーに適用されるコンテンツについては、利用可能なパートナーのリストを参照し、それぞれのページを確認してください。
テストイベント
Currents 連携を設定する際に、テストイベントを送信をクリックすると、ストレージバケットとの接続を検証できます。これらのテストイベントにより、連携がデータを正しく受信して処理できることを確認します。
テストイベントのデータ形式: テストイベントには、各フィールドの正しいデータ型に一致するプレースホルダー値が含まれていますが、現実的または正確なデータは含まれていません。たとえば、timezone フィールドには、有効なタイムゾーン識別子 (「America/Chicago」など) ではなく UUID のような文字列が含まれている場合があります。また、campaign_name や ip_pool などの他のフィールドにも、実際のデータではなくプレースホルダー値が含まれている場合があります。
これは想定どおりの動作です。テストイベントは主に接続と連携の設定をテストするためのものであり、データの正確性を検証するためのものではありません。正確なデータを含む実際のイベントを確認するには、テスト用の Currents 連携を使用して、実際のイベントデータをパイプラインに送信してください。
少なくとも1回の配信
Currents は高スループットのシステムであるため、イベントを「少なくとも1回」配信します。つまり、重複したイベントがストレージバケットに書き込まれることがあります。これは、何らかの理由でイベントがキューから再処理された場合に発生する可能性があります。
ユースケースで「1回限り」の配信が必要な場合は、すべてのイベントとともに送信される一意の識別子フィールド (id) を使用して、イベントの重複を排除できます。ファイルがストレージバケットに書き込まれた時点で Braze の管理下を離れるため、Braze 側で重複排除を保証する方法はありません。
タイムスタンプ
Currentsがエクスポートするタイムスタンプは、すべてUTCタイムゾーンで送信されます。一部のイベントでは、利用可能な場合にタイムゾーンフィールドも含まれます。このフィールドは、イベント発生時点のユーザーのローカルタイムゾーンをInternet Assigned Numbers Authority (IANA) 形式で示します。
レイテンシー
SDKまたはAPI経由でBrazeに送信されるイベントには、過去のタイムスタンプが含まれることがあります。最も代表的な例は、モバイル接続がない場合などにSDKデータがキューに入れられるケースです。この場合、イベントのタイムスタンプにはイベントが生成された時刻が反映されます。そのため、一部のイベントはレイテンシーが高いように見えます。
BrazeのAndroid、Swift、Web SDKは、未送信のイベントをデバイスに保存し、デバイスが再接続した後に再送信します。時間ベースの打ち切りはありません。Web SDKの場合、キューに入れられるイベントの上限はブラウザーのストレージ容量 (約5 MB) のみです。
遅れて到着するイベントに最大期間はありません。Currentsは、イベントのタイムスタンプがどれだけ古いかにかかわらず、受信したすべてのイベントをエクスポートするよう設計されています。遅れて到着したイベントは、Brazeで処理のキューに入れられた時間帯のdate=パーティションに書き込まれ、timeフィールドには元のタイムスタンプが保持されます。Brazeは、遅延イベントを以前のパーティションにバックフィルしません。
遅延イベントは現在のパーティションに格納されるため、Brazeでは、ルックバック期間を設けて古いdate=パーティションを再スキャンするのではなく、ストレージバケットに書き込まれた時点でファイルを処理することをおすすめします。重複を削除するには、少なくとも1回の配信で説明しているように、イベントのidフィールドを使用してください。
Apache Avro 形式
Braze Currents のデータストレージ統合は、.avro 形式でデータを出力します。Apache Avro を選択したのは、スキーマの進化をネイティブにサポートする柔軟なデータ形式であり、さまざまなデータ製品でサポートされているためです。
- Avro は、ほぼすべての主要なデータウェアハウスでサポートされています。
- データを S3 に保存したままにしたい場合、Avro は CSV や JSON よりも圧縮率が高いため、ストレージコストを抑えられ、データの解析に使用する CPU を削減できる可能性があります。
- Avro では、データの書き込み時または読み取り時にスキーマが必要です。スキーマは時間の経過とともに進化させることができ、フィールドの追加にも破損なく対応できます。
Currents は、次の形式でイベントタイプごとにファイルを作成します。
<your-bucket-prefix>/dataexport.<cluster-identifier>.<connection-type-identifier>.integration.<integration-id>/event_type=<event-type>/date=<date>/version=<currents_version>/<environment>/dataexport.<cluster-identifier>.<connection-type-identifier>.integration.<integration-id>+<partition>+<offset>.avro
たとえば、プッシュ送信イベントのパスは次のようになります。
currents-export/dataexport.prod-01.S3.integration.69cadaaed2d51b7c75b1a3e5/event_type=users.messages.pushnotification.Send/date=2025-04-01-17/version=6/us-01/dataexport.prod-01.S3.integration.69cadaaed2d51b7c75b1a3e5+0+123456.avro
version パスセグメントは、version=6 のような単純な整数の Currents バージョン値です。
version パスセグメントは、ファイルのスキーマが変更されたことを示します。これはインジケーターとしてのみ使用し、クエリ対象のデータ列としては使用しないでください。
一部のツールは、version=6 のような Hive 形式の key=value パスセグメントをパーティション列として読み取ります（例: Hive パーティショニングを使用した BigQuery 外部テーブル）。この方法でファイルを読み込むと、version パーティションキーが、同じく version という名前のイベントフィールド（users.messages.inappmessage.Abort イベントの version フィールドなど）と競合する場合があります。
この競合を避けるには、version パスセグメントを列として扱わないようにパイプラインを設定してください。アプリ内メッセージの version フィールドの値は無視してかまいません。これは、現在は使用されていない従来のアプリ内メッセージと、トリガーされたアプリ内メッセージを区別するための従来のフィールドです。
| ファイル名セグメント | 定義 |
|---|---|
<your-bucket-prefix> |
この Currents 統合に設定されたプレフィックス。 |
<cluster-identifier> |
Braze の内部使用向け。「prod-01」、「prod-02」、「prod-03」、「prod-04」などの文字列になります。すべてのファイルは同じクラスター識別子を持ちます。 |
<connection-type-identifier> |
接続タイプの識別子。オプションは「S3」、「AzureBlob」、「GCS」です。 |
<integration-id> |
この Currents 統合の一意の ID。この ID は統合の作成時に Braze によって設定され、統合の設定（フィールド変換など）を編集しても変更されません。 |
<event-type> |
ファイル内のイベントのタイプ。 |
<date> |
イベントが処理のためにシステムのキューに入れられた時間（UTC タイムゾーン）。形式は YYYY-MM-DD-HH です。 |
version=<currents_version> |
パイプラインパスの Currents バージョン。この値は 6 のような単純な整数です。 |
<environment> |
Braze の内部使用向け。 |
<partition> |
Braze の内部使用向け。整数。 |
<offset> |
Braze の内部使用向け。整数。同じ時間内に送信された異なるファイルには、異なる <offset> パラメーターが付与されることに注意してください。 |
ファイルの命名規則は変更される場合があります。Braze では、バケット内で <your-bucket-prefix> のプレフィックスを持つすべてのキーを検索することをお勧めします。
Avro の書き込みしきい値
通常の状況では、Braze は5分ごとまたは15,000イベントごとのいずれか早い方のタイミングで、ストレージバケットにデータファイルを書き込みます。負荷が高い場合は、1ファイルあたり最大100,000イベントの大きなデータファイルを書き込むことがあります。
Currents は、数百万人のユーザーに送信されたメッセージのイベントなど、大量のイベントのバーストを内部でバッファリングするように設計されています。このようなバーストに備えて、ストレージバケットで追加の書き込みスループットや I/O 容量を計画する必要はありません。
Currents が空のファイルを書き込むことはありません。
Avro スキーマの変更
Braze では、フィールドの追加、変更、削除に伴い、Avro スキーマを変更することがあります。ここでは、変更を破壊的変更と非破壊的変更の2種類に分けて説明します。すべてのスキーマ変更は Currents のリリースにまとめられ、各リリースでストレージパスの version=<currents_version> セグメントが進みます（例: version=6 から version=7）。Azure Blob Storage、Google Cloud Storage、Amazon S3 に書き込まれる Currents イベントは、次のパス形式を使用します。
<your-bucket-prefix>/<currents-integration-id>/event_type=<event-type>/date=<date>/version=<currents_version>/<environment>/<avro-file>
非破壊的変更
Avro スキーマにフィールドが追加された場合、これは非破壊的変更とみなされます。追加されるフィールドは常に「オプション」の Avro フィールド（デフォルト値が null など）となるため、Avro スキーマ解決仕様に従って古いスキーマと「一致」します。これらの追加は既存の抽出、変換、読み込み (ETL) プロセスに影響しません。フィールドは ETL プロセスに追加されるまで単に無視されるためです。
新しいフィールドが追加されたときにフローが中断されないように、ETL の設定で処理対象のフィールドを明示的に指定することをお勧めします。
破壊的変更
Avro スキーマからフィールドが削除された場合、またはフィールドが変更された場合、これは破壊的変更とみなされます。使用中のフィールドが期待どおりに記録されなくなる可能性があるため、破壊的変更では既存の ETL プロセスの修正が必要になる場合があります。
すべての破壊的変更は、リリース前に事前に通知されます。
バージョンごとの変更の全履歴については、Currents の変更ログを参照してください。