Sémantique de livraison des événements
Cette page décrit et définit la manière dont Currents gère les données d’événements sous forme de fichiers plats que nous envoyons aux partenaires de stockage de l’entrepôt de données.
Currents for Data Storage permet un flux continu de données de notre plateforme vers un compartiment de stockage de l’un de nos partenaires d’entrepôt de données. Currents écrit les fichiers Avro dans votre compartiment de stockage à des seuils réguliers, ce qui vous permet de traiter et d’analyser les données d’événements en utilisant vos propres outils d’aide à la décision.
Ce contenu s’applique uniquement aux données d’événements de fichiers plats que nous envoyons aux partenaires de stockage de l’entrepôt de données (Google Cloud Storage, Amazon S3 et Microsoft Azure Blob Storage).
Pour le contenu qui s’applique aux autres partenaires, reportez-vous à notre liste de partenaires disponibles et consultez leurs pages respectives.
Événements de test
Lorsque vous configurez une intégration Currents, cliquez sur Envoyer des événements de test pour vérifier la connexion avec votre compartiment de stockage. Ces événements de test permettent de valider que votre intégration peut recevoir et traiter les données correctement.
Format des données des événements de test : Les événements de test contiennent des valeurs de marque substitutive qui correspondent aux types de données attendus pour chaque champ, mais ils ne contiennent pas de données réalistes ou exactes. Par exemple, un champ timezone peut contenir une chaîne de caractères semblable à un UUID au lieu d’un identifiant de fuseau horaire valide (comme « America/Chicago »), et d’autres champs comme campaign_name et ip_pool peuvent également contenir des valeurs de marque substitutive plutôt que des données réelles.
Ce comportement est normal. Les événements de test servent principalement à tester la connexion et la configuration de l’intégration, et non à valider l’exactitude des données. Pour voir de vrais événements avec des données exactes, utilisez une intégration Currents de test afin d’envoyer des données d’événements réelles dans votre pipeline.
Livraison au moins une fois
En tant que système à haut débit, Currents assure une livraison des événements « au moins une fois », ce qui signifie que des événements en double peuvent parfois être écrits dans votre compartiment de stockage. Cela peut se produire lorsque des événements sont retraités à partir de notre file d’attente, quelle qu’en soit la raison.
Si vos cas d’usage exigent une livraison « exactement une fois », vous pouvez utiliser le champ d’identifiant unique envoyé avec chaque événement (id) pour dédupliquer les événements. Comme le fichier échappe à notre contrôle dès qu’il est écrit dans votre compartiment de stockage, nous n’avons aucun moyen de garantir la déduplication de notre côté.
Horodatages
Tous les horodatages exportés par Currents sont envoyés dans le fuseau horaire UTC. Certains événements incluent aussi, lorsqu’il est disponible, un champ de fuseau horaire qui indique le fuseau horaire local de l’utilisateur au moment de l’événement, au format de l’Internet Assigned Numbers Authority (IANA).
Latence
Les événements envoyés à Braze via le SDK ou l’API peuvent comporter un horodatage passé. C’est notamment le cas lorsque les données du SDK sont mises en file d’attente, par exemple en l’absence de connectivité mobile. L’horodatage de l’événement correspond alors au moment où l’événement a été généré. Une partie des événements semblera donc présenter une latence élevée.
Les SDK Android, Swift et Web de Braze stockent les événements non envoyés sur l’appareil et réessaient de les envoyer une fois l’appareil reconnecté, sans limite de temps. Pour le SDK Web, les événements en file d’attente ne sont limités que par le stockage du navigateur (environ 5 Mo).
Il n’existe pas de fenêtre maximale pour les événements arrivés en retard. Currents est conçu pour exporter chaque événement reçu, quelle que soit l’ancienneté de son horodatage. Un événement arrivé en retard est écrit dans la partition date= correspondant à l’heure à laquelle il a été mis en file d’attente pour traitement dans Braze, et conserve son horodatage d’origine dans le champ time. Braze ne réintègre pas les événements tardifs dans des partitions antérieures.
Comme les événements tardifs arrivent dans les partitions actuelles, Braze recommande de traiter les fichiers au fur et à mesure de leur écriture dans votre compartiment de stockage, plutôt que de réanalyser les anciennes partitions date= avec une fenêtre rétrospective. Pour supprimer les doublons, utilisez le champ id de l’événement, comme décrit dans la section Livraison au moins une fois.
Format Apache Avro
Les intégrations de stockage de données de Braze Currents produisent des données au format .avro. Nous avons choisi Apache Avro parce qu’il s’agit d’un format de données flexible qui prend en charge nativement l’évolution des schémas et qui est compatible avec un large éventail de produits de données :
- Avro est pris en charge par presque tous les grands entrepôts de données.
- Si vous souhaitez conserver vos données dans S3, Avro offre une meilleure compression que CSV et JSON : vous payez donc moins pour le stockage et pouvez potentiellement utiliser moins de CPU pour analyser les données.
- Avro exige des schémas lors de l’écriture ou de la lecture des données. Les schémas peuvent évoluer au fil du temps pour gérer l’ajout de champs sans rien casser.
Currents crée un fichier pour chaque type d’événement selon le format suivant :
<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
Vous ne voyez pas le code à cause de la barre de défilement ? Découvrez comment résoudre ce problème sur la page d’accueil du guide de l’utilisateur de Braze.
Par exemple, le chemin d’un événement d’envoi de notification push peut ressembler à ceci :
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
Le segment de chemin version est une simple valeur entière correspondant à la version de Currents, par exemple version=6.
Le segment de chemin version indique que le schéma des fichiers a changé. Utilisez-le uniquement comme indicateur, et non comme une colonne de données à interroger.
Certains outils lisent les segments de chemin key=value de style Hive, comme version=6, en tant que colonnes de partition (par exemple, les tables externes BigQuery avec partitionnement Hive). Lorsque vous chargez des fichiers de cette façon, la clé de partition version peut entrer en conflit avec des champs d’événement également nommés version, comme le champ version des événements users.messages.inappmessage.Abort.
Pour éviter ce conflit, configurez votre pipeline de sorte qu’il ne traite pas le segment de chemin version comme une colonne. Vous pouvez ignorer la valeur du champ version des messages in-app. Il s’agit d’un ancien champ qui permettait de distinguer les anciens messages in-app, qui ne sont plus utilisés, des messages in-app déclenchés.
| Segment du nom de fichier | Définition |
|---|---|
<your-bucket-prefix> |
Le préfixe défini pour cette intégration Currents. |
<cluster-identifier> |
Réservé à un usage interne par Braze. Il s’agit d’une chaîne de caractères telle que « prod-01 », « prod-02 », « prod-03 » ou « prod-04 ». Tous les fichiers ont le même identifiant de cluster. |
<connection-type-identifier> |
L’identifiant du type de connexion. Les options sont « S3 », « AzureBlob » ou « GCS ». |
<integration-id> |
L’ID unique de cette intégration Currents. Braze définit cet ID lorsque vous créez l’intégration, et il ne change pas lorsque vous modifiez les paramètres de l’intégration (comme les transformations de champs). |
<event-type> |
Le type d’événement contenu dans le fichier. |
<date> |
L’heure à laquelle les événements sont placés dans la file d’attente de notre système pour traitement, dans le fuseau horaire UTC. Au format AAAA-MM-JJ-HH. |
version=<currents_version> |
La version de Currents pour le chemin du pipeline. Cette valeur est un simple entier, par exemple 6. |
<environment> |
Réservé à un usage interne par Braze. |
<partition> |
Réservé à un usage interne par Braze. Entier. |
<offset> |
Réservé à un usage interne par Braze. Entier. Notez que des fichiers différents envoyés au cours de la même heure auront un paramètre <offset> différent. |
Les conventions de nommage des fichiers peuvent changer. Braze recommande de rechercher toutes les clés de votre compartiment ayant le préfixe <your-bucket-prefix>.
Seuil d’écriture Avro
Dans des conditions normales, Braze écrit des fichiers de données dans votre compartiment de stockage toutes les 5 minutes ou tous les 15 000 événements, selon ce qui survient en premier. En cas de forte charge, nous pouvons écrire des fichiers de données plus volumineux contenant jusqu’à 100 000 événements par fichier.
Currents est conçu pour mettre en mémoire tampon en interne d’importants pics d’événements, comme ceux générés par un message envoyé à des millions d’utilisateurs. Vous n’avez pas besoin de prévoir un débit d’écriture ou une capacité d’E/S supplémentaires sur votre compartiment de stockage pour ces pics.
Currents n’écrit jamais de fichiers vides.
Modifications du schéma Avro
Braze peut occasionnellement modifier le schéma Avro lorsque des champs sont ajoutés, modifiés ou supprimés. Dans ce contexte, il existe deux types de modifications : les modifications avec rupture et sans rupture. Toutes les modifications de schéma sont regroupées dans des versions de Currents, et chaque version incrémente le segment version=<currents_version> dans le chemin de stockage (par exemple, de version=6 à version=7). Les événements Currents écrits dans Azure Blob Storage, Google Cloud Storage et Amazon S3 utilisent le format de chemin suivant :
<your-bucket-prefix>/<currents-integration-id>/event_type=<event-type>/date=<date>/version=<currents_version>/<environment>/<avro-file>
Modifications sans rupture
Lorsqu’un champ est ajouté au schéma Avro, nous considérons qu’il s’agit d’une modification sans rupture. Les champs ajoutés sont toujours des champs Avro « facultatifs » (par exemple avec une valeur par défaut de null), ils « correspondent » donc aux anciens schémas conformément à la spécification de résolution des schémas Avro. Ces ajouts ne devraient pas affecter les processus ETL (extraire, transformer, charger) existants, car le champ sera simplement ignoré jusqu’à ce que vous l’ajoutiez à votre processus ETL.
Nous vous recommandons de configurer votre processus ETL de manière à ce qu’il spécifie explicitement les champs qu’il traite, afin d’éviter toute interruption du flux lors de l’ajout de nouveaux champs.
Modifications avec rupture
Lorsqu’un champ est supprimé ou modifié dans le schéma Avro, nous considérons qu’il s’agit d’une modification avec rupture. Les modifications avec rupture peuvent nécessiter d’adapter les processus ETL existants, car des champs utilisés pourraient ne plus être enregistrés comme prévu.
Toutes les modifications avec rupture sont communiquées avant la publication de la version.
Pour consulter l’historique complet des modifications par version, reportez-vous au journal des modifications de Currents.