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.
Testereignisse
Wenn Sie eine Currents-Integration einrichten, klicken Sie auf Send Test Events, um die Verbindung mit Ihrem Speicher-Bucket zu überprüfen. Diese Testereignisse bestätigen, dass Ihre Integration Daten korrekt empfangen und verarbeiten kann.
Datenformat der Testereignisse: Testereignisse enthalten Platzhalterwerte, die den korrekten Datentypen für jedes Feld entsprechen, jedoch 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, und andere Felder wie campaign_name und ip_pool können ebenfalls Platzhalterwerte statt tatsächlicher Daten enthalten.
Dies ist erwartetes Verhalten. Testereignisse dienen in erster Linie dem Testen der Verbindung und der Integrationseinrichtung, nicht der Validierung der Datengenauigkeit. Um echte Ereignisse mit genauen Daten zu sehen, verwenden Sie eine Test-Currents-Integration, um tatsächliche Ereignisdaten durch Ihre Pipeline zu senden.
Zustellung nach dem At-least-once-Prinzip
Als Hochdurchsatzsystem bietet Currents eine „At-least-once“-Zustellung von Ereignissen, was bedeutet, dass duplizierte Ereignisse gelegentlich in Ihren Speicher-Bucket geschrieben werden können. Dies kann passieren, wenn Ereignisse aus unserer Warteschlange aus irgendeinem Grund erneut verarbeitet werden.
Wenn Ihre Anwendungsfälle eine „Exactly-once“-Zustellung erfordern, können Sie das eindeutige Bezeichnerfeld, das mit jedem Ereignis gesendet wird (id), verwenden, um Ereignisse zu deduplizieren. Da die Datei unserer Kontrolle entzogen ist, sobald sie in Ihren Speicher-Bucket geschrieben wurde, können wir keine Deduplizierung auf unserer Seite garantieren.
Zeitstempel
Alle von Currents exportierten Zeitstempel werden in der Zeitzone UTC gesendet. Bei einigen Ereignissen, bei denen es verfügbar ist, wird auch ein Zeitzonen-Feld mitgeliefert, das die Ortszeit der Nutzer:innen zum Zeitpunkt des Ereignisses im Format der Internet Assigned Numbers Authority (IANA) enthält.
Latenz
Ereignisse, die über SDK oder API an Braze gesendet werden, können einen Zeitstempel aus der Vergangenheit enthalten. Das häufigste Beispiel ist, wenn SDK-Daten in eine Warteschlange gestellt werden, etwa wenn keine mobile Verbindung besteht. In diesem Fall spiegelt der Zeitstempel des Ereignisses den Zeitpunkt wider, zu dem das Ereignis erzeugt wurde. Das bedeutet, dass ein gewisser Prozentsatz der Ereignisse eine hohe Latenz aufzuweisen scheint.
Apache-Avro-Format
Die Braze-Currents-Datenspeicherintegrationen geben Daten im .avro-Format aus. Wir haben uns für Apache Avro entschieden, weil es ein flexibles Datenformat ist, das nativ Schema-Evolution unterstützt und von einer Vielzahl von Datenprodukten unterstützt wird:
- Avro wird von nahezu jedem großen Data Warehouse unterstützt.
- Falls Sie Ihre Daten in S3 belassen möchten, komprimiert Avro besser als CSV und JSON, sodass Sie weniger für Speicher bezahlen und potenziell weniger CPU für das Parsen der Daten benötigen.
- Avro erfordert Schemas, wenn Daten geschrieben oder gelesen werden. Schemas können im Laufe der Zeit weiterentwickelt werden, um das Hinzufügen von Feldern zu behandeln, ohne dass etwas kaputtgeht.
Currents erstellt eine Datei für jeden Ereignistyp 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 Scrollleiste nicht sehen? Erfahren Sie, wie Sie das beheben können, auf der Startseite des Braze User Guide.
Zum Beispiel kann ein Pfad für ein Push-Sendeereignis 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 Currents-Versionswert, wie 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 (zum Beispiel BigQuery-Externtabellen mit Hive-Partitionierung). Wenn Sie Dateien auf diese Weise laden, kann der Partitionsschlüssel version mit Ereignisfeldern in Konflikt geraten, die ebenfalls version heißen, wie z. B. das Feld version in users.messages.inappmessage.Abort-Ereignissen.
Um diesen Konflikt zu vermeiden, richten Sie Ihre Pipeline so ein, dass sie das Pfadsegment version nicht als Spalte behandelt. Sie können den Wert des In-App-Nachricht-Felds version ignorieren. Es handelt sich um ein Legacy-Feld, das ältere 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 die interne Verwendung 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 den Verbindungstyp. Optionen sind „S3“, „AzureBlob“ oder „GCS“. |
<integration-id> |
Die eindeutige ID für diese Currents-Integration. |
<event-type> |
Der Typ des Ereignisses in der Datei. |
<date> |
Die Stunde, in der Ereignisse in unserem System zur Verarbeitung in der UTC-Zeitzone in die Warteschlange eingereiht werden. Formatiert als 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 die interne Verwendung durch Braze. |
<partition> |
Für die interne Verwendung durch Braze. Ganzzahl. |
<offset> |
Für die interne Verwendung durch Braze. Ganzzahl. Beachten Sie, dass verschiedene Dateien, die innerhalb derselben Stunde gesendet werden, einen unterschiedlichen <offset>-Parameter haben. |
Dateibenennungskonventionen können sich ändern. Braze empfiehlt, alle Schlüssel in Ihrem Bucket zu durchsuchen, die ein Präfix von <your-bucket-prefix> haben.
Avro-Schreibschwelle
Unter normalen Umständen schreibt Braze alle 5 Minuten oder alle 15.000 Ereignisse Dateien in Ihren Speicher-Bucket, je nachdem, was zuerst eintritt. Bei hoher Last können wir größere Dateien mit bis zu 100.000 Ereignissen pro Datei schreiben.
Currents schreibt niemals leere Dateien.
Avro-Schemaänderungen
Von Zeit zu Zeit kann Braze Änderungen am Avro-Schema vornehmen, wenn Felder hinzugefügt, geändert oder entfernt werden. Für unsere Zwecke gibt es hier zwei Arten von Änderungen: nicht-brechende und brechende. 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-Ereignisse, 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>
Nicht-brechende Änderungen
Wenn ein Feld zum Avro-Schema hinzugefügt wird, betrachten wir dies als nicht-brechende Änderung. Hinzugefügte Felder sind immer „optionale“ Avro-Felder (z. B. mit einem Standardwert von null), sodass sie gemäß der Avro-Schemaauflösungsspezifikation 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 explizit angibt, welche Felder es verarbeitet, um den Ablauf nicht zu unterbrechen, wenn neue Felder hinzugefügt werden.
Brechende Änderungen
Wenn ein Feld aus dem Avro-Schema entfernt oder geändert wird, betrachten wir dies als brechende Änderung. Brechende Änderungen können Modifikationen an bestehenden ETL-Prozessen erfordern, da Felder, die verwendet wurden, möglicherweise nicht mehr wie erwartet aufgezeichnet werden.
Alle brechenden Änderungen werden im Voraus vor dem Release kommuniziert.
Eine vollständige Änderungshistorie nach Version finden Sie im Currents-Changelog.