Semantik der Zustellung von Events
Auf dieser Seite wird beschrieben und definiert, wie Currents die Flat-File-Event-Daten verwaltet, die wir an Data Warehouse-Speicherpartner senden.
„Currents für Datenspeicher“ ist ein kontinuierlicher Datenstrom von unserer Plattform zu einem Speicher-Bucket auf einer unserer Data Warehouse-Partnerverbindungen. Currents schreibt Avro-Dateien in regelmäßigen Abständen in Ihren Speicher-Bucket, sodass Sie die Event-Daten mit Ihrem eigenen Business-Intelligence-Toolset (BI) verarbeiten und analysieren können.
Dieser Inhalt gilt nur für die Flat-File-Event-Daten, die wir an Data Warehouse-Speicherpartner (Google Cloud Storage, Amazon S3 und Microsoft Azure Blob Storage) senden.
Inhalte, die für andere Partner gelten, finden Sie in unserer Liste der verfügbaren Partner und auf den jeweiligen Seiten.
Test-Events
Wenn Sie eine Currents-Integration einrichten, klicken Sie auf Test-Events senden, um die Verbindung mit Ihrem Storage-Bucket zu überprüfen. Diese Test-Events bestätigen, dass Ihre Integration Daten korrekt empfangen und verarbeiten kann.
Datenformat von Test-Events: Test-Events enthalten Platzhalterwerte, die den korrekten Datentypen der einzelnen Felder entsprechen, aber keine realistischen oder genauen Daten enthalten. Beispielsweise kann ein timezone-Feld einen UUID-ähnlichen String anstelle eines gültigen Zeitzonen-Bezeichners (wie „America/Chicago“) enthalten. Auch andere Felder wie campaign_name und ip_pool können Platzhalterwerte statt tatsächlicher Daten enthalten.
Dieses Verhalten ist beabsichtigt. Test-Events dienen in erster Linie dazu, die Verbindung und die Einrichtung der Integration zu testen, nicht die Genauigkeit der Daten zu überprüfen. Um echte Events mit genauen Daten zu sehen, verwenden Sie eine Test-Integration von Currents, um tatsächliche Event-Daten durch Ihre Pipeline zu senden.
At-least-once-Zustellung
Als System mit hohem Durchsatz bietet Currents eine „At-least-once“-Zustellung von Events. Das bedeutet, dass gelegentlich doppelte Events in Ihren Storage-Bucket geschrieben werden können. Das kann passieren, wenn Events aus irgendeinem Grund erneut aus unserer Warteschlange verarbeitet werden.
Wenn Ihre Anwendungsfälle eine „Exactly-once“-Zustellung erfordern, können Sie das Feld mit dem eindeutigen Bezeichner, das mit jedem Event gesendet wird (id), nutzen, um Events zu deduplizieren. Da die Datei unsere Kontrolle verlässt, sobald sie in Ihren Storage-Bucket geschrieben wird, können wir eine Deduplizierung auf unserer Seite nicht garantieren.
Zeitstempel
Alle von Currents exportierten Zeitstempel werden in der Zeitzone UTC gesendet. Bei einigen Events, für die sie verfügbar ist, ist zusätzlich ein Zeitzonenfeld enthalten. Es liefert die lokale Zeitzone der Nutzer:innen zum Zeitpunkt des Events im Format der Internet Assigned Numbers Authority (IANA).
Latenz
Events, die über das SDK oder die API an Braze gesendet werden, können einen Zeitstempel aus der Vergangenheit enthalten. Das bekannteste Beispiel ist, wenn SDK-Daten in eine Warteschlange gestellt werden, etwa wenn keine mobile Verbindung besteht. In diesem Fall gibt der Zeitstempel des Events an, wann das Event erzeugt wurde. Daher scheint ein Teil der Events eine hohe Latenz aufzuweisen.
Die Android-, Swift- und Web-SDKs von Braze speichern nicht gesendete Events auf dem Gerät und senden sie erneut, sobald das Gerät wieder verbunden ist. Dabei gibt es keine zeitliche Begrenzung. Beim Web SDK sind Events in der Warteschlange nur durch den Browserspeicher begrenzt (etwa 5 MB).
Für verspätet eintreffende Events gibt es kein maximales Zeitfenster. Currents ist darauf ausgelegt, jedes empfangene Event zu exportieren, unabhängig davon, wie alt sein Zeitstempel ist. Ein verspätet eintreffendes Event wird in die date=-Partition für die Stunde geschrieben, in der es bei Braze zur Verarbeitung in die Warteschlange gestellt wurde. Sein ursprünglicher Zeitstempel bleibt im Feld time erhalten. Braze trägt verspätete Events nicht nachträglich in frühere Partitionen ein.
Da verspätete Events in aktuellen Partitionen landen, empfiehlt Braze, Dateien zu verarbeiten, sobald sie in Ihren Storage-Bucket geschrieben werden, anstatt ältere date=-Partitionen mit einem Lookback-Fenster erneut zu durchsuchen. Um Duplikate zu entfernen, verwenden Sie das Feld id des Events wie unter Mindestens einmalige Zustellung beschrieben.
Apache Avro-Format
Die Datenspeicher-Integrationen von Braze-Currents geben Daten im Format .avro aus. Wir haben uns für Apache Avro entschieden, weil es ein flexibles Datenformat ist, das Schemaentwicklung nativ unterstützt und von einer Vielzahl von Datenprodukten unterstützt wird:
- Avro wird von nahezu jedem großen Data Warehouse unterstützt.
- Wenn Sie Ihre Daten in S3 belassen möchten, lässt sich Avro besser komprimieren als CSV und JSON. Sie zahlen also weniger für den Speicher und benötigen möglicherweise weniger CPU-Leistung, um die Daten zu parsen.
- Avro erfordert Schemas, wenn Daten geschrieben oder gelesen werden. Schemas können im Laufe der Zeit weiterentwickelt werden, sodass neue Felder hinzugefügt werden können, ohne dass etwas kaputtgeht.
Currents erstellt für jeden Event-Typ eine Datei im folgenden Format:
<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
Sie können den Code wegen der Bildlaufleiste nicht sehen? Wie Sie das beheben, erfahren Sie auf der Startseite des Braze-Benutzerhandbuchs.
Ein Pfad für ein Push-Send-Event kann beispielsweise so aussehen:
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
Das Pfadsegment version ist ein einfacher ganzzahliger Wert für die Currents-Version, z. B. version=6.
Das Pfadsegment version zeigt an, dass sich das Schema der Dateien geändert hat. Verwenden Sie es nur als Indikator, nicht als Datenspalte, die Sie abfragen.
Einige Tools lesen Hive-artige key=value-Pfadsegmente wie version=6 als Partitionsspalten ein (zum Beispiel externe BigQuery-Tabellen mit Hive-Partitionierung). Wenn Sie Dateien auf diese Weise laden, kann der Partitionsschlüssel version mit Event-Feldern kollidieren, die ebenfalls version heißen, etwa dem Feld version in users.messages.inappmessage.Abort-Events.
Um diesen Konflikt zu vermeiden, richten Sie Ihre Pipeline so ein, dass sie das Pfadsegment version nicht als Spalte behandelt. Den Wert des Felds version bei In-App-Nachrichten können Sie ignorieren. Es handelt sich um ein Legacy-Feld, das Legacy-In-App-Nachrichten, die nicht mehr verwendet werden, von getriggerten In-App-Nachrichten unterschied.
| Dateinamensegment | Definition |
|---|---|
<your-bucket-prefix> |
Das für diese Currents-Integration festgelegte Präfix. |
<cluster-identifier> |
Für den internen Gebrauch durch Braze. Ist ein String wie „prod-01“, „prod-02“, „prod-03“ oder „prod-04“. Alle Dateien haben denselben Cluster-Bezeichner. |
<connection-type-identifier> |
Der Bezeichner für die Art der Verbindung. Optionen sind „S3“, „AzureBlob“ oder „GCS“. |
<integration-id> |
Die eindeutige ID für diese Currents-Integration. Braze legt diese ID beim Erstellen der Integration fest, und sie ändert sich nicht, wenn Sie die Einstellungen der Integration bearbeiten (z. B. Feldtransformationen). |
<event-type> |
Der Typ des Events in der Datei. |
<date> |
Die Stunde, in der Events in unserem System zur Verarbeitung in die Warteschlange gestellt werden, in der Zeitzone UTC. Format: JJJJ-MM-TT-HH. |
version=<currents_version> |
Die Currents-Version für den Pipeline-Pfad. Dieser Wert ist eine einfache Ganzzahl wie 6. |
<environment> |
Für den internen Gebrauch durch Braze. |
<partition> |
Für den internen Gebrauch durch Braze. Ganzzahl. |
<offset> |
Für den internen Gebrauch durch Braze. Ganzzahl. Beachten Sie, dass verschiedene Dateien, die innerhalb derselben Stunde gesendet werden, einen unterschiedlichen <offset>-Parameter haben. |
Die Konventionen für Dateinamen können sich ändern. Braze empfiehlt, alle Schlüssel in Ihrem Bucket zu durchsuchen, die das Präfix <your-bucket-prefix> haben.
Avro-Schreibschwelle
Unter normalen Umständen schreibt Braze alle 5 Minuten oder alle 15.000 Events Datendateien in Ihren Speicher-Bucket – je nachdem, was zuerst eintritt. Bei hoher Last schreiben wir möglicherweise größere Datendateien mit bis zu 100.000 Events pro Datei.
Currents ist darauf ausgelegt, große Event-Spitzen intern zu puffern, etwa die Events einer Nachricht, die an Millionen von Nutzer:innen gesendet wird. Sie müssen für diese Spitzen keinen zusätzlichen Schreibdurchsatz und keine zusätzliche I/O-Kapazität für Ihren Speicher-Bucket einplanen.
Currents schreibt niemals leere Dateien.
Änderungen am Avro-Schema
Von Zeit zu Zeit nimmt Braze möglicherweise Änderungen am Avro-Schema vor, wenn Felder hinzugefügt, geändert oder entfernt werden. Für unsere Zwecke gibt es zwei Arten von Änderungen: Breaking Changes und Non-Breaking Changes. Alle Schemaänderungen werden in Currents-Releases gebündelt, und jedes Release erhöht das Segment version=<currents_version> im Speicherpfad (zum Beispiel von version=6 auf version=7). Currents-Events, die in Azure Blob Storage, Google Cloud Storage und Amazon S3 geschrieben werden, verwenden das folgende Pfadformat:
<your-bucket-prefix>/<currents-integration-id>/event_type=<event-type>/date=<date>/version=<currents_version>/<environment>/<avro-file>
Non-Breaking Changes
Wenn dem Avro-Schema ein Feld hinzugefügt wird, betrachten wir dies als Non-Breaking Change. Hinzugefügte Felder sind immer „optionale“ Avro-Felder (z. B. mit dem Standardwert null), sodass sie gemäß der Avro-Spezifikation zur Schemaauflösung mit älteren Schemas „übereinstimmen“. Diese Ergänzungen sollten bestehende ETL-Prozesse (Extract, Transform, Load) nicht beeinträchtigen, da das Feld einfach ignoriert wird, bis es zu Ihrem ETL-Prozess hinzugefügt wird.
Wir empfehlen, dass Ihr ETL-Setup die verarbeiteten Felder explizit angibt, damit der Ablauf nicht unterbrochen wird, wenn neue Felder hinzugefügt werden.
Breaking Changes
Wenn ein Feld aus dem Avro-Schema entfernt oder darin geändert wird, betrachten wir dies als Breaking Change. Breaking Changes können Anpassungen an bestehenden ETL-Prozessen erfordern, da verwendete Felder möglicherweise nicht mehr wie erwartet erfasst werden.
Alle Breaking Changes werden vor dem Release angekündigt.
Den vollständigen Verlauf der Änderungen nach Version finden Sie im Currents-Changelog.